Sinch Python SDK for Numbers

The Sinch Numbers Python SDK allows you to quickly interact with the Numbers API from inside your Python applications. The fastest way to get started with the SDK is to check out our getting started guides. There you'll find all the instructions necessary to download, install, set up, and start using the SDK.

Syntax

When using the Python SDK, the code representing requests and queries sent to and responses received from the Numbers API are structured similarly to those that are sent and received using the Numbers API itself.

from sinch import SinchClient

sinch_client = SinchClient(
    key_id="YOUR_key_id",
    key_secret="YOUR_key_secret",
    project_id="YOUR_project_id"
)

available_numbers_response = sinch_client.numbers.available.list(
    region_code="YOUR_region_code",
    number_type="YOUR_number_type"
)

print(available_numbers_response)

The code sample on the side of this page is an example of how to use the Python SDK to list the available numbers given a set of constraints. The Numbers API call that accomplishes the same task is displayed below for reference:

import requests

project_id = "YOUR_project_id"
url = "https://numbers.api.sinch.com/v1/projects/" + project_id + "/availableNumbers"

query = {
  "regionCode": "US",
  "type": "LOCAL"
}

response = requests.get(url, params=query, auth=('<username>','<password>'))

data = response.json()
print(data)

This example highlights the following required to successfully make a Numbers API call using the Sinch Python SDK:

• Client initialization
• Numbers domain access
• Endpoint usage
• Field population

Client

When using the Sinch Python SDK, you initialize communication with the Sinch backend by initializing the Python SDK's main client class. This client allows you to access the the functionality of the Sinch Python SDK.

Initialization

To successfully initialize the Sinch client class, you must provide a valid access key ID and access key secret combination. You must also provide your Project ID. For example:

from sinch import SinchClient

sinch_client = SinchClient(
    key_id="YOUR_key_id",
    key_secret="YOUR_key_secret",
    project_id="YOUR_project_id"
)

Configuration

After intializing the client, you can modify the following Numbers properties using the configuration class:

Numbers domain

from sinch import SinchClient

sinch_client = SinchClient(key_id="YOUR_key_id", key_secret="YOUR_key_secret",
project_id="YOUR_project_id")

from sinch.domains.numbers import Numbers

numbers_client = Numbers(sinch_client)

Endpoint categories

In the Sinch Python SDK, Numbers API endpoints are accessible through the client (either a general client or a Numbers-specific client). The naming convention of the endpoint's representation in the SDK matches the API:

• available
• active
• regions

For example:

numbers_available = sinch_client.numbers.available.list(
    region_code="US",
    number_type="LOCAL"
)

available endpoint category

active endpoint category

regions endpoint category

Request and query parameters

Requests and queries made using the Python SDK are similar to those made using the Numbers API. Many of the fields are named and structured similarly. For example, consider the representations of a Numbers API region code. One field is represented in JSON, and the other is using our Python SDK:

region_code = "US"

"regionCode": "US"

Note that the fields are nearly the same. Additionally, path parameters, request body parameters, and query parameters that are used in the API are all passed as arguments to the corresponding Python method.

Field name differences

When translating field names from the Numbers API to the Python SDK, remember that many of the API field names are in camelCase, whereas the Python SDK field names are in snake_case. This pattern change manages almost all field name translations between the API and the SDK.

Below is a table detailing field names present in the Numbers API and their modified counterparts in the Numbers API Python SDK:

Nested objects

When making calls directly to the API, we use JSON objects, including (in some cases) nested JSON objects. When using the Python SDK, we use dictionaries instead of nested JSON objects. For example, consider the sms configuration objects below. One is represented in JSON, the other as a Python dictionary:

sms_configuration = {
    "servicePlanId": "service_plan_string"
}

"smsConfiguration": {
    "servicePlanId": "service_plan_string"
}

Responses

Response fields match the API responses. They are delivered as Python objects, with each top-level field represented as a property. Note that any nested objects normally returned by the Numbers API are returned as dictionaries by the Python SDK. Additionally, if there are any responses that differ significantly from the API responses, we note them in the endpoint category documentation.