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 work flow 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 (e.g. Capabilities) does not cause a roll back for another scope (e.g. Configuration).

■ Backend Scopes: Live Platform classifies each field in the request into one of the following scopes:
● Capabilities: capabilities field 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 pre-flight checks before the workflow process commences are described below. In the event where these checks fail, "400: Bad Request" is returned.
● Numbers list must have at least one entry (EMPTY_NUMBER_LIST).
● Null entries are not allowed in the Numbers array (NULL_ENTRIES).
● No duplicate telephone numbers within the same request (DUPLICATE_NUMBERS).
● Each entry must have at least one non-null patchable field (NO_FIELDS_SPECIFIED).
● Each Add/Remove Usage/Capability must include at least one item (EMPTY_DELTA).
● Telephone numbers must be in E.164 format (e.g. +14155551234) (INVALID_PHONE_FORMAT).
● All numbers must exist in the acquired numbers inventory (NUMBERS_NOT_FOUND).
● scriptParameters cannot be provided without scriptTemplateId (SCRIPT_TEMPLATE_REQUIRED).
● The referenced scriptTemplateId must exist (SCRIPT_TEMPLATE_NOT_FOUND).
● Numbers in the SBC Script scope must be programmed on at least one SBC (NO_SBCS_PROGRAMMED).
● SBC Script scope is limited to 500 numbers per request (BUCKET_LIMIT_EXCEEDED).
■ Concurrency: If any number in the batch has a pending operation in the same scope, the entire request is rejected. In this case, a 409 error is returned with the following: CONCURRENT_OPERATION and a lockedNumbers array listing the conflicting numbers.
■ Infrastructure Error State: 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:
● 409 with errorCode: NUMBER_IN_INFRASTRUCTURE_ERROR_STATE and an errorStateNumbers array.

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 Parameters

Parameter

Type

Description

msTenantId

string

Microsoft TenantId (Azure Tenant ID of the customer).

Request Body

Parameter

Type

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 (add and removed).

 

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

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 parenthesis):

■ 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.

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 V

CustomVar.Variable<VariableSequenceNumber>

string

The Proxy Set name.

additionalProp2

CustomVar.Variable<VariableSequenceNumber>

string

The CAC Profile value. For example,

additionalProp3

CustomVar.Variable<VariableSequenceNumber>

string

The OnlinePstnGateway name.

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

■ 200 OK

Parameter

Type

Description
id

string

Task Id

status

string

Task status is one of the following

■ In Progress
■ Completed Successful
■ Completed Failed

The cache mechanism used to Upload numbers is according to Distributed Cache.

details

string

One of the following values:

■ Numbers uploaded: Numbers uploaded successfully
■ InvalidTelephonesError: Numbers entered incorrectly
■ MsProgrammingError: Number could not be configured on Microsoft.

executionMessages

list array

This list array includes the following parameters:

■ level
■ message

level

string

One of the following values:

■ Information
■ Error

message

string

The following 'Information' messages may appear:

■ 'Input is valid': Indicates that Telephone syntax entered is valid.
■ 'Duplicates: <PhoneNumbers>': Indicates that phone number already exists in the database.
■ 'All uploaded numbers are not present in Microsoft context': Numbers have not yet been updated on Microsoft.
■ Site found: The Live Platform IP Group link between Live Platform and SBC device has been found.
■ Number(s) accepted by Microsoft: Numbers are approved by Microsoft.
■ UploadToAccount job status:
✔ In Progress
✔ Success
■ Moving on: starting processing of next number.
■ Telephone numbers programmed in SBC and in Live Cloud database': Numbers have been updated on both SBC and Live Platform.
■ Workflow completed: End of upload process.

The following 'Error' messages may appear:

■ upload telephone numbers to Microsoft: Partner '{Microsoft Tenant Id}' does not support Offer Types [Calling] in country '{Country Abbreviation Code}': Region number that you are attempting to upload is not partnered with the operator (as configured in customer Teams admin center). For example, configured regions are Australia and Canada and you are attempting to upload an Italy number.

The following are example error messages:

■ Invalid Telephones Number (in this case, the number already existed in the database):
Copy 
{
    "id": "wup_2bd5ed7d-7eb1-44b7-88cf-6be495ccd420",
    "status": "CompletedFailed",
    "details": [
        "InvalidTelephonesError"
    ],
    "executionMessages": [
        {
            "level": "Error",
            "message": "Duplicates: +97239764533"
        },
        {
            "level": "Information",
            "message": "Workflow completed."
        }
    ],
    "outputData": {
        "CreateTime": "2023-09-21T10:53:44.6292124Z",
        "CompleteTime": "2023-09-21T10:53:44.8276113Z",
        "OcUploadNumberResult": "InvalidTelephonesError",
        "WorkflowVersion": 3
    }
}
■ Invalid Telephone Number (invalid phone number syntax). When the Request Body includes the following
Copy 
{
"callingProfile": "ab86ef82-ce9e-4ead-befb-4aa954b64872",
"usage": "CallingUserAssignment",
"additionalUsages": ["FirstPartyAppAssignment"],
"capabilities": ["InboundCalling", "OutboundCalling"],
"phoneNumberRanges": [

    {

      "start": "+448718943002",

      "end": "++448718943009"

    }

  ],
"workflowVersion": 3,
"country": "GB"
}

The following error is raised because the

Copy 
{
    "id": "wup_9e7f5e3f-a51f-43aa-85c9-f7b9508b6924",
    "status": "CompletedFailed",
    "details": [
        "InvalidTelephonesError"
    ],
    "executionMessages": [
        {
            "level": "Error",
            "message": "No telephone numbers to validate."
        },
        {
            "level": "Information",
            "message": "Workflow completed."
        }
    ],
    "outputData": {
        "ocUploadNumberResult": "InvalidTelephonesError",
        "workflowVersion": 3,
        "msJobStatus": ""
    },
    "createTime": "2026-02-17T09:40:27.4969529Z",
    "completeTime": "2026-02-17T09:40:27.5430781Z"
}
■ "message": "upload telephone numbers to Microsoft: Partner '7a4e58a1-8348-4fa5-8d36-4e19125e4ac3' does not support Offer Types [Calling] in country 'NL'. This message is displayed if you generated a consented lead and then tried to upload a number for a country that was not configured in the customer Teams admin center.
Copy 
{
    "id": "wup_7e3ca019-c34e-4ff7-883e-e592c54d2c03",
    "status": "CompletedFailed",
    "details": [
        "MsProgrammingError"
    ],
    "executionMessages": [
        {
            "level": "Information",
            "message": "Input is valid."
        },
        {
            "level": "Information",
            "message": "All uploaded numbers are not present in Microsoft context."
        },
        {
            "level": "Information",
            "message": "Site GRXRATNEUZMNZ found."
        },
        {
            "level": "Error",
            "message": "upload telephone numbers to Microsoft: Partner '7a4e58a1-8348-4fa5-8d36-4e19125e4ac3' does not support Offer Types [Calling] in country 'NL'."
        },
        {
            "level": "Information",
            "message": "Workflow completed."
        }
    ],
    "outputData": {
        "CreateTime": "2023-10-09T14:40:19.0541215Z",
        "CompleteTime": "2023-10-09T14:40:22.0420167Z",
        "OcUploadNumberResult": "MsProgrammingError",
        "WorkflowVersion": 3,
        "SbcIdList": [
            8
        ],
        "MsJobStatus": ""
    }
}

When attempting to upload a a Toll-free number with the usage "CallingUserAssignment".

Copy 
"usage": "CallingUserAssignment",
"capabilities": ["InboundCalling", "OutboundCalling"],
"phoneNumbers": ["+18000900790"],
"workflowVersion": "3",
"country": "US"
}

The following error message is displayed as Toll-free numbers must be configured with the usage 'FirstPartyAppAssignment'.

Copy 
{
    "id": "wup_d62adf69-47c6-44bb-83e0-dfc632a2eca0",
    "status": "CompletedFailed",
    "details": [
        "MsProgrammingError"
    ],
    "executionMessages": [
        {
            "level": "Information",
            "message": "Input is valid."
        },
        {
            "level": "Information",
            "message": "All uploaded numbers are not present in Microsoft context."
        },
        {
            "level": "Information",
            "message": "Site GRYXIKLDOVPLU found."
        },
        {
            "level": "Error",
            "message": "upload telephone numbers to Microsoft: Plan/Usage 'Calling User Assignment' does not support Toll Free TNs upload."
        },
        {
            "level": "Information",
            "message": "Workflow completed."
        }
    ],
    "outputData": {
        "createTime": "2024-05-07T15:02:02.8461328Z",
        "completeTime": "2024-05-07T15:02:13.3898797Z",
        "ocUploadNumberResult": "MsProgrammingError",
        "workflowVersion": 3,
        "sbcIdList": [
            8
        ],
        "msJobStatus": ""
    },
    "createTime": "0001-01-01T00:00:00"
}

The following message is displayed if there are no SBC devices assigned to the Calling Profile and therefore you cannot make or receive calls to this number.

Copy 
{
    "errors": {
        "CallingProfile": [
            "There are no SBCs assigned to this calling profile!"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-ce7db116205054eee1c59c80ebe7f48d-d5a3edc4aadfc80d-00"
}

outputData

List array

 

This array includes the following parameters:

■ CreateTime
■ CompleteTime
■ OcUploadNumberResult
■ NumbersUploaded
■ WorkflowVersion
■ SbcIdList
■ MsJobWhenUpdated
■ MsJobId
■ MsJobStatus

CreateTime

string($date-time)

Timestamp at the commencement of the number upload.

CompleteTime

string($date-time)

Timestamp at the completion of the number upload.

OcUploadNumberResult

string

One of the following values:

■ NumbersUploaded
■ InvalidTelephonesError
■ MsProgrammingError

WorkflowVersion

integer

Version of the Workflow API.

SbcIdList

integer

Id of the SBC device in the Live Platform database.

MsJobWhenUpdated

string($date-time)

Timestamp when the Microsoft tenant platform was updated with the new number.

MsJobId

string

Id of the job to update the Microsoft platform.
■ 400 Bad Request: The following error message is raised when numbers are not found.
Copy 
{
  "status": 400,
  "title": "Numbers Not Found",
  "errorCode": "NUMBERS_NOT_FOUND",
  "invalidNumbers": ["+14155559999"],
  "traceId": "00-abc123-def456-00"
}
■ 409 Conflict: The following error is raised when there is a concurrent operation in progress
Copy 
{
  "status": 409,
  "title": "Concurrent Operation",
  "errorCode": "CONCURRENT_OPERATION",
  "lockedNumbers": ["+14155551234"],
  "traceId": "00-abc123-def456-00"
}
■