Upload Operator Connect Numbers Patch

The Upload Operator Connect Numbers Patch request lets you update specific Operator Connect number properties and then asynchronously update the Microsoft platform. A workflow process is implemented to streamline the synchronization mechanism. This process groups numbers for each Microsoft tenant and processes each scope independently. A failure in the processing for one scope, for example, "Capabilities" does not cause a rollback for another scope, for example, "Configuration".

■ Backend Scopes: Live Platform processes each parameter in the request into one of the following scopes:
● Capabilities: capabilities parameter that is processed using Microsoft tn-capability-update API.
● Configuration: callingProfileId, locationId, usage, additionalUsages, allowedCustomerActions, routingOptions that is processed using Microsoft tn-update-orders API.
● SbcScript: scriptTemplateId, scriptParameters. Executes a Handlebars script template on all SBC devices where the numbers are stored. Limit: 500 numbers per request in this scope.
■ Validation Rules: Synchronous checks before the workflow process commences. In the event where these checks fail, "400: Bad Request" is returned (scenarios are described in 400 Bad Request: Bad requests may result from one of the following scenarios:).

Rate Limit

This request has a global rate limit of 300 calls per minute. Exceeding this limit will result in a HTTP 429: Too Many Requests error.

URI

Copy 
{{baseUrl}}/api/v3/oc/numbers

HTTP Method

PATCH

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

Parameter

Type

Mandatory

Description

msTenantId

string

´

Microsoft TenantId (Azure Tenant ID of the customer).

Request Body

Parameter

Type

Mandatory

Description

idempotencyKey

string

´

An idempotencyKey is used to enable safe retries to prevent sending duplication requests to Microsoft for update actions to the same number.

■ Same key + same payload → 202 with the original task ID (no new workflow is started).
■ Same key + different payload → 409 with errorCode: IDEMPOTENCY_CONFLICT.

ticket ID

Related Service Request ticket (see Managing Service Requests).

´

Ticket ID

numbers

list array

Ö

A list of telephone numbers including capabilities (added and removed).

■ Numbers list must include at least one entry.
■ Null entries are not allowed in the Numbers array.
■ No duplicate telephone numbers within the same request.
■ Numbers in the SBC script scope must be configured in a dial plan on at least one SBC.
■ All numbers must exist in the acquired numbers inventory.
■ 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.

capabilities
■ The list of added capabilities
■ The list of removed capabilities

Each Add/Remove Usage/Capability must include at least one item.

´

One of the following values with matching supported usages (see above) (configure bolded value):

■ InboundCalling
✔ CallingUserAssignment
✔ FirstPartyAppAssignment
✔ ConferenceAssignment
■ OutboundCalling
✔ CallingUserAssignment
✔ FirstPartyAppAssignment
✔ ConferenceAssignment
■ OCMobile
✔ CallingUserAssignment
■ Mobile
✔ CallingUserAssignment
✔ FirstPartyAppAssignment

 

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.

locationId

string

´

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

usage

integer

´

One of the following values (mapping to Teams admin center values is shown in parentheses):

■ CallingUserAssignment (User): Assign regular number directly to a user.
■ FirstPartyAppAssignment (Voice app): Assign Service number to an Auto-attendant or Call queue. This option can be used for uploading Toll-free numbers. For example, +18000900770. When configuring Toll-free numbers you must also configure the 'Displayed Country Code' location (see below).
■ ConferenceAssignment (Audio Conferencing): Assign number to an Audio conferencing bridge.
■ ThirdPartyAppAssignment: Assign Third-party applications to users to integrate and manage external applications, such as telephony services provided by third-party operators.

Verify that the 'ThirdPartyAppAssignment' value is supported on your Microsoft tenant.

additionalUsage
■ The list of added AdditionalUsage
■ The list of removed AdditionalUsage


´

Support for an Additional usage type. For example if you configure 'CallingUserAssignment' as the Usage, then you can choose 'Conference Assignment' or 'FirstPartyAppAssignment' for the Additional Usage.

Configuration of Additional usage requires workflow Version 3.

allowedCustomerActions
■ The integer value of allowed Customer actions
■ The integer value of removed Customer actions

´

For future use

routingOptions
■ The integer value of allowed routingOptions
■ The integer value of removed routingOptions

´

For future use

scriptTemplateId

integer

´

The unique id of the script. See SBC Template Scenarios for references to IDs for default SBC script templates. See M365 Template Scenarios for references to IDs for default M365 script templates.

This value is mandatory if you configure script parameters (see below).

scriptParameters refers to:

CustomVar.Variable<VariableSequenceNumber>

dictionary

where <VariableSequenceNumber> is the sequence in database that the variable is defined in the 'Customer variables' column for the script properties (see Customer Variables).

For example, when the following IP-PBX variables are defined in the database in the order: IPPBX-ProxyAddress, IPPBX-ProxyAddress-SIPPort, SIP-HostName then Custom variables should be defined as follows:

■ CustomVar.Variable1: <: IPPBX-ProxyAddress>
■ CustomVar.Variable2: < IPPBX-ProxyAddress-SIPPort>
■ CustomVar.Variable3: <SIP-HostName>

 

´

Custom variables can be defined to update specific parameters on the SBC device. These variables must be predefined in the UMP-365 database (see Customer Variables). Also verify that the custom variables notation has been added to the script (see parameter 'sbcOnboardingScript' above) that you are applying to the request.

There are three fields displayed in the schema additionalProp1-3, however there is no limitation for the number of variables that can be added.

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"

Example Request Body

Copy 
{
         
  "idempotencyKey": "r2c4d3d5-vbgt-6540-erfu-ef1234554380",
  "ticketId": "TICKET-001",
  "numbers": [
    {
      "telephoneNumber": "+61395557002",
      "callingProfileId": "fcdd70da-df67-4ac5-a9fa-5d69da190622",
      "capabilities": { "add": ["InboundCalling"], "remove": [] }
    },
    {
      "telephoneNumber": "+61395557004",
      "scriptTemplateId": 2020,
      "scriptParameters": { "ProxySet": "SIPTrunk" }
    }
  ]
}

202 Accepted Response

The initial response displays the Task Id.

Parameter

Type

Description

Task Id

string

The queued task Id that is generated for this action. You must run the Task request to retrieve the status of the action. See Task Status. Note that the wup string in the prefix is unique for this endpoint.
Copy 
{
    "taskId": "wup_c14a0a55-fcc5-4598-b405-c978e7da1af4"
}

The execution of the request may take a few minutes. The status will progress from 'In Progress' to 'Completed Success'.

Copy 
{
    "numbers": [
        {
            "number": "+61395557002",
            "status": "Submitted",
            "failures": null
        },
        {
            "number": "+61395557004",
            "status": "Pending",
            "failures": null
        }
    ],
    "id": "ocn_p_14ce135c-15f1-4ff2-be62-4760a7d30a2d",
    "status": "Queued",
    "executionMessages": [
        {
            "level": "User",
            "message": "Starting patch operation for 2 number(s) across 1 tenant(s)."
        },
        {
            "level": "Information",
            "message": "Started child workflow c6906169-c565-4b94-8a69-3ba618e9225c for tenant '3bc57cac-5794-457f-ad36-2c88cade9dbb'."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Locking 2 number(s) for exclusive access."
        },
        {
            "level": "User",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Acquired exclusive access to 2 number(s)."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Lock acquired."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Submitting capability update for 1 number(s)."
        },
        {
            "level": "User",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Capability update submitted to Microsoft Operator Connect."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Capability update order submitted (MS order: c6774da1-3227-4de5-ba33-cc099d2e0ed4)."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Checking capability update status (attempt 1/15, MS order: c6774da1-3227-4de5-ba33-cc099d2e0ed4)."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Capability update in progress. Next check in 60s."
        }
    ],
    "outputData": {},
    "createTime": "2026-07-07T08:16:54.6103857Z"
}

 

Copy 
{
    "numbers": [
        {
            "number": "+61395557002",
            "status": "Completed",
            "failures": null
        },
        {
            "number": "+61395557004",
            "status": "Completed",
            "failures": null
        }
    ],
    "id": "ocn_p_14ce135c-15f1-4ff2-be62-4760a7d30a2d",
    "status": "CompletedSuccess",
    "executionMessages": [
        {
            "level": "User",
            "message": "Starting patch operation for 2 number(s) across 1 tenant(s)."
        },
        {
            "level": "Information",
            "message": "Started child workflow c6906169-c565-4b94-8a69-3ba618e9225c for tenant '3bc57cac-5794-457f-ad36-2c88cade9dbb'."
        },
        {
            "level": "Information",
            "message": "Detected child c6906169-c565-4b94-8a69-3ba618e9225c completed (status=Complete); 1/1 done."
        },
        {
            "level": "User",
            "message": "Patch operation completed: 1 of 1 tenant(s) succeeded."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Locking 2 number(s) for exclusive access."
        },
        {
            "level": "User",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Acquired exclusive access to 2 number(s)."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Lock acquired."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Submitting capability update for 1 number(s)."
        },
        {
            "level": "User",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Capability update submitted to Microsoft Operator Connect."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Capability update order submitted (MS order: c6774da1-3227-4de5-ba33-cc099d2e0ed4)."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Checking capability update status (attempt 1/15, MS order: c6774da1-3227-4de5-ba33-cc099d2e0ed4)."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Capability update in progress. Next check in 60s."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Checking capability update status (attempt 2/15, MS order: c6774da1-3227-4de5-ba33-cc099d2e0ed4)."
        },
        {
            "level": "User",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Capability update confirmed by Microsoft."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Capability update completed successfully."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Submitting configuration update for 1 number(s)."
        },
        {
            "level": "User",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Configuration update submitted to Microsoft Operator Connect."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Configuration update order submitted (MS order: 138ddbfe-8d02-47bc-a6c1-ac3431c4619e)."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Checking configuration update status (attempt 1/15, MS order: 138ddbfe-8d02-47bc-a6c1-ac3431c4619e)."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Configuration update in progress. Next check in 60s."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Checking configuration update status (attempt 2/15, MS order: 138ddbfe-8d02-47bc-a6c1-ac3431c4619e)."
        },
        {
            "level": "User",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Configuration update confirmed by Microsoft."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Configuration update completed successfully."
        },
        {
            "level": "User",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Exclusive access released."
        },
        {
            "level": "Information",
            "message": "[Tenant: 3bc57cac-5794-457f-ad36-2c88cade9dbb] Lock released."
        }
    ],
    "outputData": {},
    "createTime": "2026-07-07T08:16:54.6103857Z",
    "completeTime": "2026-07-07T08:19:21.6337647Z"
}

HTTP Responses

■ 202 Accepted

The initial response displays the Task Id.

Parameter

Type

Description

taskId

string

The queued task Id that is generated for this action. You must run the Task request to retrieve the status of the action. See Task Status. Note that the tsk_ms_job string in the prefix is unique for this endpoint.
Copy 
{
    "taskId":ocn_p_3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

The execution of the request may take a few minutes. The status will progress from 'In Progress' to 'Completed Success'. The time execution of the request depends on the connection with Microsoft Operator Connect.

■ 400 Bad Request: Bad requests may result from one of the following scenarios:
● The number list array is empty
● Duplicate telephone numbers are specified in the list
● The Add or Remove capability list array is empty
● Numbers specified are not in the valid E.164 format
● Numbers specified do not exist in the number inventory
● Script parameters have been configured, however, a scriptTemplateId has not been configured
● The specified scriptTemplateId does not exist
● Numbers specified have not been configured on the SBC
● The request exceeds 500 numbers
Copy 
{
  "status": 400,
  "title": "Numbers Not Found",
  "errorCode": "NUMBERS_NOT_FOUND",
  "invalidNumbers": ["+14155559999"],
  "traceId": "00-abc123-def456-00"
}
■ 403 Forbidden: This error is raised when the request parameter for the customer Microsoft tenant does not belong to the channel as specified in the request header values X-Ovoc-Channel-Id or X-IAM-Account-Id. The numbers specified in the Request Body belonging to the specified tenant are listed under invalidNumbers.

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"
■ 409 Conflict:  
● If any number in the batch has a pending operation in the same scope, the entire request is rejected. In this case, the following error is returned including a list array of the conflicting (locked) numbers.
Copy 
{
  "status": 409,
  "title": "Concurrent Operation",
  "errorCode": "CONCURRENT_OPERATION",
  "lockedNumbers": ["+14155551234"],
  "traceId": "00-abc123-def456-00"
}
●  If a previous SBC script scope failure arose on any number, this number is blocked from further PATCH operations until the following error is cleared:

NUMBER_IN_INFRASTRUCTURE_ERROR_STATE and an errorStateNumbers array.