Get Specific Operator Connect Number

The Get Specific Operator Connect Number request retrieves a specific Operator Connect number on Live Platform. Numbers can be viewed in the Number Management page of the Multitenant portal (see Operator Connect Number Management using SBC). This request retrieves details for a single phone number, including its assignment status, capabilities, location information, and SBC configuration. Optionally, additional data such as civic address details or script parameters can be included in the response using the fields query parameter.

URL

Copy 
{{baseUrl}}/api/v2/oc/numbers/{phonenumber}

HTTP Method

GET

Request Headers

You can alternatively specify either of the following headers, both of which return identical output.

Attribute

Type

Description

X-Ovoc-Channel-Id

integer

The Live Platform channel id. When specified, data is scoped to only customers belonging to the specified channel. See Get List of Channels to extract this value.

X-IAM-Account-Id

string

The Live Platform iamAccountId of the channel. When specified, data is scoped to only customers belonging to the specified channel. See Get List of Channels to extract this value.

Request Parameters

Multiple fields can be configured using comma separation.

Parameter

Type

Mandatory

Description

PhoneNumber

string

Ö

The phone number to retrieve in E.164 format.

Phone numbers are validated according to the configuration of the customer Operator Settings on their Teams admin center. For example, if United Kingdom, France and Italy are configured then only phone numbers with Country codes for these countries can be uploaded, unless the "Geographic" option is configured above for the Type of Service.

Phone number validation rules are in accordance with E.164 format:

■ A + sign.
■ Country calling code (international).
■ Local area code.

Local telephone number or subscriber number.

It has the following structure: [+][country code][area code][subscriber number].

Example of a number with E.164 format in the United States

Telephone number: 415 123 1234

E.164 format number: +14151231234

■ Country code: +1
■ Area code: 415
■ Subscriber number: 1231234

Valid country code, per civic address and/or contact info of the given lead. See Country Dialing Codes

The leading "+" is optional and will be added automatically if missing. Maximum length: 100 characters.

civicAddress

string

´

Retrieves full civic address details of the tenants with "PhoneNumber".

● If the civic address is not found in the local database, the system automatically synchronizes civic addresses from Microsoft Teams and updates the local cache.
● Civic address synchronization may add a few seconds to the response time upon initial request.

scriptParameters

string

´

Retrieves all script parameters configured for "PhoneNumber". For example, ProxySet and CacProfile.

Script parameters with sensitive values (e.g. CarrierPassword) are masked with "****".

Example Requests

Copy 
/api/v2/oc/numbers/12129723736?fields=civicAddress

 

Copy 
/api/v2/oc/numbers/12129723736?fields=civicAddress,scriptParameters

Example Response without parameters

Copy 
{
    "uploadTelephoneNumberEntryId": 325390,
    "source": "webapi",
    "sbcList": [
        {
            "sbcName": "oc1.sandbox2.audiocodes.be [20.102.51.206]",
            "sbcId": 8
        }
    ],
    "id": 125796,
    "uploadToAccountJobId": 3185,
    "whenCreated": "2024-04-16T12:13:42.8160255+00:00",
    "acquiredNumberStatus": null,
    "telephoneNumber": "+442074996300",
    "callingProfileId": "5f3fbb3b-df9b-483d-b294-c7eb01e22aac",
    "acquiredCapabilities": [
        "Office365",
        "InboundCalling",
        "OutboundCalling",
        "UserAssignment"
    ],
    "availableCapabilities": [
        "FirstPartyAppAssignment",
        "Office365",
        "InboundCalling",
        "OutboundCalling",
        "UserAssignment",
        "Mobile"
    ],
    "acquiredOn": "2024-04-16T12:10:06.8660792+00:00",
    "isoCountryCode": "GB",
    "tnUploadJobId": "c82e3c6b-e845-4dc6-ac8d-6ff96a2b8efa",
    "locationId": null,
    "civicAddressId": null,
    "assignmentStatus": null,
    "tenantId": "f94238e5-4f2c-4e1b-8125-2d27122ca75f",
    "aslcht": null,
    "aslsct": null,
    "aslvCode": null,
    "asticks": null
}

Example Response with Civic addresses

Copy 
{
    "id": 122601,
    "uploadToAccountJobId": 5562,
    "whenCreated": "2026-07-02T18:08:08.6620073+00:00",
    "acquiredNumberStatus": 0,
    "telephoneNumber": "+12129723736",
    "callingProfileId": "4a5ed485-93bc-4b85-bc9b-fd7b2a8d8d10",
    "acquiredCapabilities": [
        "Geographic",
        "Office365",
        "InboundCalling",
        "OutboundCalling",
        "UserAssignment"
    ],
    "availableCapabilities": [
        "Geographic",
        "FirstPartyAppAssignment",
        "Office365",
        "InboundCalling",
        "OutboundCalling",
        "UserAssignment",
        "SharedCalling"
    ],
    "acquiredOn": "2026-07-02T18:07:49.2438385+00:00",
    "isoCountryCode": "US",
    "tnUploadJobId": "4b5e8c52-424e-405a-8a5e-8d314dfb169a",
    "locationId": "457f155b-3ca5-4456-a58d-9953cc2e6f28",
    "civicAddressId": "922b7390-181f-11f1-8e7f-09bc8a9784bc",
    "assignmentStatus": "Unassigned",
    "tenantId": "adcf0077-5bc8-47ad-9435-ce4ece9180ba",
    "aslcht": "2026-07-07T10:42:20.7746948+00:00",
    "aslsct": "2026-07-07T10:42:20.7746948+00:00",
    "aslvCode": 200,
    "asticks": 639190176602000443,
    "uploadTelephoneNumberEntryId": 295833,
    "source": "webapi",
    "sbcList": [
        {
            "sbcName": "EMEA SP1 SBC 02",
            "sbcId": 12
        }
    ],
    "tenantCallingProfileId": null,
    "ocSipConnectionName": null,
    "ocSipConnectionDescription": null,
    "umpCustomerGuid": "2791a49f-4e24-4c95-aede-3c90bcc28e69",
    "ovocChannelId": 97261,
    "consentedOn": null,
    "umpCustomerFullName": "Erez17_06_5FN",
    "msCompanyName": "Erez_2_7__0",
    "civicAddress": {
        "id": "922b7390-181f-11f1-8e7f-09bc8a9784bc",
        "country": "US",
        "houseNumber": "700",
        "houseNumberSuffix": "",
        "preDirectional": "",
        "streetName": "Eden Roc Drive",
        "streetSuffix": "",
        "postDirectional": "",
        "stateOrProvince": "OH",
        "countyOrDistrict": "US",
        "cityOrTown": "Xenia",
        "cityOrTownAlias": "",
        "postalOrZipCode": "45385",
        "description": "USA1",
        "companyName": "MSFT",
        "companyId": "",
        "defaultLocationId": "457f155b-3ca5-4456-a58d-9953cc2e6f28",
        "validationStatus": "Validated",
        "tenantId": "adcf0077-5bc8-47ad-9435-ce4ece9180ba",
        "partnerId": "00000000-0000-0000-0000-000000000000",
        "locations": [
            {
                "id": "457f155b-3ca5-4456-a58d-9953cc2e6f28",
                "civicAddressId": "922b7390-181f-11f1-8e7f-09bc8a9784bc",
                "description": "USA1",
                "additionalInfo": null,
                "isDefault": "true",
                "elin": null
            }
        ]
    },
    "infrastructureProvisioningStatus": "Ok"
}

Example Response with script parameters

Copy 
{
    "id": 122622,
    "uploadToAccountJobId": 5573,
    "whenCreated": "2026-07-07T08:26:06.4984089+00:00",
    "acquiredNumberStatus": 0,
    "telephoneNumber": "+61395554002",
    "callingProfileId": "fcdd70da-df67-4ac5-a9fa-5d69da190622",
    "acquiredCapabilities": [
        "Geographic",
        "Office365",
        "InboundCalling",
        "OutboundCalling",
        "UserAssignment"
    ],
    "availableCapabilities": [
        "Geographic",
        "FirstPartyAppAssignment",
        "Office365",
        "InboundCalling",
        "OutboundCalling",
        "UserAssignment",
        "SharedCalling"
    ],
    "acquiredOn": "2026-07-07T08:25:43.8332994+00:00",
    "isoCountryCode": "AU",
    "tnUploadJobId": "2c2d47c0-dc44-4a85-8d64-2fdec78683f9",
    "locationId": null,
    "civicAddressId": null,
    "assignmentStatus": "Unassigned",
    "tenantId": "3bc57cac-5794-457f-ad36-2c88cade9dbb",
    "aslcht": "2026-07-07T08:41:07.7743251+00:00",
    "aslsct": "2026-07-07T08:41:07.7743251+00:00",
    "aslvCode": 200,
    "asticks": 639190104677743251,
    "uploadTelephoneNumberEntryId": 295853,
    "source": "webapi",
    "sbcList": [
        {
            "sbcName": "APAC SP1 SBC",
            "sbcId": 8
        }
    ],
    "tenantCallingProfileId": null,
    "ocSipConnectionName": null,
    "ocSipConnectionDescription": null,
    "umpCustomerGuid": "a8401c93-31f5-439c-a21d-bc6b87ceee67",
    "ovocChannelId": 52262,
    "consentedOn": null,
    "umpCustomerFullName": "OCDevIP",
    "msCompanyName": "MSFT",
    "scriptParameters": {
        "CacProfile": "5 sessions",
        "ProxySet": "SIPTrunk",
        "OnlinePstnGateway": "sandbox3apac.audiocodes.be"
    },
    "infrastructureProvisioningStatus": "Ok"
}

HTTP Responses

■ 200 OK

Parameter

Type

Description

Id

string

Unique identifier of the uploaded number.

uploadToAccountJobId

integer

Job Id indicating when the number was uploaded.

whenCreated

string($date-time)

Timestamp at the commencement of the number retrieval.

acquiredNumberStatus

integer

One of the following values:

■ 0: Release Requested
■ 1: Marked for Removal
■ 2: Ready for Removal

telephoneNumber

string

List of retrieved telephone numbers.

callingProfileId

string

The Id string for the Microsoft Operator Connect Calling Profile that is attached to the tenant service (see Get Calling Profiles). Each Calling Profile is mapped to an SBC trunk used to manage call functionality for tenant service.

acquiredCapabilities

string

Capabilities acquired from the Calling profile. One of the following values:

From the drop-down choose one of the following values:

■ Inbound Calling with the following matching supported usages:
✔ CallingUserAssignment
✔ FirstPartyAppAssignment
✔ Conference Assignment
■ Outbound Calling with the following matching supported usages:
✔ CallingUserAssignment
✔ FirstPartyAppAssignment
✔ Conference Assignment
■ OC Mobile with the following matching supported usages:
✔ CallingUserAssignment
■ Mobile with the following matching supported usages:
✔ CallingUserAssignment
✔ FirstPartyAppAssignment

availableCapabilities

string

Capabilities available for configuration in the Calling profile:

■ Geographic
■ FirstPartyAppAssignment
■ Office365
■ InboundCalling
■ OutboundCalling
■ UserAssignment
■ SharedCalling

acquiredOn

string($date-time)

Timestamp indicating when the number was uploaded to customer tenant.

isoCountryCode

string

Country Calling dial code configured by customer in Teams admin center. See Country Dialing Codes for a full list of Dialing codes.

tnUploadJobId

string

Id for upload to customer account.

locationId

string

Id of the site location (see Get Services Brief Details (V3).

civicAddressId

string

Id of the civicAddress (see Get All OC Leads).

assignmentStatus

list

Indicates the type of number assignment in the Teams admin center:

■ UserAssigned: Assign number directly to a user.
■ ConferenceAssigned: Assign Service number to an Audio conferencing bridge.
■ VoiceApp: Assign Service number to an Auto attendant or Call queue.
■ ThirdPartyAppAssigned

tenantId

string

Customer tenant Azure subscription tenant Id.

aslcht

string($date-time)

Last successful assignment check time, updated each time after a successful verification.

If there are errors, do not update this field, and do not touch the status itself.

aslsct

string($date-time)

Last status change time (null if not known).

alsvcode

string

Last verification code, numeric, inspired from http status codes:

■ 200 OK
■ 500, 404
■ Set to null in case of never verified

asticks

string($date-time)

Ticks for the iteration session.

UploadTelephoneNumberEntryId

integer

Id generated at the start of the upload process.

source

string

Source interface of the uploaded number; webapi

sbcList

dictionary

sbcName -string

sbcId-integer

Dictionary including the following parameters:

■ sbcName: SBC FQDN and IP address, For example, oc1.sandbox2.audiocodes.be \[xx.xxx.xx.xxx\]
■ sbcId: SBC Id in Live Platform database.

tenantCallingProfileId

string

The Id of the Calling Profile record that is attached to the tenant service. A new record is created each time the template is attached to a customer service. Calling Profile Provisioning templates allow you to apply Calling Profile Templates when applying license (see Create OC Essential Service from Lead with IP Group), adding OC SIP Connections (see Add SIP Connections), uploading numbers (see Upload Operator Connect Numbers to Customer) and releasing numbers (see Release Operator Connect Numbers from Customer). You can then assign each Calling Profile Provisioning template to a different IP Group. For instance, you might want to configure an IP Group with enhanced security settings based on the site location's topology requirements and map it to a Calling Profile tailored for a specific carrier.

This value is assigned to services with IP Group-based SIP Connections; this method is currently not supported using the REST API.

ocSipConnectionName

string

The name of the OC SIP Connection (for services with SIP Connection type "IP Group").

This value is assigned to services with IP Group-based SIP Connections; this method is currently not supported using the REST API.

ocSipConnectionDescription

string

Short description of the OC SIP Connection.

This value is assigned to services with IP Group-based SIP Connections; this method is currently not supported using the REST API.

umpCustomerGuid

string($guid)

This value is created in the Live Platformcustomer tenant SQL database directory when a license is applied to the lead Create Service from Lead Overview).

This value is also obtained in the 'Get Task' response when the customer service is created.

ovocChannelId

integer

The Id of the Live Platform channel if the service is attached to a channel.

consentedOn

string($date-time

The date of consent by the Operator.

umpCustomerFullName

string

Full customer name

msCompanyName

string

MSFT

civicAddresses (this data is displayed when ?fields=civicAddress is configured as a Header parameter). If not specified and Civic addresses exist, then the Civic address Id value is displayed

dictionary

■ When civicAddress is configured as header parameter: list array
■ When civicAddress is not configured as header parameter: only "civicAddressId" value is retrieved (see above)

Dictionary including the following values:

■ id
■ country
■ houseNumber
■ houseNumberSuffix
■ preDirectional
■ streetName
■ streetSuffix
■ postDirectional
■ stateOrProvince
■ countyOrDistrict
■ cityOrTown
■ cityOrTownAlias
■ postalOrZipCode
■ description
■ companyName
■ companyId
■ defaultLocationId
■ validationStatus
■ tenantId
■ partnerId
■ locations:
✔ id
✔ civicAddressId
✔ description
✔ additionalInfo
✔ isDefault
✔ elin

scriptParameters (this data is displayed when ?fields=scriptParameters is configured as Header parameter)

dictionary

List array including any configured script parameters. For example, CacProfile, Proxy Set or OnlinePstnGateway values.

infrastructureProvisioningStatus

string

Ok
■ 403 Forbidden: This error raised when the telephone number specified in the Request parameter belongs to a customer that is not associated with the channel specified in the Request header.

Parameter

Type

Description/Examples

errors

string

 Text description of the error.

type

string

"https://tools.ietf.org/html/rfc7231#section-6.5.1"

title

string

Email title. For example "One or more validation errors occurred."

status

error code

HTML error code i.e. 400

detail

string

Additional error details.

traceId

string

Error trace Id

instance

string

Error instance

errorTicket

string

This field may not appear for all return codes.

errorCode

string

This field may not appear for all return codes.

additionalProp1

string

Custom Script variable argument. For example "CacProfile": "5 sessions"

additionalProp2

string

Custom Script argument. For example, ProxySet": "SIPTrunk"

additionalProp3

string

Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"
■ 404 Not Found: For example, this error is raised when the phone number request parameter does not exist in Live Platform. In the event where the conditions for the raising of a 403 Forbidden error are also met, then the 404 Not Found error takes precedence.

Parameter

Type

Description/Examples

errors

string

 Text description of the error.

type

string

"https://tools.ietf.org/html/rfc7231#section-6.5.1"

title

string

Email title. For example "One or more validation errors occurred."

status

error code

HTML error code i.e. 400

detail

string

Additional error details.

traceId

string

Error trace Id

instance

string

Error instance

errorTicket

string

This field may not appear for all return codes.

errorCode

string

This field may not appear for all return codes.

additionalProp1

string

Custom Script variable argument. For example "CacProfile": "5 sessions"

additionalProp2

string

Custom Script argument. For example, ProxySet": "SIPTrunk"

additionalProp3

string

Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"
■ 500 Internal Server Error