Telnyx Account Access - curl

Installation

# curl is pre-installed on macOS, Linux, and Windows 10+

Setup

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

All examples below use $TELNYXAPIKEY for authentication.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

# Check HTTP status code in response
response=$(curl -s -w "\n%{http_code}" \
  -X POST "https://api.telnyx.com/v2/messages" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+13125550001", "from": "+13125550002", "text": "Hello"}')

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

case $http_code in
  2*) echo "Success: $body" ;;
  422) echo "Validation error — check required fields and formats" ;;
  429) echo "Rate limited — retry after delay"; sleep 1 ;;
  401) echo "Authentication failed — check TELNYX_API_KEY" ;;
  *)   echo "Error $http_code: $body" ;;
esac

Common error codes: 401 invalid API key, 403 insufficient permissions, 404 resource not found, 422 validation error (check field formats), 429 rate limited (retry with exponential backoff).

Important Notes

Pagination: List endpoints return paginated results. Use page[number] and page[size] query parameters to navigate pages. Check meta.total_pages in the response.

List all Access IP Addresses

GET /accessipaddress

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/access_ip_address"

Returns: createdat (date-time), description (string), id (string), ipaddress (string), source (string), status (enum: pending, added), updatedat (date-time), userid (string)

Create new Access IP Address

POST /accessipaddress — Required: ip_address

Optional: description (string)

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ip_address": "203.0.113.10"
}' \
  "https://api.telnyx.com/v2/access_ip_address"

Returns: createdat (date-time), description (string), id (string), ipaddress (string), source (string), status (enum: pending, added), updatedat (date-time), userid (string)

Retrieve an access IP address

GET /accessipaddress/{accessipaddress_id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/access_ip_address/{access_ip_address_id}"

Returns: createdat (date-time), description (string), id (string), ipaddress (string), source (string), status (enum: pending, added), updatedat (date-time), userid (string)

Delete access IP address

DELETE /accessipaddress/{accessipaddress_id}

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/access_ip_address/{access_ip_address_id}"

Returns: createdat (date-time), description (string), id (string), ipaddress (string), source (string), status (enum: pending, added), updatedat (date-time), userid (string)

List all addresses

Returns a list of your addresses.

GET /addresses

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/addresses?sort=street_address"

Returns: addressbook (boolean), administrativearea (string), borough (string), businessname (string), countrycode (string), createdat (string), customerreference (string), extendedaddress (string), firstname (string), id (string), lastname (string), locality (string), neighborhood (string), phonenumber (string), postalcode (string), recordtype (string), streetaddress (string), updatedat (string), validate_address (boolean)

Creates an address

Creates an address.

POST /addresses — Required: firstname, lastname, businessname, streetaddress, locality, country_code

Optional: addressbook (boolean), administrativearea (string), borough (string), customerreference (string), extendedaddress (string), neighborhood (string), phonenumber (string), postalcode (string), validate_address (boolean)

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Alfred",
  "last_name": "Foster",
  "business_name": "Toy-O'Kon",
  "street_address": "600 Congress Avenue",
  "locality": "Austin",
  "country_code": "US"
}' \
  "https://api.telnyx.com/v2/addresses"

Validate an address

Validates an address for emergency services.

POST /addresses/actions/validate — Required: countrycode, streetaddress, postal_code

Optional: administrativearea (string), extendedaddress (string), locality (string)

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "street_address": "600 Congress Avenue",
  "postal_code": "78701",
  "country_code": "US"
}' \
  "https://api.telnyx.com/v2/addresses/actions/validate"

Returns: errors (array[object]), record_type (string), result (enum: valid, invalid), suggested (object)

Retrieve an address

Retrieves the details of an existing address.

GET /addresses/{id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/addresses/550e8400-e29b-41d4-a716-446655440000"

Deletes an address

Deletes an existing address.

DELETE /addresses/{id}

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/addresses/550e8400-e29b-41d4-a716-446655440000"

Accepts this address suggestion as a new emergency address for Operator Connect and finishes the uploads of the numbers associated with it to Microsoft.

POST /addresses/{id}/actions/accept_suggestions

Optional: id (string)

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/addresses/550e8400-e29b-41d4-a716-446655440000/actions/accept_suggestions"

Returns: accepted (boolean), id (uuid), recordtype (enum: addresssuggestion)

List all SSO authentication providers

Returns a list of your SSO authentication providers.

GET /authentication_providers

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/authentication_providers?sort=name"

Returns: activatedat (date-time), active (boolean), createdat (date-time), id (uuid), name (string), organizationid (uuid), recordtype (string), settings (object), shortname (string), updatedat (date-time)

Creates an authentication provider

Creates an authentication provider.

POST /authenticationproviders — Required: name, shortname, settings

Optional: active (boolean), settings_url (uri)

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Okta",
  "short_name": "myorg",
  "settings": {}
}' \
  "https://api.telnyx.com/v2/authentication_providers"

Retrieve an authentication provider

Retrieves the details of an existing authentication provider.

GET /authentication_providers/{id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/authentication_providers/550e8400-e29b-41d4-a716-446655440000"

Update an authentication provider

Updates settings of an existing authentication provider.

PATCH /authentication_providers/{id}

Optional: active (boolean), name (string), settings (object), settingsurl (uri), shortname (string)

curl \
  -X PATCH \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Okta",
  "short_name": "myorg",
  "active": true,
  "settings": {
    "idp_entity_id": "https://myorg.myidp.com/saml/metadata",
    "idp_sso_target_url": "https://myorg.myidp.com/trust/saml2/http-post/sso",
    "idp_cert_fingerprint": "13:38:C7:BB:C9:FF:4A:70:38:3A:E3:D9:5C:CD:DB:2E:50:1E:80:A7",
    "idp_cert_fingerprint_algorithm": "sha1"
  }
}' \
  "https://api.telnyx.com/v2/authentication_providers/550e8400-e29b-41d4-a716-446655440000"

Deletes an authentication provider

Deletes an existing authentication provider.

DELETE /authentication_providers/{id}

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/authentication_providers/550e8400-e29b-41d4-a716-446655440000"