Share via

Phone Numbers - Get Reservation

Service:
Communication
API Version:
2025-06-01

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

GET {endpoint}/availablePhoneNumbers/reservations/{reservationId}?api-version=2025-06-01

URI Parameters

Name In Required Type Description
endpoint
 path True

string (url)

The communication resource, for example https://resourcename.communication.azure.com
reservationId
 path True

string (uuid)

The id of the reservation.
api-version
 query True

string

Version of API to invoke

Responses

Name Type Description
200 OK

PhoneNumbersReservation

Successfully retrieved the reservation.
Other Status Codes

CommunicationErrorResponse

Failure

Examples

Get reservation

Sample request

GET https://resourcename.communication.azure.com/availablePhoneNumbers/reservations/65c18c7f-8074-4efb-a572-e0df127a9964?api-version=2025-06-01

Sample response

Status code:
200 
{
  "id": "65c18c7f-8074-4efb-a572-e0df127a9964",
  "expiresAt": "2023-08-23T22:29:17.092Z",
  "phoneNumbers": {},
  "status": "active"
}

Definitions

Name Description
AvailablePhoneNumber

Represents a phone number available in inventory
AvailablePhoneNumberError

Contains error details in case of failure when reserving, releasing or purchasing the phone number. Note that this is ignored by the service when present in requests.
AvailablePhoneNumberStatus

Represents the status of the phone number. Possible values include: 'available', 'reserved', 'expired', 'error', 'purchased'.
BillingFrequency

The frequency with which the cost gets billed.
CommunicationError

The Communication Services error.
CommunicationErrorResponse

The Communication Services error.
Cost

The incurred cost for this phone number.
PhoneNumberAssignmentType

Represents the assignment type of the offering.
PhoneNumberCapabilities

Capabilities of a phone number.
PhoneNumberCapabilityType

Capability value for calling.
PhoneNumbersReservation

Represents a reservation for phone numbers. A reservation is a temporary hold on phone numbers that can later be purchased. The reservation has a limited lifetime after which the phone numbers are released if not purchased. Reservations older than 1 month are automatically deleted.
PhoneNumberType

Represents the number type of the offering.
ReservationStatus

Represents the status of the reservation. Possible values include: 'active', 'submitted', 'completed', 'expired'.

AvailablePhoneNumber

Object

Represents a phone number available in inventory

Name Type Description
assignmentType

PhoneNumberAssignmentType

Represents the assignment type of the offering. Also known as the use case.
capabilities

PhoneNumberCapabilities

Capabilities of a phone number.
cost

Cost

The incurred cost for this phone number.
countryCode

string

The ISO 3166-2 country code, e.g. US.
error

AvailablePhoneNumberError

Contains error details in case of failure when reserving, releasing or purchasing the phone number. Note that this is ignored by the service when present in requests.
id

string

The id of the phone number.
isAgreementToNotResellRequired

boolean

Indicates if do not resell agreement is required. If true, the phone number cannot be acquired unless the customer provides explicit agreement to not resell it.
phoneNumber

string

The phone number in E.164 format, e.g. +11234567890.
phoneNumberType

PhoneNumberType

Represents the number type of the offering.
status

AvailablePhoneNumberStatus

Represents the status of the phone number. Possible values include: 'available', 'reserved', 'expired', 'error', 'purchased'.

AvailablePhoneNumberError

Object

Contains error details in case of failure when reserving, releasing or purchasing the phone number. Note that this is ignored by the service when present in requests.

Name Type Description
code

string

The error code indicating the reason why the operation performed on the phone number failed.
message

string

The error message describing the failure that occurred.

AvailablePhoneNumberStatus

Enumeration

Represents the status of the phone number. Possible values include: 'available', 'reserved', 'expired', 'error', 'purchased'.

Value Description
available
reserved
expired
error
purchased

BillingFrequency

Enumeration

The frequency with which the cost gets billed.

Value Description
monthly

CommunicationError

Object

The Communication Services error.

Name Type Description
code

string

The error code.
details

CommunicationError[]

Further details about specific errors that led to this error.
innererror

CommunicationError

The inner error if any.
message

string

The error message.
target

string

The error target.

CommunicationErrorResponse

Object

The Communication Services error.

Name Type Description
error

CommunicationError

The Communication Services error.

Cost

Object

The incurred cost for this phone number.

Name Type Description
amount

number (double)

The cost amount.
billingFrequency

BillingFrequency

The frequency with which the cost gets billed.
currencyCode

string

The ISO 4217 currency code for the cost amount, e.g. USD.

PhoneNumberAssignmentType

Enumeration

Represents the assignment type of the offering.

Value Description
person
application

PhoneNumberCapabilities

Object

Capabilities of a phone number.

Name Type Description
calling

PhoneNumberCapabilityType

Capability value for calling.
sms

PhoneNumberCapabilityType

Capability value for SMS.

PhoneNumberCapabilityType

Enumeration

Capability value for calling.

Value Description
none
inbound
outbound
inbound+outbound

PhoneNumbersReservation

Object

Represents a reservation for phone numbers. A reservation is a temporary hold on phone numbers that can later be purchased. The reservation has a limited lifetime after which the phone numbers are released if not purchased. Reservations older than 1 month are automatically deleted.

Name Type Description
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.
id

string (uuid)

The id of the reservation.
phoneNumbers

<string,  AvailablePhoneNumber>

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

ReservationStatus

Represents the status of the reservation. Possible values include: 'active', 'submitted', 'completed', 'expired'.

PhoneNumberType

Enumeration

Represents the number type of the offering.

Value Description
geographic
tollFree
mobile

ReservationStatus

Enumeration

Represents the status of the reservation. Possible values include: 'active', 'submitted', 'completed', 'expired'.

Value Description
active
submitted
completed
expired