{ "swagger": "2.0", "info": { "title": "PhoneNumbersClient", "description": "The phone numbers client uses Azure Communication Services to purchase and manage phone numbers.", "version": "2025-06-01" }, "paths": { "/availablePhoneNumbers/countries/{countryCode}/areaCodes": { "get": { "tags": [ "Browse for available countries, cities and area codes" ], "summary": "Gets the list of available area codes.", "operationId": "PhoneNumbers_ListAreaCodes", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "countryCode", "description": "The ISO 3166-2 country code, e.g. US.", "required": true, "type": "string" }, { "in": "query", "name": "phoneNumberType", "description": "Filter by numberType, e.g. Geographic, TollFree, Mobile.", "required": true, "type": "string", "enum": [ "geographic", "tollFree", "mobile" ], "x-ms-enum": { "name": "PhoneNumberType", "modelAsString": true } }, { "in": "query", "name": "skip", "description": "An optional parameter for how many entries to skip, for pagination purposes. The default value is 0.", "type": "integer", "format": "int32", "default": 0 }, { "in": "query", "name": "maxPageSize", "description": "An optional parameter for how many entries to return, for pagination purposes. The default value is 100.", "type": "integer", "format": "int32", "default": 100 }, { "in": "query", "name": "assignmentType", "description": "Filter by assignmentType, e.g. Person, Application.", "type": "string", "enum": [ "person", "application" ], "x-ms-enum": { "name": "PhoneNumberAssignmentType", "modelAsString": true } }, { "in": "query", "name": "locality", "description": "The name of locality or town in which to search for the area code. This is required if the number type is Geographic.", "type": "string" }, { "in": "query", "name": "administrativeDivision", "description": "The name of the state or province in which to search for the area code.", "type": "string" }, { "$ref": "#/parameters/ApiVersionParameter" }, { "in": "header", "name": "accept-language", "description": "The locale to display in the localized fields in the response. e.g. 'en-US'", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/PhoneNumberAreaCodes" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink", "itemName": "areaCodes" }, "x-ms-examples": { "Get Area Codes Search Result": { "$ref": "./examples/GetAreaCodes.json" } } } }, "/availablePhoneNumbers/countries": { "get": { "tags": [ "Browse for available countries, cities and area codes" ], "summary": "Gets the list of supported countries.", "operationId": "PhoneNumbers_ListAvailableCountries", "produces": [ "application/json" ], "parameters": [ { "in": "query", "name": "skip", "description": "An optional parameter for how many entries to skip, for pagination purposes. The default value is 0.", "type": "integer", "format": "int32", "default": 0 }, { "in": "query", "name": "maxPageSize", "description": "An optional parameter for how many entries to return, for pagination purposes. The default value is 100.", "type": "integer", "format": "int32", "default": 100 }, { "$ref": "#/parameters/ApiVersionParameter" }, { "in": "header", "name": "accept-language", "description": "The locale to display in the localized fields in the response. e.g. 'en-US'", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/PhoneNumberCountries" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink", "itemName": "countries" }, "x-ms-examples": { "Get countries": { "$ref": "./examples/GetCountries.json" } } } }, "/availablePhoneNumbers/countries/{countryCode}/:browse": { "post": { "tags": [ "Browse, reserve and purchase available phone numbers" ], "summary": "Browses for available phone numbers to purchase.", "description": "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.", "operationId": "PhoneNumbers_BrowseAvailableNumbers", "produces": [ "application/json" ], "consumes": [ "application/json" ], "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" }, { "$ref": "#/parameters/CountryCodeParameter" }, { "in": "body", "name": "phoneNumbersBrowseRequest", "description": "An object defining the criteria to browse for available phone numbers.", "schema": { "$ref": "#/definitions/PhoneNumbersBrowseRequest" }, "required": true } ], "responses": { "200": { "description": "A randomized list of phone numbers available to purchase matching the browsing criteria.", "schema": { "$ref": "#/definitions/PhoneNumbersBrowseResult" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Browse available phone numbers": { "$ref": "./examples/BrowseAvailablePhoneNumbers.json" } } } }, "/availablePhoneNumbers/countries/{countryCode}/localities": { "get": { "tags": [ "Browse for available countries, cities and area codes" ], "summary": "Gets the list of cities or towns with available phone numbers.", "operationId": "PhoneNumbers_ListAvailableLocalities", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "countryCode", "description": "The ISO 3166-2 country code, e.g. US.", "required": true, "type": "string" }, { "in": "query", "name": "skip", "description": "An optional parameter for how many entries to skip, for pagination purposes. The default value is 0.", "type": "integer", "format": "int32", "default": 0 }, { "in": "query", "name": "maxPageSize", "description": "An optional parameter for how many entries to return, for pagination purposes. The default value is 100.", "type": "integer", "format": "int32", "default": 100 }, { "in": "query", "name": "administrativeDivision", "description": "An optional parameter for the name of the state or province in which to search for the area code.", "type": "string" }, { "$ref": "#/parameters/ApiVersionParameter" }, { "in": "header", "name": "accept-language", "description": "The locale to display in the localized fields in the response. e.g. 'en-US'", "type": "string" }, { "in": "query", "name": "phoneNumberType", "description": "Filter by numberType, e.g. Geographic, TollFree, Mobile.", "type": "string", "enum": [ "geographic", "tollFree", "mobile" ], "x-ms-enum": { "name": "PhoneNumberType", "modelAsString": true } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/PhoneNumberLocalities" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink", "itemName": "phoneNumberLocalities" }, "x-ms-examples": { "Get PhoneNumber Search Result": { "$ref": "./examples/GetLocalities.json" } } } }, "/availablePhoneNumbers/countries/{countryCode}/offerings": { "get": { "tags": [ "Browse for available countries, cities and area codes" ], "summary": "List available offerings of capabilities with rates for the given country.", "operationId": "PhoneNumbers_ListOfferings", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "countryCode", "description": "The ISO 3166-2 country code, e.g. US.", "required": true, "type": "string" }, { "in": "query", "name": "skip", "description": "An optional parameter for how many entries to skip, for pagination purposes. The default value is 0.", "type": "integer", "format": "int32", "default": 0 }, { "in": "query", "name": "maxPageSize", "description": "An optional parameter for how many entries to return, for pagination purposes. The default value is 100.", "type": "integer", "format": "int32", "default": 100 }, { "in": "query", "name": "phoneNumberType", "description": "Filter by numberType, e.g. Geographic, TollFree, Mobile.", "type": "string", "enum": [ "geographic", "tollFree", "mobile" ], "x-ms-enum": { "name": "PhoneNumberType", "modelAsString": true } }, { "in": "query", "name": "assignmentType", "description": "Filter by assignmentType, e.g. Person, Application.", "type": "string", "enum": [ "person", "application" ], "x-ms-enum": { "name": "PhoneNumberAssignmentType", "modelAsString": true } }, { "$ref": "#/parameters/ApiVersionParameter" }, { "in": "header", "name": "accept-language", "description": "The locale to display in the localized fields in the response. e.g. 'en-US'", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/OfferingsResponse" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink", "itemName": "phoneNumberOfferings" }, "x-ms-examples": { "Get PhoneNumber Search Result": { "$ref": "./examples/GetOfferings.json" } } } }, "/availablePhoneNumbers/reservations": { "get": { "tags": [ "Browse, reserve and purchase available phone numbers" ], "summary": "Lists all reservations.", "description": "Retrieves a paginated list of all phone number reservations. Note that the reservations will not be populated with the phone numbers associated with them.", "produces": [ "application/json" ], "operationId": "PhoneNumbers_ListReservations", "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" }, { "$ref": "#/parameters/MaxPageSizeParameter" } ], "responses": { "200": { "description": "A collection of Phone Number Reservations, and an optional link to the next page of results.", "schema": { "$ref": "#/definitions/PhoneNumbersReservations" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink", "itemName": "reservations" }, "x-ms-examples": { "Get reservations": { "$ref": "./examples/GetReservations.json" } } } }, "/availablePhoneNumbers/reservations/{reservationId}": { "patch": { "tags": [ "Browse, reserve and purchase available phone numbers" ], "summary": "Creates or updates a reservation by its ID.", "description": "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.", "consumes": [ "application/merge-patch+json" ], "produces": [ "application/json" ], "operationId": "PhoneNumbers_CreateOrUpdateReservation", "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" }, { "$ref": "#/parameters/ReservationIdParameter" }, { "$ref": "#/parameters/ReservationParameter" } ], "responses": { "201": { "description": "Reservation successfully created.", "schema": { "$ref": "#/definitions/PhoneNumbersReservation" } }, "200": { "description": "Reservation successfully updated.", "schema": { "$ref": "#/definitions/PhoneNumbersReservation" } }, "207": { "description": "Reservation operation partially succeeded. This can happen when the operation (create or update) is processed successfully, but it failed for at least one of the phone numbers in the request.", "schema": { "$ref": "#/definitions/PhoneNumbersReservation" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Create or update reservation": { "$ref": "./examples/CreateOrUpdateReservation.json" } } }, "get": { "tags": [ "Browse, reserve and purchase available phone numbers" ], "summary": "Gets a reservation by its ID.", "description": "Retrieves the reservation with the given ID, including all of the phone numbers associated with it.", "produces": [ "application/json" ], "operationId": "PhoneNumbers_GetReservation", "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" }, { "$ref": "#/parameters/ReservationIdParameter" } ], "responses": { "200": { "description": "Successfully retrieved the reservation.", "schema": { "$ref": "#/definitions/PhoneNumbersReservation" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Get reservation": { "$ref": "./examples/GetReservation.json" } } }, "delete": { "tags": [ "Browse, reserve and purchase available phone numbers" ], "summary": "Deletes a reservation by its ID.", "description": "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.", "produces": [ "application/json" ], "operationId": "PhoneNumbers_DeleteReservation", "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" }, { "$ref": "#/parameters/ReservationIdParameter" } ], "responses": { "204": { "description": "Reservation successfully deleted." }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Delete reservation": { "$ref": "./examples/DeleteReservation.json" } } } }, "/availablePhoneNumbers/reservations/{reservationId}/:purchase": { "post": { "tags": [ "Browse, reserve and purchase available phone numbers" ], "summary": "Starts the purchase of all phone numbers in the reservation.", "description": "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.", "produces": [ "application/json" ], "operationId": "PhoneNumbers_PurchaseReservation", "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" }, { "$ref": "#/parameters/ReservationIdParameter" }, { "in": "body", "name": "reservationPurchaseRequest", "required": false, "schema": { "$ref": "#/definitions/PhoneNumbersReservationPurchaseRequest" } } ], "responses": { "202": { "description": "The service has accepted the request and will start processing later. It will return 'Accepted' immediately and include an 'Operation-Location' header. Client side should further query the operation status using the URL specified in 'Operation-Location' header.", "headers": { "Operation-Location": { "description": "URL to query for status of the operation.", "type": "string" }, "operation-id": { "description": "The operation id.", "type": "string" }, "reservation-purchase-id": { "description": "The reservation purchase operation id.", "type": "string" } } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-long-running-operation": true, "x-ms-examples": { "Start reservation purchase": { "$ref": "./examples/PurchaseReservation.json" } } } }, "/availablePhoneNumbers/countries/{countryCode}/:search": { "post": { "tags": [ "Find and purchase available phone numbers" ], "summary": "Search for available phone numbers to purchase.", "operationId": "PhoneNumbers_SearchAvailablePhoneNumbers", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "countryCode", "description": "The ISO 3166-2 country code, e.g. US.", "required": true, "type": "string" }, { "$ref": "#/parameters/ApiVersionParameter" }, { "in": "body", "name": "body", "description": "The phone number search request.", "required": true, "schema": { "$ref": "#/definitions/PhoneNumberSearchRequest" } } ], "responses": { "202": { "description": "The service has accepted the request and will start processing later. It will return 'Accepted' immediately and include an 'Operation-Location' and 'Location' headers. Client side should further query the operation status using the URL specified in 'Operation-Location' header. When operation completes successfully query final result using URL specified in 'Location' header.", "schema": { "$ref": "#/definitions/PhoneNumberSearchResult" }, "headers": { "Location": { "description": "URL to retrieve the final result after operation completes.", "type": "string" }, "Operation-Location": { "description": "URL to query for status of the operation.", "type": "string" }, "operation-id": { "description": "The operation id.", "type": "string" }, "search-id": { "description": "The search operation id.", "type": "string" } } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "x-ms-examples": { "Search for phone numbers": { "$ref": "./examples/SearchPhoneNumbers.json" } } } }, "/availablePhoneNumbers/searchResults/{searchId}": { "get": { "tags": [ "Find and purchase available phone numbers" ], "summary": "Gets a phone number search result by search id.", "operationId": "PhoneNumbers_GetSearchResult", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "searchId", "description": "The search Id.", "required": true, "type": "string" }, { "$ref": "#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/PhoneNumberSearchResult" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Get PhoneNumber Search Result": { "$ref": "./examples/GetPhoneNumberSearchResult.json" } } } }, "/availablePhoneNumbers/:purchase": { "post": { "tags": [ "Find and purchase available phone numbers" ], "summary": "Purchases phone numbers.", "operationId": "PhoneNumbers_PurchasePhoneNumbers", "consumes": [ "application/json" ], "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" }, { "in": "body", "name": "body", "description": "The phone number purchase request", "required": true, "schema": { "$ref": "#/definitions/PhoneNumberPurchaseRequest" } } ], "responses": { "202": { "description": "The service has accepted the request and will start processing later. It will return 'Accepted' immediately and include an 'Operation-Location' header. Client side should further query the operation status using the URL specified in 'Operation-Location' header.", "headers": { "Operation-Location": { "description": "URL to query for status of the operation.", "type": "string" }, "operation-id": { "description": "The operation id.", "type": "string" }, "purchase-id": { "description": "The purchase operation id.", "type": "string" } } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-long-running-operation": true, "x-ms-examples": { "Purchase phone numbers": { "$ref": "./examples/PurchasePhoneNumbers.json" } }, "produces": [ "application/json" ] } }, "/phoneNumbers/operations/{operationId}": { "get": { "tags": [ "Long running operations" ], "summary": "Gets an operation by its id.", "operationId": "PhoneNumbers_GetOperation", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "operationId", "description": "The id of the operation", "required": true, "type": "string" }, { "$ref": "#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "When the operation is completed, query the final result of the operation using the URL specified in the 'Location' attribute in the response header.", "schema": { "$ref": "#/definitions/PhoneNumberOperation" }, "headers": { "Location": { "description": "Url to retrieve the final result after operation completes.", "type": "string" } } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Get long running operation status by operation id": { "$ref": "./examples/GetOperation.json" } } }, "delete": { "tags": [ "Long running operations" ], "summary": "Cancels an operation by its id.", "operationId": "PhoneNumbers_CancelOperation", "parameters": [ { "in": "path", "name": "operationId", "description": "The id of the operation", "required": true, "type": "string" }, { "$ref": "#/parameters/ApiVersionParameter" } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Delete long running operation with the given operation id": { "$ref": "./examples/DeleteOperation.json" } }, "produces": [ "application/json" ] } }, "/phoneNumbers/{phoneNumber}/capabilities": { "patch": { "tags": [ "Manage purchased phone numbers" ], "summary": "Updates the capabilities of a phone number.", "operationId": "PhoneNumbers_UpdateCapabilities", "consumes": [ "application/merge-patch+json" ], "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "phoneNumber", "description": "The phone number id in E.164 format. The leading plus can be either + or encoded as %2B, e.g. +11234567890.", "required": true, "type": "string" }, { "$ref": "#/parameters/ApiVersionParameter" }, { "in": "body", "name": "body", "description": "Defines the update capabilities request.", "schema": { "$ref": "#/definitions/PhoneNumberCapabilitiesRequest" } } ], "responses": { "202": { "description": "The service has accepted the request and will start processing later. It will return 'Accepted' immediately and include an 'Operation-Location' and 'Location' headers. Client side should further query the operation status using the URL specified in 'Operation-Location' header. When operation completes successfully query final result using URL specified in 'Location' header.", "schema": { "$ref": "#/definitions/PurchasedPhoneNumber" }, "headers": { "Location": { "description": "URL to retrieve the final result after operation completes.", "type": "string" }, "Operation-Location": { "description": "URL to query for status of the operation.", "type": "string" }, "operation-id": { "description": "The operation id.", "type": "string" }, "capabilities-id": { "description": "The capabilities operation id.", "type": "string" } } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "x-ms-examples": { "Update phoneNumber capabilities": { "$ref": "./examples/UpdatePhoneNumberCapabilities.json" } } } }, "/phoneNumbers/{phoneNumber}": { "get": { "tags": [ "Manage purchased phone numbers" ], "summary": "Gets the details of the given purchased phone number.", "operationId": "PhoneNumbers_GetByNumber", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "phoneNumber", "description": "The purchased phone number whose details are to be fetched in E.164 format, e.g. +11234567890.", "required": true, "type": "string" }, { "$ref": "#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/PurchasedPhoneNumber" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Fetch purchased phone number": { "$ref": "./examples/GetPhoneNumber.json" } } }, "delete": { "tags": [ "Manage purchased phone numbers" ], "summary": "Releases a purchased phone number.", "operationId": "PhoneNumbers_ReleasePhoneNumber", "parameters": [ { "in": "path", "name": "phoneNumber", "description": "Phone number to be released, e.g. +11234567890.", "required": true, "type": "string" }, { "$ref": "#/parameters/ApiVersionParameter" } ], "responses": { "202": { "description": "The service has accepted the request and will start processing later. It will return 'Accepted' immediately and include an 'Operation-Location' header. Client side should further query the operation status using the URL specified in 'Operation-Location' header.", "headers": { "Operation-Location": { "description": "URL to query for status of the operation.", "type": "string" }, "operation-id": { "description": "The operation id.", "type": "string" }, "release-id": { "description": "The release operation id.", "type": "string" } } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-long-running-operation": true, "x-ms-examples": { "Release phone number": { "$ref": "./examples/ReleasePhoneNumber.json" } }, "produces": [ "application/json" ] } }, "/phoneNumbers": { "get": { "tags": [ "Manage purchased phone numbers" ], "summary": "Gets the list of all purchased phone numbers.", "operationId": "PhoneNumbers_ListPhoneNumbers", "produces": [ "application/json" ], "parameters": [ { "in": "query", "name": "skip", "description": "An optional parameter for how many entries to skip, for pagination purposes. The default value is 0.", "type": "integer", "format": "int32", "default": 0 }, { "in": "query", "name": "top", "description": "An optional parameter for how many entries to return, for pagination purposes. The default value is 100.", "type": "integer", "format": "int32", "default": 100 }, { "$ref": "#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/PurchasedPhoneNumbers" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink", "itemName": "phoneNumbers" }, "x-ms-examples": { "List purchased phone numbers": { "$ref": "./examples/GetPhoneNumbers.json" } } } }, "/operatorInformation/:search": { "post": { "tags": [ "Obtain operator information for requested numbers" ], "summary": "Searches for number format and operator information for a given list of phone numbers.", "operationId": "PhoneNumbers_OperatorInformationSearch", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" }, { "in": "body", "name": "body", "description": "The phone number(s) whose number format and operator information should be searched", "required": true, "schema": { "$ref": "#/definitions/OperatorInformationRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/OperatorInformationResult" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Search for number format and operator information on phone numbers": { "$ref": "./examples/SearchOperatorInformation.json" } } } } }, "definitions": { "OfferingsResponse": { "description": "Represents a wrapper around a list of offerings.", "type": "object", "properties": { "phoneNumberOfferings": { "description": "Represents the underlying list of offerings.", "type": "array", "items": { "$ref": "#/definitions/PhoneNumberOffering" } }, "nextLink": { "description": "Represents the URL link to the next page.", "type": "string" } } }, "OperatorDetails": { "description": "Represents metadata describing the operator of a phone number", "type": "object", "properties": { "name": { "description": "Name of the phone operator", "type": "string" }, "mobileNetworkCode": { "description": "Mobile Network Code, 2 or 3 decimal digits that identify mobile networks within a country/region", "type": "string" }, "mobileCountryCode": { "description": "Mobile Country Code, 3 decimal digits that identify a country/region", "type": "string" } } }, "OperatorInformation": { "description": "Represents metadata about a phone number that is controlled/provided by that phone number's operator.", "required": [ "phoneNumber" ], "type": "object", "properties": { "phoneNumber": { "description": "E.164 formatted string representation of the phone number", "type": "string" }, "nationalFormat": { "description": "National format of the phone number", "type": "string" }, "internationalFormat": { "description": "International format of the phone number", "type": "string" }, "isoCountryCode": { "description": "ISO 3166-1 two character ('alpha-2') code associated with the phone number.", "type": "string" }, "numberType": { "description": "Type of service associated with the phone number", "enum": [ "unknown", "other", "geographic", "mobile" ], "type": "string", "x-ms-enum": { "name": "OperatorNumberType", "modelAsString": true } }, "operatorDetails": { "$ref": "#/definitions/OperatorDetails" } } }, "OperatorInformationOptions": { "description": "Represents options to modify a search request for operator information", "type": "object", "properties": { "includeAdditionalOperatorDetails": { "description": "Includes the fields operatorDetails, numberType, and isoCountryCode in the response. Please note: use of this option will result in additional costs", "type": "boolean" } } }, "OperatorInformationRequest": { "description": "Represents a search request for operator information for the given phone numbers.", "required": [ "phoneNumbers" ], "type": "object", "properties": { "phoneNumbers": { "description": "Phone number(s) whose operator information is being requested", "type": "array", "items": { "type": "string" } }, "options": { "$ref": "#/definitions/OperatorInformationOptions" } } }, "OperatorInformationResult": { "description": "Represents a search result containing format and operator information associated with the requested phone numbers", "type": "object", "properties": { "values": { "description": "Results of a search.\r\nThis array will have one entry per requested phone number which will contain the relevant operator information.", "type": "array", "items": { "$ref": "#/definitions/OperatorInformation" } } } }, "PhoneNumberAdministrativeDivision": { "description": "Represents an administrative division. e.g. state or province.", "required": [ "abbreviatedName", "localizedName" ], "type": "object", "properties": { "localizedName": { "description": "Represents the localized name of the administrative division of the locality. e.g. state or province localized name.", "type": "string" }, "abbreviatedName": { "description": "Represents the abbreviated name of the administrative division of the locality. e.g. state or province abbreviation such as WA (Washington).", "type": "string" } } }, "PhoneNumberAreaCode": { "description": "Represents an Area Code.", "type": "object", "properties": { "areaCode": { "description": "An area code.", "type": "string" } } }, "PhoneNumberAreaCodes": { "description": "The list of available area codes.", "required": [ "areaCodes" ], "type": "object", "properties": { "areaCodes": { "description": "Represents a list of available toll-free area codes.", "type": "array", "items": { "$ref": "#/definitions/PhoneNumberAreaCode" } }, "nextLink": { "description": "Represents the URL link to the next page.", "type": "string" } } }, "PhoneNumberCapabilities": { "description": "Capabilities of a phone number.", "required": [ "calling", "sms" ], "type": "object", "properties": { "calling": { "description": "Capability value for calling.", "enum": [ "none", "inbound", "outbound", "inbound+outbound" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberCapabilityType", "modelAsString": true } }, "sms": { "description": "Capability value for SMS.", "enum": [ "none", "inbound", "outbound", "inbound+outbound" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberCapabilityType", "modelAsString": true } } } }, "PhoneNumberCapabilitiesRequest": { "description": "Capabilities of a phone number.", "type": "object", "properties": { "calling": { "description": "Capability value for calling.", "enum": [ "none", "inbound", "outbound", "inbound+outbound" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberCapabilityType", "modelAsString": true } }, "sms": { "description": "Capability value for SMS.", "enum": [ "none", "inbound", "outbound", "inbound+outbound" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberCapabilityType", "modelAsString": true } } } }, "PhoneNumberCost": { "description": "The incurred cost for a single phone number.", "required": [ "amount", "billingFrequency", "currencyCode" ], "type": "object", "properties": { "amount": { "format": "double", "description": "The cost amount.", "type": "number" }, "currencyCode": { "description": "The ISO 4217 currency code for the cost amount, e.g. USD.", "type": "string" }, "billingFrequency": { "description": "The frequency with which the cost gets billed.", "enum": [ "monthly" ], "type": "string", "x-ms-enum": { "name": "BillingFrequency", "modelAsString": true } } } }, "PhoneNumberCountries": { "description": "Represents a wrapper around a list of countries.", "type": "object", "properties": { "countries": { "description": "Represents the underlying list of countries.", "type": "array", "items": { "$ref": "#/definitions/PhoneNumberCountry" } }, "nextLink": { "description": "Represents the URL link to the next page", "type": "string" } } }, "PhoneNumberCountry": { "description": "Represents a country.", "required": [ "countryCode", "localizedName" ], "type": "object", "properties": { "localizedName": { "description": "Represents the name of the country.", "type": "string" }, "countryCode": { "description": "Represents the abbreviated name of the country.", "type": "string" } } }, "PhoneNumberLocalities": { "description": "Represents a wrapper around a list of cities or towns.", "type": "object", "properties": { "phoneNumberLocalities": { "description": "Represents the underlying list of localities, e.g. cities or town.", "type": "array", "items": { "$ref": "#/definitions/PhoneNumberLocality" } }, "nextLink": { "description": "Represents the URL link to the next page.", "type": "string" } } }, "PhoneNumberLocality": { "description": "Represents a locality.", "required": [ "localizedName" ], "type": "object", "properties": { "localizedName": { "description": "Represents the localized name of the locality.", "type": "string" }, "administrativeDivision": { "$ref": "#/definitions/PhoneNumberAdministrativeDivision" } } }, "PhoneNumberOffering": { "description": "Represents a phone number capability offering", "required": [ "cost" ], "type": "object", "properties": { "phoneNumberType": { "description": "Represents the number type of the offering.", "enum": [ "geographic", "tollFree", "mobile" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberType", "modelAsString": true } }, "assignmentType": { "description": "Represents the assignment type of the offering.", "enum": [ "person", "application" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberAssignmentType", "modelAsString": true } }, "availableCapabilities": { "$ref": "#/definitions/PhoneNumberCapabilities" }, "cost": { "$ref": "#/definitions/PhoneNumberCost" } } }, "PhoneNumberOperation": { "required": [ "createdDateTime", "id", "operationType", "status" ], "type": "object", "properties": { "operationType": { "description": "The type of operation, e.g. Search", "enum": [ "purchase", "releasePhoneNumber", "search", "updatePhoneNumberCapabilities", "reservationPurchase" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberOperationType", "modelAsString": true } }, "status": { "description": "Status of operation.", "enum": [ "notStarted", "running", "succeeded", "failed" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberOperationStatus", "modelAsString": true } }, "resourceLocation": { "description": "URL for retrieving the result of the operation, if any.", "type": "string" }, "createdDateTime": { "format": "date-time", "description": "The date that the operation was created.", "type": "string" }, "error": { "$ref": "../../../Common/stable/2021-03-07/common.json#/definitions/CommunicationError" }, "id": { "description": "Id of operation.", "type": "string" }, "lastActionDateTime": { "format": "date-time", "description": "The most recent date that the operation was changed.", "type": "string", "readOnly": true } } }, "PhoneNumberPurchaseRequest": { "description": "The phone number search purchase request.", "type": "object", "properties": { "searchId": { "description": "The search id.", "type": "string" }, "agreeToNotResell": { "description": "The agreement to not resell the phone numbers. Defaults to false if not provided.", "type": "boolean" } } }, "PhoneNumberSearchRequest": { "description": "Represents a phone number search request to find phone numbers. Found phone numbers are temporarily held for a following purchase.", "required": [ "assignmentType", "capabilities", "phoneNumberType" ], "type": "object", "properties": { "phoneNumberType": { "description": "The type of phone numbers to search for, e.g. geographic, tollFree, mobile.", "enum": [ "geographic", "tollFree", "mobile" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberType", "modelAsString": true } }, "assignmentType": { "description": "The assignment type of the phone numbers to search for. A phone number can be assigned to a person, or to an application.", "enum": [ "person", "application" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberAssignmentType", "modelAsString": true } }, "capabilities": { "$ref": "#/definitions/PhoneNumberCapabilities" }, "areaCode": { "description": "The area code of the desired phone number, e.g. 425.", "type": "string" }, "quantity": { "format": "int32", "description": "The quantity of desired phone numbers. The default value is 1.", "default": 1, "maximum": 2147483647, "minimum": 1, "type": "integer" } } }, "PhoneNumberSearchResult": { "description": "The result of a phone number search operation.", "required": [ "assignmentType", "capabilities", "cost", "phoneNumbers", "phoneNumberType", "searchExpiresBy", "searchId" ], "type": "object", "properties": { "searchId": { "description": "The search id.", "type": "string" }, "phoneNumbers": { "description": "The phone numbers that are available. Can be fewer than the desired search quantity.", "type": "array", "items": { "type": "string" } }, "phoneNumberType": { "description": "The phone number's type, e.g. geographic, tollFree, mobile.", "enum": [ "geographic", "tollFree", "mobile" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberType", "modelAsString": true } }, "assignmentType": { "description": "Phone number's assignment type.", "enum": [ "person", "application" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberAssignmentType", "modelAsString": true } }, "capabilities": { "$ref": "#/definitions/PhoneNumberCapabilities" }, "cost": { "$ref": "#/definitions/PhoneNumberCost" }, "searchExpiresBy": { "format": "date-time", "description": "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.", "type": "string" }, "isAgreementToNotResellRequired": { "description": "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.", "type": "boolean" }, "errorCode": { "format": "int32", "description": "The error code of the search.", "type": "integer" }, "error": { "description": "Mapping Error Messages to Codes", "enum": [ "NoError", "UnknownErrorCode", "OutOfStock", "AuthorizationDenied", "MissingAddress", "InvalidAddress", "InvalidOfferModel", "NotEnoughLicenses", "NoWallet", "NotEnoughCredit", "NumbersPartiallyAcquired", "AllNumbersNotAcquired", "ReservationExpired", "PurchaseFailed", "BillingUnavailable", "ProvisioningFailed", "UnknownSearchError" ], "type": "string", "x-ms-enum": { "name": "Error", "modelAsString": true } } } }, "PurchasedPhoneNumber": { "description": "Represents a purchased phone number.", "required": [ "assignmentType", "capabilities", "cost", "countryCode", "id", "phoneNumber", "phoneNumberType", "purchaseDate" ], "type": "object", "properties": { "id": { "description": "The id of the phone number, e.g. 11234567890.", "type": "string" }, "phoneNumber": { "description": "String of the E.164 format of the phone number, e.g. +11234567890.", "type": "string" }, "countryCode": { "description": "The ISO 3166-2 code of the phone number's country, e.g. US.", "type": "string" }, "phoneNumberType": { "description": "The phone number's type, e.g. geographic, tollFree, mobile.", "enum": [ "geographic", "tollFree", "mobile" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberType", "modelAsString": true } }, "capabilities": { "$ref": "#/definitions/PhoneNumberCapabilities" }, "assignmentType": { "description": "The assignment type of the phone number. A phone number can be assigned to a person, or to an application.", "enum": [ "person", "application" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberAssignmentType", "modelAsString": true } }, "purchaseDate": { "format": "date-time", "description": "The date and time that the phone number was purchased.", "type": "string" }, "cost": { "$ref": "#/definitions/PhoneNumberCost" } } }, "PurchasedPhoneNumbers": { "description": "The list of purchased phone numbers.", "required": [ "phoneNumbers" ], "type": "object", "properties": { "phoneNumbers": { "description": "Represents a list of phone numbers.", "type": "array", "items": { "$ref": "#/definitions/PurchasedPhoneNumber" } }, "nextLink": { "description": "Represents the URL link to the next page of phone number results.", "type": "string" } } }, "PhoneNumbersBrowseRequest": { "description": "The parameters for the browse operation.", "required": [ "phoneNumberType" ], "type": "object", "properties": { "phoneNumberType": { "description": "Represents the number type of the offering.", "enum": [ "geographic", "tollFree", "mobile" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberType", "modelAsString": true } }, "capabilities": { "$ref": "#/definitions/PhoneNumberBrowseCapabilitiesRequest" }, "assignmentType": { "description": "Represents the assignment type of the offering. Also known as the use case.", "enum": [ "person", "application" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberAssignmentType", "modelAsString": true } }, "phoneNumberPrefixes": { "description": "The phone number prefix to match. If specified, the search will be limited to phone numbers that start with the any of the given prefixes.", "type": "array", "items": { "type": "string" }, "example": [ "1425", "1626" ] } } }, "PhoneNumberBrowseCapabilitiesRequest": { "description": "The minimum desired capabilities for the browse operation request.", "type": "object", "properties": { "calling": { "description": "Capability value for calling.", "enum": [ "none", "inbound", "outbound", "inbound+outbound" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberCapabilityType", "modelAsString": true } }, "sms": { "description": "Capability value for SMS.", "enum": [ "none", "inbound", "outbound", "inbound+outbound" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberCapabilityType", "modelAsString": true } } } }, "PhoneNumbersBrowseResult": { "required": [ "phoneNumbers" ], "type": "object", "description": "The result of a phone number browse operation.", "properties": { "phoneNumbers": { "description": "The phone numbers that are available for purchase.", "type": "array", "items": { "$ref": "#/definitions/AvailablePhoneNumber" } } } }, "AvailablePhoneNumber": { "required": [ "countryCode", "capabilities", "phoneNumberType", "assignmentType" ], "type": "object", "description": "Represents a phone number available in inventory", "properties": { "id": { "description": "The id of the phone number.", "type": "string", "readOnly": true }, "countryCode": { "description": "The ISO 3166-2 country code, e.g. US.", "type": "string" }, "phoneNumber": { "description": "The phone number in E.164 format, e.g. +11234567890.", "type": "string", "readOnly": true }, "capabilities": { "$ref": "#/definitions/PhoneNumberCapabilities" }, "phoneNumberType": { "description": "Represents the number type of the offering.", "enum": [ "geographic", "tollFree", "mobile" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberType", "modelAsString": true } }, "assignmentType": { "description": "Represents the assignment type of the offering. Also known as the use case.", "enum": [ "person", "application" ], "type": "string", "x-ms-enum": { "name": "PhoneNumberAssignmentType", "modelAsString": true } }, "cost": { "readOnly": true, "type": "object", "description": "The incurred cost for this phone number.", "allOf": [ { "$ref": "#/definitions/PhoneNumberCost" } ] }, "status": { "readOnly": true, "description": "Represents the status of the phone number. Possible values include: 'available', 'reserved', 'expired', 'error', 'purchased'.", "type": "string", "enum": [ "available", "reserved", "expired", "error", "purchased" ], "x-ms-enum": { "name": "AvailablePhoneNumberStatus", "modelAsString": true } }, "isAgreementToNotResellRequired": { "description": "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.", "type": "boolean", "readOnly": true }, "error": { "$ref": "#/definitions/AvailablePhoneNumberError" } } }, "AvailablePhoneNumberError": { "readOnly": true, "type": "object", "description": "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.", "properties": { "code": { "readOnly": true, "type": "string", "description": "The error code indicating the reason why the operation performed on the phone number failed." }, "message": { "readOnly": true, "type": "string", "description": "The error message describing the failure that occurred." } } }, "PhoneNumbersReservations": { "required": [ "reservations" ], "type": "object", "description": "Represents a list of phone numbers reservations. Note that the phone numbers from each reservation are not included.", "properties": { "reservations": { "description": "Represents a list of phone numbers reservations. Note that the phone numbers from each reservation are not included.", "type": "array", "items": { "$ref": "#/definitions/PhoneNumbersReservation" } }, "nextLink": { "description": "Represents the URL link to the next page of phone number results.", "type": "string" } } }, "PhoneNumbersReservation": { "type": "object", "description": "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.", "properties": { "id": { "description": "The id of the reservation.", "type": "string", "format": "uuid", "readOnly": true }, "expiresAt": { "description": "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.", "type": "string", "format": "date-time", "readOnly": true }, "phoneNumbers": { "type": "object", "description": "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.", "additionalProperties": { "$ref": "#/definitions/AvailablePhoneNumber", "x-nullable": true } }, "status": { "type": "string", "description": "Represents the status of the reservation. Possible values include: 'active', 'submitted', 'completed', 'expired'.", "readOnly": true, "enum": [ "active", "submitted", "completed", "expired" ], "x-ms-enum": { "name": "ReservationStatus", "modelAsString": true } } } }, "PhoneNumbersReservationPurchaseRequest": { "description": "The phone number search purchase request.", "type": "object", "properties": { "agreeToNotResell": { "description": "The agreement to not resell the phone numbers. Defaults to false if not provided.", "type": "boolean" } } }, "CommunicationErrorResponse": { "description": "The Communication Services error.", "type": "object", "required": [ "error" ], "properties": { "error": { "description": "The Communication Services error.", "$ref": "../../../Common/stable/2021-03-07/common.json#/definitions/CommunicationError" } } } }, "parameters": { "ApiVersionParameter": { "in": "query", "name": "api-version", "description": "Version of API to invoke", "required": true, "type": "string", "x-ms-parameter-location": "client" }, "Endpoint": { "in": "path", "name": "endpoint", "description": "The communication resource, for example https://resourcename.communication.azure.com", "required": true, "type": "string", "x-ms-skip-url-encoding": true, "x-ms-parameter-location": "client", "format": "url" }, "CountryCodeParameter": { "in": "path", "name": "countryCode", "description": "The ISO 3166-2 country code, e.g. US.", "required": true, "type": "string", "x-ms-parameter-location": "method" }, "MaxPageSizeParameter": { "in": "query", "name": "maxPageSize", "description": "An optional parameter for how many entries to return, for pagination purposes. The default value is 100.", "type": "integer", "format": "int32", "default": 100, "x-ms-parameter-location": "method" }, "ReservationIdParameter": { "in": "path", "name": "reservationId", "description": "The id of the reservation.", "required": true, "type": "string", "format": "uuid", "x-ms-parameter-location": "method" }, "ReservationParameter": { "in": "body", "name": "reservation", "description": "A representation of the desired state of the reservation.", "required": true, "schema": { "$ref": "#/definitions/PhoneNumbersReservation" }, "x-ms-parameter-location": "method" } }, "securityDefinitions": { "azure_auth": { "type": "oauth2", "flow": "implicit", "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", "scopes": { "user_impersonation": "impersonate your user account" }, "description": "Azure Active Directory OAuth2 Flow" } }, "x-ms-parameterized-host": { "hostTemplate": "{endpoint}", "useSchemePrefix": false, "parameters": [ { "$ref": "#/parameters/Endpoint" } ] } }