sinch.domains.numbers.virtual_numbers module

class sinch.domains.numbers.virtual_numbers.VirtualNumbers(sinch)[source]

Bases: object

Synchronous version of the Numbers domain.

Documentation for Sinch virtual Numbers is found at https://developers.sinch.com/docs/numbers/.

sinch_events(
callback_secret: str,
) → SinchEvents[source]

Create a Numbers Sinch Events handler with the specified callback secret.

Parameters:

callback_secret (str) – Secret used for webhook validation.

Returns:

A configured Sinch Events handler

Return type:

SinchEvents

list(
region_code: str | None = None,
number_type: Literal['MOBILE', 'LOCAL', 'TOLL_FREE'] | Annotated[str, Strict(strict=True)] | None = None,
number_pattern: str | None = None,
number_search_pattern: Literal['START', 'CONTAINS', 'END'] | Annotated[str, Strict(strict=True)] | None = None,
capabilities: List[Literal['SMS', 'VOICE'] | Annotated[str, Strict(strict=True)]] | None = None,
page_size: int | None = None,
page_token: str | None = None,
order_by: Literal['PHONE_NUMBER', 'DISPLAY_NAME'] | Annotated[str, Strict(strict=True)] | None = None,
**kwargs,
) → Paginator[ActiveNumber][source]

Search for all active virtual numbers associated with a certain project.

Parameters:

  • region_code (Optional[str]) – Optional. ISO 3166-1 alpha-2 country code. Example: US, GB or SE.

  • number_type (Optional[NumberType]) – Optional. Type of number (e.g., “MOBILE”, “LOCAL”, “TOLL_FREE”).

  • number_pattern (Optional[str]) – Specific sequence of digits to search for.

  • number_search_pattern (Optional[NumberSearchPatternType]) – Pattern to apply (e.g., “START”, “CONTAINS”, “END”).

  • capabilities (Optional[List[CapabilityType]]) – Capabilities required for the number (e.g., [“SMS”, “VOICE”]).

  • page_size (int) – Maximum number of items to return.

  • page_token (Optional[str]) – Token for the next page of results.

  • order_by (Optional[OrderByType]) – Field to order the results by (e.g., “phoneNumber”, “displayName”).

  • kwargs (dict) – Additional filters for the request.

Returns:

A paginator for iterating through the results.

Return type:

Paginator[ActiveNumber]

For detailed documentation, visit https://developers.sinch.com

update(
phone_number: str,
sms_configuration: SmsConfigurationDict,
voice_configuration: VoiceConfigurationESTDict,
display_name: str | None = None,
event_destination_target: str | None = None,
) → ActiveNumber[source]
update(
phone_number: str,
sms_configuration: SmsConfigurationDict,
voice_configuration: VoiceConfigurationFAXDict,
display_name: str | None = None,
event_destination_target: str | None = None,
) → ActiveNumber
update(
phone_number: str,
sms_configuration: SmsConfigurationDict,
voice_configuration: VoiceConfigurationRTCDict,
display_name: str | None = None,
event_destination_target: str | None = None,
) → ActiveNumber

Make updates to the configuration of your virtual number. Update the display name, change the currency type, or reconfigure for either SMS and/or Voice.

Parameters:

  • phone_number (str) – Phone number in E.164 format with leading ‘+’. Example: ‘+12025550134’.

  • display_name (Optional[str]) – The display name for the virtual number.

  • sms_configuration (Optional[SmsConfigurationDict]) – A dictionary defining the SMS configuration, including fields such as: service_plan_id (str), campaign_id (optional, required for US 10DLC).

  • voice_configuration (Optional[VoiceConfigurationDict]) – A dictionary defining the Voice configuration. Supported types include:: - VoiceConfigurationRTCDict: type 'RTC' with an app_id field. - VoiceConfigurationESTDict: type 'EST' with a trunk_id field. - VoiceConfigurationFAXDict: type 'FAX' with a service_id field.

  • event_destination_target (Optional[str]) – The event destination URL for the virtual number.

  • kwargs (dict) – Additional parameters for the request.

Return type:

ActiveNumber

For detailed documentation, visit https://developers.sinch.com

get(
phone_number: str,
**kwargs,
) → ActiveNumber[source]

Get the configuration settings for your virtual number.

Parameters:

  • phone_number (str) – Phone number in E.164 format with leading ‘+’. Example: ‘+12025550134’.

  • kwargs (dict) – Additional parameters for the request.

Returns:

The configuration settings for the virtual number.

Return type:

ActiveNumber

For detailed documentation, visit https://developers.sinch.com

release(
phone_number: str,
**kwargs,
) → ActiveNumber[source]

Release virtual numbers you no longer need from your project.

Parameters:

  • phone_number (str) – Phone number in E.164 format with leading ‘+’. Example: ‘+12025550134’.

  • kwargs (dict) – Additional parameters for the request.

Returns:

The configuration settings of the released virtual number.

Return type:

ActiveNumber

For detailed documentation, visit https://developers.sinch.com

check_availability(
phone_number: str,
**kwargs,
) → AvailableNumber[source]

Enter a specific phone number to check availability.

Parameters:

  • phone_number (str) – Phone number in E.164 format with leading ‘+’. Example: ‘+12025550134’.

  • kwargs (dict) – Additional parameters for the request.

Returns:

A response object with the availability status of the number.

Return type:

AvailableNumber

For detailed documentation, visit: https://developers.sinch.com

rent(
phone_number: str,
sms_configuration: SmsConfigurationDict,
voice_configuration: VoiceConfigurationESTDict,
event_destination_target: str | None = None,
) → ActiveNumber[source]
rent(
phone_number: str,
sms_configuration: SmsConfigurationDict,
voice_configuration: VoiceConfigurationFAXDict,
event_destination_target: str | None = None,
) → ActiveNumber
rent(
phone_number: str,
sms_configuration: SmsConfigurationDict,
voice_configuration: VoiceConfigurationRTCDict,
event_destination_target: str | None = None,
) → ActiveNumber

Rent a virtual number to use with SMS, Voice, or both products.

Parameters:

  • phone_number (str) – Phone number in E.164 format with leading ‘+’. Example: ‘+12025550134’.

  • sms_configuration (Optional[SmsConfigurationDict]) – A dictionary defining the SMS configuration, including fields such as: service_plan_id (str), campaign_id (optional, required for US 10DLC).

  • voice_configuration (Optional[VoiceConfigurationDict]) – A dictionary defining the Voice configuration. Supported types include:: - VoiceConfigurationRTCDict: type 'RTC' with an app_id field. - VoiceConfigurationESTDict: type 'EST' with a trunk_id field. - VoiceConfigurationFAXDict: type 'FAX' with a service_id field.

  • event_destination_target (Optional[str]) – The event destination URL to be called.

  • kwargs (dict) – Additional parameters for the request.

Returns:

A response object with the rented number and its details.

Return type:

ActiveNumber

For detailed documentation, visit https://developers.sinch.com

rent_any(
region_code: str,
number_type: Literal['MOBILE', 'LOCAL', 'TOLL_FREE'] | Annotated[str, Strict(strict=True)],
sms_configuration: SmsConfigurationDict,
voice_configuration: VoiceConfigurationRTCDict,
number_pattern: NumberPatternDict,
capabilities: Literal['SMS', 'VOICE'] | Annotated[str, Strict(strict=True)] | None = None,
event_destination_target: str | None = None,
) → ActiveNumber[source]
rent_any(
region_code: str,
number_type: Literal['MOBILE', 'LOCAL', 'TOLL_FREE'] | Annotated[str, Strict(strict=True)],
sms_configuration: SmsConfigurationDict,
voice_configuration: VoiceConfigurationFAXDict,
number_pattern: NumberPatternDict,
capabilities: List[Literal['SMS', 'VOICE'] | Annotated[str, Strict(strict=True)]] | None = None,
event_destination_target: str | None = None,
) → ActiveNumber
rent_any(
region_code: str,
number_type: Literal['MOBILE', 'LOCAL', 'TOLL_FREE'] | Annotated[str, Strict(strict=True)],
sms_configuration: SmsConfigurationDict,
voice_configuration: VoiceConfigurationESTDict,
number_pattern: NumberPatternDict,
capabilities: List[Literal['SMS', 'VOICE'] | Annotated[str, Strict(strict=True)]] | None = None,
event_destination_target: str | None = None,
) → ActiveNumber

Search for and activate an available Sinch virtual number all in one API call. Currently, the rent_any operation works only for US 10DLC numbers.

Parameters:

  • region_code (str) – ISO 3166-1 alpha-2 country code. Example: US, GB or SE.

  • number_type (NumberType) – Type of number (e.g., "MOBILE", "LOCAL", "TOLL_FREE"). Defaults to "MOBILE".

  • number_pattern (Optional[NumberPatternDict]) – Optional dict with pattern (str) and search_pattern (e.g., "START", "CONTAINS", "END").

  • capabilities (Optional[List[CapabilityType]]) – Capabilities required for the number (e.g., ["SMS", "VOICE"]).

  • sms_configuration (Optional[SmsConfigurationDict]) – A dictionary defining the SMS configuration, including fields such as: service_plan_id (str), campaign_id (optional, required for US 10DLC).

  • voice_configuration (Optional[VoiceConfigurationDict]) – A dictionary defining the Voice configuration. Supported types include:: - VoiceConfigurationRTCDict: type 'RTC' with an app_id field. - VoiceConfigurationESTDict: type 'EST' with a trunk_id field. - VoiceConfigurationFAXDict: type 'FAX' with a service_id field.

  • event_destination_target (Optional[str]) – The event destination URL to receive notifications.

  • kwargs (dict) – Additional parameters for the request.

Returns:

A response object with the activated number and its details.

Return type:

ActiveNumber

For detailed documentation, visit: https://developers.sinch.com

search_for_available_numbers(
region_code: str,
number_type: Literal['MOBILE', 'LOCAL', 'TOLL_FREE'] | Annotated[str, Strict(strict=True)],
number_pattern: str | None = None,
number_search_pattern: Literal['START', 'CONTAINS', 'END'] | Annotated[str, Strict(strict=True)] | None = None,
capabilities: List[Literal['SMS', 'VOICE'] | Annotated[str, Strict(strict=True)]] | None = None,
page_size: int | None = None,
**kwargs,
) → Paginator[AvailableNumber][source]

Search for available virtual numbers for you to rent using a variety of parameters to filter results.

Parameters:

  • region_code (str) – ISO 3166-1 alpha-2 country code. Example: US, GB or SE.

  • number_type (NumberType) – Type of number (e.g., "MOBILE", "LOCAL", "TOLL_FREE").

  • number_pattern (Optional[str]) – Specific sequence of digits to search for.

  • number_search_pattern (Optional[NumberSearchPatternType]) – Pattern to apply (e.g., "START", "CONTAINS", "END").

  • capabilities (Optional[List[CapabilityType]]) – Capabilities required for the number (e.g., ["SMS", "VOICE"]).

  • page_size (int) – Maximum number of items to return.

  • kwargs (dict) – Additional filters for the request.

Returns:

A paginator for iterating through the results.

Return type:

Paginator[AvailableNumber]

For detailed documentation, visit: https://developers.sinch.com