phone_numbers

Creates, updates, deletes, gets or lists a phone_numbers resource.

Overview

Name	phone_numbers
Type	Resource
Id	azure.communication_phone_numbers.phone_numbers

Fields

The following fields are returned by SELECT queries:

search_available_phone_numbers

Name	Datatype	Description
assignmentType	string	Phone number's assignment type. Required. Known values are: "person" and "application".
capabilities	object	Capabilities of a phone number. Required.
cost	object	The incurred cost for a single phone number. Required.
error	string	Mapping Error Messages to Codes. Known values are: "NoError", "UnknownErrorCode", "OutOfStock", "AuthorizationDenied", "MissingAddress", "InvalidAddress", "InvalidOfferModel", "NotEnoughLicenses", "NoWallet", "NotEnoughCredit", "NumbersPartiallyAcquired", "AllNumbersNotAcquired", "ReservationExpired", "PurchaseFailed", "BillingUnavailable", "ProvisioningFailed", and "UnknownSearchError".
errorCode	integer	The error code of the search.
isAgreementToNotResellRequired	boolean	Indicates if do not resell agreement is required. If true, the phone numbers cannot be acquired unless the customer provides explicit agreement to not resell them.
phoneNumberType	string	The phone number's type, e.g. geographic, tollFree, mobile. Required. Known values are: "geographic", "tollFree", and "mobile".
phoneNumbers	array	The phone numbers that are available. Can be fewer than the desired search quantity. Required.
searchExpiresBy	string (date-time)	The date that this search result expires and phone numbers are no longer on hold. A search result expires in less than 15min, e.g. 2020-11-19T16:31:49.048Z. Required.
searchId	string	The search id. Required.

list_area_codes

Name	Datatype	Description
areaCode	string	An area code.

list_available_localities

Name	Datatype	Description
administrativeDivision	object	Represents an administrative division. e.g. state or province.
localizedName	string	Represents the localized name of the locality. Required.

get_by_number

Name	Datatype	Description
id	string	The id of the phone number, e.g. 11234567890. Required.
assignmentType	string	The assignment type of the phone number. A phone number can be assigned to a person, or to an application. Required. Known values are: "person" and "application".
capabilities	object	Capabilities of a phone number. Required.
cost	object	The incurred cost for a single phone number. Required.
countryCode	string	The ISO 3166-2 code of the phone number's country, e.g. US. Required.
phoneNumber	string	String of the E.164 format of the phone number, e.g. +11234567890. Required.
phoneNumberType	string	The phone number's type, e.g. geographic, tollFree, mobile. Required. Known values are: "geographic", "tollFree", and "mobile".
purchaseDate	string (date-time)	The date and time that the phone number was purchased. Required.

get_reservation

Name	Datatype	Description
id	string	The id of the reservation.
expiresAt	string (date-time)	The time at which the reservation will expire. If a reservation is not purchased before this time, all of the reserved phone numbers will be released and made available for others to purchase.
phoneNumbers	object	A dictionary containing the reservation phone numbers. The key is the ID of the phone number (digits only) and values are AvailablePhoneNumber objects. Not populated when retrieving PhoneNumbersReservation collections.
status	string	Represents the status of the reservation. Possible values include: 'active', 'submitted', 'completed', 'expired'. Known values are: "active", "submitted", "completed", and "expired".

get_search_result

Name	Datatype	Description
assignmentType	string	Phone number's assignment type. Required. Known values are: "person" and "application".
capabilities	object	Capabilities of a phone number. Required.
cost	object	The incurred cost for a single phone number. Required.
error	string	Mapping Error Messages to Codes. Known values are: "NoError", "UnknownErrorCode", "OutOfStock", "AuthorizationDenied", "MissingAddress", "InvalidAddress", "InvalidOfferModel", "NotEnoughLicenses", "NoWallet", "NotEnoughCredit", "NumbersPartiallyAcquired", "AllNumbersNotAcquired", "ReservationExpired", "PurchaseFailed", "BillingUnavailable", "ProvisioningFailed", and "UnknownSearchError".
errorCode	integer	The error code of the search.
isAgreementToNotResellRequired	boolean	Indicates if do not resell agreement is required. If true, the phone numbers cannot be acquired unless the customer provides explicit agreement to not resell them.
phoneNumberType	string	The phone number's type, e.g. geographic, tollFree, mobile. Required. Known values are: "geographic", "tollFree", and "mobile".
phoneNumbers	array	The phone numbers that are available. Can be fewer than the desired search quantity. Required.
searchExpiresBy	string (date-time)	The date that this search result expires and phone numbers are no longer on hold. A search result expires in less than 15min, e.g. 2020-11-19T16:31:49.048Z. Required.
searchId	string	The search id. Required.

get_operation

Name	Datatype	Description
id	string	Id of operation. Required.
createdDateTime	string (date-time)	The date that the operation was created. Required.
error	object	The Communication Services error.
lastActionDateTime	string (date-time)	The most recent date that the operation was changed.
operationType	string	The type of operation, e.g. Search. Required. Known values are: "purchase", "releasePhoneNumber", "search", "updatePhoneNumberCapabilities", and "reservationPurchase".
resourceLocation	string	URL for retrieving the result of the operation, if any.
status	string	Status of operation. Required. Known values are: "notStarted", "running", "succeeded", and "failed".

list_available_countries

Name	Datatype	Description
countryCode	string	Represents the abbreviated name of the country. Required.
localizedName	string	Represents the name of the country. Required.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
search_available_phone_numbers	select	country_code, endpoint		Search for available phone numbers to purchase. Search for available phone numbers to purchase.
list_area_codes	select	country_code, phoneNumberType, endpoint	skip, maxPageSize, assignmentType, locality, administrativeDivision, accept-language	Gets the list of available area codes. Gets the list of available area codes.
list_available_localities	select	country_code, endpoint	skip, maxPageSize, administrativeDivision, accept-language, phoneNumberType	Gets the list of cities or towns with available phone numbers. Gets the list of cities or towns with available phone numbers.
get_by_number	select	phone_number, endpoint		Gets the details of the given purchased phone number. Gets the details of the given purchased phone number.
get_reservation	select	reservation_id, endpoint		Gets a reservation by its ID. Retrieves the reservation with the given ID, including all of the phone numbers associated with it.
get_search_result	select	search_id, endpoint		Gets a phone number search result by search id. Gets a phone number search result by search id.
get_operation	select	operation_id, endpoint		Gets an operation by its id. Gets an operation by its id.
list_available_countries	select	endpoint	skip, maxPageSize, accept-language	Gets the list of supported countries. Gets the list of supported countries.
release_phone_number	delete	phone_number, endpoint		Releases a purchased phone number. Releases a purchased phone number.
cancel_operation	delete	operation_id, endpoint		Cancels an operation by its id. Cancels an operation by its id.
list_offerings	exec	country_code, endpoint	skip, maxPageSize, phoneNumberType, assignmentType, accept-language	List available offerings of capabilities with rates for the given country. List available offerings of capabilities with rates for the given country.
list_reservations	exec	endpoint	maxPageSize	Lists all reservations. Retrieves a paginated list of all phone number reservations. Note that the reservations will not be populated with the phone numbers associated with them.
list_phone_numbers	exec	endpoint	skip, top	Gets the list of all purchased phone numbers. Gets the list of all purchased phone numbers.
create_or_update_reservation	exec	reservation_id, endpoint		Creates or updates a reservation by its ID. Adds and removes phone numbers from the reservation with the given ID. The response will be the updated state of the reservation. Phone numbers can be reserved by including them in the payload. If a number is already in the reservation, it will be ignored. To remove a phone number, set it explicitly to null in the request payload. This operation is idempotent. If a reservation with the same ID already exists, it will be updated, otherwise a new one is created. Only reservations with 'active' status can be updated. Updating a reservation will extend the expiration time of the reservation to 15 minutes after the last change, up to a maximum of 2 hours from creation time. Partial success is possible, in which case the response will have a 207 status code.
delete_reservation	exec	reservation_id, endpoint		Deletes a reservation by its ID. Deletes the reservation with the given ID. Any phone number in the reservation will be released and made available for others to purchase. Only reservations with 'active' status can be deleted.
browse_available_numbers	exec	country_code, endpoint, phoneNumberType		Browses for available phone numbers to purchase. Browses for available phone numbers to purchase. The response will be a randomized list of phone numbers available to purchase matching the browsing criteria. This operation is not paginated. Since the results are randomized, repeating the same request will not guarantee the same results.
purchase_reservation	exec	reservation_id, endpoint		Starts the purchase of all phone numbers in the reservation. Starts a long running operation to purchase all of the phone numbers in the reservation. Purchase can only be started for active reservations that at least one phone number. If any of the phone numbers in the reservation is from a country where reselling is not permitted, do not resell agreement is required. The response will include an 'Operation-Location' header that can be used to query the status of the operation.
purchase_phone_numbers	exec	endpoint		Purchases phone numbers. Purchases phone numbers.
update_capabilities	exec	phone_number, endpoint		Updates the capabilities of a phone number. Updates the capabilities of a phone number.
operator_information_search	exec	endpoint, phoneNumbers		Searches for number format and operator information for a given list of phone numbers. Searches for number format and operator information for a given list of phone numbers.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
country_code	string	The ISO 3166-2 country code, e.g. US. Required.
endpoint	string	The service endpoint host (no scheme), e.g. myaccount.table.cosmos.azure.com:443 - value of the client endpoint parameter. (default: )
operation_id	string	The id of the operation. Required.
phoneNumberType	string	Filter by numberType, e.g. Geographic, TollFree, Mobile. Known values are: "geographic", "tollFree", and "mobile". Required.
phone_number	string	The phone number id in E.164 format. The leading plus can be either + or encoded as %2B, e.g. +11234567890. Required.
reservation_id	string	The id of the reservation. Required.
search_id	string	The search Id. Required.
accept-language	string	The locale to display in the localized fields in the response. e.g. 'en-US'. Default value is None.
administrativeDivision	string	An optional parameter for the name of the state or province in which to search for the area code. Default value is None.
assignmentType	string	Filter by assignmentType, e.g. Person, Application. Known values are: "person" and "application". Default value is None.
locality	string	The name of locality or town in which to search for the area code. This is required if the number type is Geographic. Default value is None.
maxPageSize	integer	An optional parameter for how many entries to return, for pagination purposes. The default value is 100. Default value is 100.
phoneNumberType	string	Filter by numberType, e.g. Geographic, TollFree, Mobile. Known values are: "geographic", "tollFree", and "mobile". Default value is None.
skip	integer	An optional parameter for how many entries to skip, for pagination purposes. The default value is 0. Default value is 0.
top	integer	An optional parameter for how many entries to return, for pagination purposes. The default value is 100. Default value is 100.

SELECT examples

search_available_phone_numbers

Search for available phone numbers to purchase. Search for available phone numbers to purchase.

SELECT
assignmentType,
capabilities,
cost,
error,
errorCode,
isAgreementToNotResellRequired,
phoneNumberType,
phoneNumbers,
searchExpiresBy,
searchId
FROM azure.communication_phone_numbers.phone_numbers
WHERE country_code = '{{ country_code }}' -- required
AND endpoint = '{{ endpoint }}' -- required
;

list_area_codes

Gets the list of available area codes. Gets the list of available area codes.

SELECT
areaCode
FROM azure.communication_phone_numbers.phone_numbers
WHERE country_code = '{{ country_code }}' -- required
AND phoneNumberType = '{{ phoneNumberType }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND skip = '{{ skip }}'
AND maxPageSize = '{{ maxPageSize }}'
AND assignmentType = '{{ assignmentType }}'
AND locality = '{{ locality }}'
AND administrativeDivision = '{{ administrativeDivision }}'
AND accept-language = '{{ accept-language }}'
;

list_available_localities

Gets the list of cities or towns with available phone numbers. Gets the list of cities or towns with available phone numbers.

SELECT
administrativeDivision,
localizedName
FROM azure.communication_phone_numbers.phone_numbers
WHERE country_code = '{{ country_code }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND skip = '{{ skip }}'
AND maxPageSize = '{{ maxPageSize }}'
AND administrativeDivision = '{{ administrativeDivision }}'
AND accept-language = '{{ accept-language }}'
AND phoneNumberType = '{{ phoneNumberType }}'
;

get_by_number

Gets the details of the given purchased phone number. Gets the details of the given purchased phone number.

SELECT
id,
assignmentType,
capabilities,
cost,
countryCode,
phoneNumber,
phoneNumberType,
purchaseDate
FROM azure.communication_phone_numbers.phone_numbers
WHERE phone_number = '{{ phone_number }}' -- required
AND endpoint = '{{ endpoint }}' -- required
;

get_reservation

Gets a reservation by its ID. Retrieves the reservation with the given ID, including all of the phone numbers associated with it.

SELECT
id,
expiresAt,
phoneNumbers,
status
FROM azure.communication_phone_numbers.phone_numbers
WHERE reservation_id = '{{ reservation_id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
;

get_search_result

Gets a phone number search result by search id. Gets a phone number search result by search id.

SELECT
assignmentType,
capabilities,
cost,
error,
errorCode,
isAgreementToNotResellRequired,
phoneNumberType,
phoneNumbers,
searchExpiresBy,
searchId
FROM azure.communication_phone_numbers.phone_numbers
WHERE search_id = '{{ search_id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
;

get_operation

Gets an operation by its id. Gets an operation by its id.

SELECT
id,
createdDateTime,
error,
lastActionDateTime,
operationType,
resourceLocation,
status
FROM azure.communication_phone_numbers.phone_numbers
WHERE operation_id = '{{ operation_id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
;

list_available_countries

Gets the list of supported countries. Gets the list of supported countries.

SELECT
countryCode,
localizedName
FROM azure.communication_phone_numbers.phone_numbers
WHERE endpoint = '{{ endpoint }}' -- required
AND skip = '{{ skip }}'
AND maxPageSize = '{{ maxPageSize }}'
AND accept-language = '{{ accept-language }}'
;

DELETE examples

release_phone_number

Releases a purchased phone number. Releases a purchased phone number.

DELETE FROM azure.communication_phone_numbers.phone_numbers
WHERE phone_number = '{{ phone_number }}' --required
AND endpoint = '{{ endpoint }}' --required
;

cancel_operation

Cancels an operation by its id. Cancels an operation by its id.

DELETE FROM azure.communication_phone_numbers.phone_numbers
WHERE operation_id = '{{ operation_id }}' --required
AND endpoint = '{{ endpoint }}' --required
;

Lifecycle Methods

list_offerings

List available offerings of capabilities with rates for the given country. List available offerings of capabilities with rates for the given country.

EXEC azure.communication_phone_numbers.phone_numbers.list_offerings 
@country_code='{{ country_code }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@skip='{{ skip }}', 
@maxPageSize='{{ maxPageSize }}', 
@phoneNumberType='{{ phoneNumberType }}', 
@assignmentType='{{ assignmentType }}', 
@accept-language='{{ accept-language }}'
;

list_reservations

Lists all reservations. Retrieves a paginated list of all phone number reservations. Note that the reservations will not be populated with the phone numbers associated with them.

EXEC azure.communication_phone_numbers.phone_numbers.list_reservations 
@endpoint='{{ endpoint }}' --required, 
@maxPageSize='{{ maxPageSize }}'
;

list_phone_numbers

Gets the list of all purchased phone numbers. Gets the list of all purchased phone numbers.

EXEC azure.communication_phone_numbers.phone_numbers.list_phone_numbers 
@endpoint='{{ endpoint }}' --required, 
@skip='{{ skip }}', 
@top='{{ top }}'
;

create_or_update_reservation

Creates or updates a reservation by its ID. Adds and removes phone numbers from the reservation with the given ID. The response will be the updated state of the reservation. Phone numbers can be reserved by including them in the payload. If a number is already in the reservation, it will be ignored. To remove a phone number, set it explicitly to null in the request payload. This operation is idempotent. If a reservation with the same ID already exists, it will be updated, otherwise a new one is created. Only reservations with 'active' status can be updated. Updating a reservation will extend the expiration time of the reservation to 15 minutes after the last change, up to a maximum of 2 hours from creation time. Partial success is possible, in which case the response will have a 207 status code.

EXEC azure.communication_phone_numbers.phone_numbers.create_or_update_reservation 
@reservation_id='{{ reservation_id }}' --required, 
@endpoint='{{ endpoint }}' --required 
@@json=
'{
"phoneNumbers": "{{ phoneNumbers }}"
}'
;

delete_reservation

Deletes a reservation by its ID. Deletes the reservation with the given ID. Any phone number in the reservation will be released and made available for others to purchase. Only reservations with 'active' status can be deleted.

EXEC azure.communication_phone_numbers.phone_numbers.delete_reservation 
@reservation_id='{{ reservation_id }}' --required, 
@endpoint='{{ endpoint }}' --required
;

browse_available_numbers

Browses for available phone numbers to purchase. Browses for available phone numbers to purchase. The response will be a randomized list of phone numbers available to purchase matching the browsing criteria. This operation is not paginated. Since the results are randomized, repeating the same request will not guarantee the same results.

EXEC azure.communication_phone_numbers.phone_numbers.browse_available_numbers 
@country_code='{{ country_code }}' --required, 
@endpoint='{{ endpoint }}' --required 
@@json=
'{
"phoneNumberType": "{{ phoneNumberType }}", 
"capabilities": "{{ capabilities }}", 
"assignmentType": "{{ assignmentType }}", 
"phoneNumberPrefixes": "{{ phoneNumberPrefixes }}"
}'
;

purchase_reservation

Starts the purchase of all phone numbers in the reservation. Starts a long running operation to purchase all of the phone numbers in the reservation. Purchase can only be started for active reservations that at least one phone number. If any of the phone numbers in the reservation is from a country where reselling is not permitted, do not resell agreement is required. The response will include an 'Operation-Location' header that can be used to query the status of the operation.

EXEC azure.communication_phone_numbers.phone_numbers.purchase_reservation 
@reservation_id='{{ reservation_id }}' --required, 
@endpoint='{{ endpoint }}' --required 
@@json=
'{
"agreeToNotResell": {{ agreeToNotResell }}
}'
;

purchase_phone_numbers

Purchases phone numbers. Purchases phone numbers.

EXEC azure.communication_phone_numbers.phone_numbers.purchase_phone_numbers 
@endpoint='{{ endpoint }}' --required 
@@json=
'{
"searchId": "{{ searchId }}", 
"agreeToNotResell": {{ agreeToNotResell }}
}'
;

update_capabilities

Updates the capabilities of a phone number. Updates the capabilities of a phone number.

EXEC azure.communication_phone_numbers.phone_numbers.update_capabilities 
@phone_number='{{ phone_number }}' --required, 
@endpoint='{{ endpoint }}' --required 
@@json=
'{
"calling": "{{ calling }}", 
"sms": "{{ sms }}"
}'
;

operator_information_search

Searches for number format and operator information for a given list of phone numbers. Searches for number format and operator information for a given list of phone numbers.

EXEC azure.communication_phone_numbers.phone_numbers.operator_information_search 
@endpoint='{{ endpoint }}' --required 
@@json=
'{
"phoneNumbers": "{{ phoneNumbers }}", 
"options": "{{ options }}"
}'
;