Installation
pip install telnyx
Setup
import os
from telnyx import Telnyx
client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted )
All examples below assume `client` is already initialized as shown above.
## 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:
```python
import telnyx
try:
result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello")
except telnyx.APIConnectionError:
print("Network error — check connectivity and retry")
except telnyx.RateLimitError:
# 429: rate limited — wait and retry with exponential backoff
import time
time.sleep(1) # Check Retry-After header for actual delay
except telnyx.APIStatusError as e:
print(f"API error {e.status_code}: {e.message}")
if e.status_code == 422:
print("Validation error — check required fields and formats")
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 methods return an auto-paginating iterator. Use
for item in page_result:to iterate through all pages automatically.
List all Access IP Addresses
GET /access_ip_address
page = client.access_ip_address.list()
page = page.data[0]
print(page.id)
Returns: created_at (date-time), description (string), id (string), ip_address (string), source (string), status (enum: pending, added), updated_at (date-time), user_id (string)
Create new Access IP Address
POST /access_ip_address — Required: ip_address
Optional: description (string)
access_ip_address_response = client.access_ip_address.create(
ip_address="203.0.113.10",
)
print(access_ip_address_response.id)
Returns: created_at (date-time), description (string), id (string), ip_address (string), source (string), status (enum: pending, added), updated_at (date-time), user_id (string)
Retrieve an access IP address
GET /access_ip_address/{access_ip_address_id}
access_ip_address_response = client.access_ip_address.retrieve(
"access_ip_address_id",
)
print(access_ip_address_response.id)
Returns: created_at (date-time), description (string), id (string), ip_address (string), source (string), status (enum: pending, added), updated_at (date-time), user_id (string)
Delete access IP address
DELETE /access_ip_address/{access_ip_address_id}
access_ip_address_response = client.access_ip_address.delete(
"access_ip_address_id",
)
print(access_ip_address_response.id)
Returns: created_at (date-time), description (string), id (string), ip_address (string), source (string), status (enum: pending, added), updated_at (date-time), user_id (string)
List all addresses
Returns a list of your addresses.
GET /addresses
page = client.addresses.list()
page = page.data[0]
print(page.id)
Returns: address_book (boolean), administrative_area (string), borough (string), business_name (string), country_code (string), created_at (string), customer_reference (string), extended_address (string), first_name (string), id (string), last_name (string), locality (string), neighborhood (string), phone_number (string), postal_code (string), record_type (string), street_address (string), updated_at (string), validate_address (boolean)
Creates an address
Creates an address.
POST /addresses — Required: first_name, last_name, business_name, street_address, locality, country_code
Optional: address_book (boolean), administrative_area (string), borough (string), customer_reference (string), extended_address (string), neighborhood (string), phone_number (string), postal_code (string), validate_address (boolean)
address = client.addresses.create(
business_name="Toy-O'Kon",
country_code="US",
first_name="Alfred",
last_name="Foster",
locality="Austin",
street_address="600 Congress Avenue",
)
print(address.data)
Returns: address_book (boolean), administrative_area (string), borough (string), business_name (string), country_code (string), created_at (string), customer_reference (string), extended_address (string), first_name (string), id (string), last_name (string), locality (string), neighborhood (string), phone_number (string), postal_code (string), record_type (string), street_address (string), updated_at (string), validate_address (boolean)
Validate an address
Validates an address for emergency services.
POST /addresses/actions/validate — Required: country_code, street_address, postal_code
Optional: administrative_area (string), extended_address (string), locality (string)
response = client.addresses.actions.validate(
country_code="US",
postal_code="78701",
street_address="600 Congress Avenue",
)
print(response.data)
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}
address = client.addresses.retrieve(
"id",
)
print(address.data)
Returns: address_book (boolean), administrative_area (string), borough (string), business_name (string), country_code (string), created_at (string), customer_reference (string), extended_address (string), first_name (string), id (string), last_name (string), locality (string), neighborhood (string), phone_number (string), postal_code (string), record_type (string), street_address (string), updated_at (string), validate_address (boolean)
Deletes an address
Deletes an existing address.
DELETE /addresses/{id}
address = client.addresses.delete(
"id",
)
print(address.data)
Returns: address_book (boolean), administrative_area (string), borough (string), business_name (string), country_code (string), created_at (string), customer_reference (string), extended_address (string), first_name (string), id (string), last_name (string), locality (string), neighborhood (string), phone_number (string), postal_code (string), record_type (string), street_address (string), updated_at (string), validate_address (boolean)
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)
response = client.addresses.actions.accept_suggestions(
address_uuid="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: accepted (boolean), id (uuid), record_type (enum: address_suggestion)
List all SSO authentication providers
Returns a list of your SSO authentication providers.
GET /authentication_providers
page = client.authentication_providers.list()
page = page.data[0]
print(page.id)
Returns: activated_at (date-time), active (boolean), created_at (date-time), id (uuid), name (string), organization_id (uuid), record_type (string), settings (object), short_name (string), updated_at (date-time)
Creates an authentication provider
Creates an authentication provider.
POST /authentication_providers — Required: name, short_name, settings
Optional: active (boolean), settings_url (uri)
authentication_provider = client.authentication_providers.create(
name="Okta",
settings={
"idp_cert_fingerprint": "13:38:C7:BB:C9:FF:4A:70:38:3A:E3:D9:5C:CD:DB:2E:50:1E:80:A7",
"idp_entity_id": "https://myorg.myidp.com/saml/metadata",
"idp_sso_target_url": "https://myorg.myidp.com/trust/saml2/http-post/sso",
},
short_name="myorg",
)
print(authentication_provider.data)
Returns: activated_at (date-time), active (boolean), created_at (date-time), id (uuid), name (string), organization_id (uuid), record_type (string), settings (object), short_name (string), updated_at (date-time)
Retrieve an authentication provider
Retrieves the details of an existing authentication provider.
GET /authentication_providers/{id}
authentication_provider = client.authentication_providers.retrieve(
"id",
)
print(authentication_provider.data)
Returns: activated_at (date-time), active (boolean), created_at (date-time), id (uuid), name (string), organization_id (uuid), record_type (string), settings (object), short_name (string), updated_at (date-time)
Update an authentication provider
Updates settings of an existing authentication provider.
PATCH /authentication_providers/{id}
Optional: active (boolean), name (string), settings (object), settings_url (uri), short_name (string)
authentication_provider = client.authentication_providers.update(
id="550e8400-e29b-41d4-a716-446655440000",
active=True,
name="Okta",
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",
},
short_name="myorg",
)
print(authentication_provider.data)
Returns: activated_at (date-time), active (boolean), created_at (date-time), id (uuid), name (string), organization_id (uuid), record_type (string), settings (object), short_name (string), updated_at (date-time)
Deletes an authentication provider
Deletes an existing authentication provider.
DELETE /authentication_providers/{id}
authentication_provider = client.authentication_providers.delete(
"id",
)
print(authentication_provider.data)
Returns: activated_at (date-time), active (boolean), created_at (date-time), id (uuid), name (string), organization_id (uuid), record_type (string), settings (object), short_name (string), updated_at (date-time)
List all billing groups
GET /billing_groups
page = client.billing_groups.list()
page = page.data[0]
print(page.id)
Returns: created_at (date-time), deleted_at (date-time), id (uuid), name (string), organization_id (uuid), record_type (enum: billing_group), updated_at (date-time)
Create a billing group
POST /billing_groups
Optional: name (string)
billing_group = client.billing_groups.create(
name="my-resource",
)
print(billing_group.data)
Returns: created_at (date-time), deleted_at (date-time), id (uuid), name (string), organization_id (uuid), record_type (enum: billing_group), updated_at (date-time)
Get a billing group
GET /billing_groups/{id}
billing_group = client.billing_groups.retrieve(
"f5586561-8ff0-4291-a0ac-84fe544797bd",
)
print(billing_group.data)
Returns: created_at (date-time), deleted_at (date-time), id (uuid), name (string), organization_id (uuid), record_type (enum: billing_group), updated_at (date-time)
Update a billing group
PATCH /billing_groups/{id}
Optional: name (string)
billing_group = client.billing_groups.update(
id="f5586561-8ff0-4291-a0ac-84fe544797bd",
name="my-resource",
)
print(billing_group.data)
Returns: created_at (date-time), deleted_at (date-time), id (uuid), name (string), organization_id (uuid), record_type (enum: billing_group), updated_at (date-time)
Delete a billing group
DELETE /billing_groups/{id}
billing_group = client.billing_groups.delete(
"f5586561-8ff0-4291-a0ac-84fe544797bd",
)
print(billing_group.data)
Returns: created_at (date-time), deleted_at (date-time), id (uuid), name (string), organization_id (uuid), record_type (enum: billing_group), updated_at (date-time)
List integration secrets
Retrieve a list of all integration secrets configured by the user.
GET /integration_secrets
page = client.integration_secrets.list()
page = page.data[0]
print(page.id)
Returns: created_at (date-time), id (string), identifier (string), record_type (string), updated_at (date-time)
Create a secret
Create a new secret with an associated identifier that can be used to securely integrate with other services.
POST /integration_secrets — Required: identifier, type
Optional: password (string), token (string), username (string)
integration_secret = client.integration_secrets.create(
identifier="my_secret",
type="bearer",
token="my_secret_value",
)
print(integration_secret.data)
Returns: created_at (date-time), id (string), identifier (string), record_type (string), updated_at (date-time)
Delete an integration secret
Delete an integration secret given its ID.
DELETE /integration_secrets/{id}
client.integration_secrets.delete(
"id",
)
Create an Access Token.
Create an Access Token (JWT) for the credential.
POST /telephony_credentials/{id}/token
response = client.telephony_credentials.create_token(
"id",
)
print(response)