Release Operator Connect Numbers from Customer

The Release Operator Connect Numbers from Customer request releases Operator Connect numbers from the customer tenant. Number Release requests are sent to Operator Connect to validate the request. Numbers are released from both from Live Platform and Operator Connect.

■ Request Handling rules:
● Phone numbers must be currently assigned to the specified Microsoft tenant
● Released numbers become available for assignment to other tenants
● The operation is processed asynchronously to handle large ranges efficiently
● Rate limiting applies to prevent system overload (10 requests per 10 seconds)
● For Ranges:
❖ All SBCs (Session Border Controllers) associated with the tenant must be online before processing
❖ The operation is processed asynchronously to handle large ranges efficiently
❖ Range expansion is performed server-side to generate individual phone numbers
■ Number Validation rules:
● Microsoft tenant ID must be a valid GUID format
● Phone numbers must be in E.164 format (see below)
● Maximum number of phone numbers per request is configurable (default limit applies)
● Phone numbers cannot be currently processing in another operation
● Request body cannot be empty or null
● For Ranges:
❖ Range start number must be less than or equal to range end number
❖ Range must be able to generate at least one valid phone number
❖ All associated SBCs must be online and accessible
● When deleting using the REST API, only numbers belonging to the same Tenant Id can be deleted in the same action; numbers cannot be deleted per service.
● Assigned numbers must be unassigned before they can be released (see Unassign Numbers).

URI - Release with Single Numbers

Copy 
{{baseUrl}}/api/v2/oc/numbers/action/release?msTenantId={{msTenantId}}

URI - Release with Range

Copy 
{{baseUrl}}/api/v2/oc/numbers/action/release/range?msTenantId={{msTenantId}}

 

HTTP Method

POST

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

Mandatory

Type

Description

msTenantId

Ö

string

The Microsoft Azure subscription Tenant Id of the customer.

Request Body

The Request Body includes the phone number that you wish to release.

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

Example Request with Single Number

Copy 
[
"+61395556880"
]

Example Request with Multiple Numbers

Copy 
[
"+31206319190","+31206319192","+31645487594","+31365461299"
]

Example Request with Range

Phone number ranges should be configured as follows:

Copy 
"phoneNumberRanges": [
{
"start": "+97239764660",
"end": "+97239764670"
}

HTTP Responses

■ 200 OK

Example Response

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": "release_task_67800"
}

The execution of the request may take a few minutes. The status will progress from 'In Progress' to 'Completed Success'. See Number Release Task Status for details. The time execution of Release numbers request depends on the connection with Microsoft Operator Connect.

Example Response (In Progress)

Copy 
{
    "totalNumbersCount": 4,
    "id": "taskId": "release_task_67800",
    "status": "InProgress",
    "details": [
        "{\"Id\":\"67800\",\"TenantId\":\"c524b5f5-fd18-43c0-964c-bc5d35525eaa\",\"Status\":\"Complete\",\"CreatedAt\":\"2025-05-04T16:42:49.3916376+00:00\",\"CreatedBy\":\"AppId: \\u00277b771eea-e15a-4898-ad1a-8f6be5f1b0bd\\u0027\",\"TelephoneNumbers\":[{\"TelephoneNumber\":\"\\u002B31206319190\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\\u002B31206319192\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\\u002B31645487594\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\\u002B31365461299\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null}],\"ErrorMessage\":null}"
    ],
    "executionMessages": [],
    "outputData": {
        "msReleaseJobId": "67800",
        "msTenantId": "c524b5f5-fd18-43c0-964c-bc5d35525eaa",
        "msReleaseJobStatus": "Complete",
        "umpReleaseJobStatus": "Pending",
        "msReleaseJobCreatedAt": "5/4/2025 4:42:49 PM +00:00",
        "msReleaseJobCreatedBy": "AppId: '7b771eea-e15a-4898-ad1a-8f6be5f1b0bd'",
        "pendingIntervention": false
    },
    "createTime": "2025-05-04T16:42:49.7459336"
}

Example Response (Completed Success)

Copy 
{
    "totalNumbersCount": 4,
    "id": "67800",
    "status": "CompletedSuccess",
    "details": ["{\"Id\":\"67800\",\"TenantId\":\"c524b5f5-fd18-43c0-964c-bc5d35525eaa\",\"Status\":\"Complete\",\"CreatedAt\":\"2025-05-04T16:42:49.3916376+00:00\",\"CreatedBy\":\"AppId: \'7b771eea-e15a-4898-ad1a-8f6be5f1b0bd\'\",\"TelephoneNumbers\":[{\"TelephoneNumber\":\"\+31206319190\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\+31206319192\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\+31645487594\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\+31365461299\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null}],\"ErrorMessage\":null}"
    ],
    "executionMessages": [],
    "outputData": {
        "msReleaseJobId": "67800",
        "msTenantId": "c524b5f5-fd18-43c0-964c-bc5d35525eaa",
        "msReleaseJobStatus": "Complete",
        "umpReleaseJobStatus": "Complete",
        "msReleaseJobCreatedAt": "5/4/2025 4:42:49 PM +00:00",
        "msReleaseJobCreatedBy": "AppId: '7b771eea-e15a-4898-ad1a-8f6be5f1b0bd'",
        "pendingIntervention": false
    },
    "createTime": "2025-05-04T16:42:49.7459336"
}

Response with Multiple Numbers

Copy 
{
    "totalNumbersCount": 5,
    "id": "tsk_msjob_0a57213a-351a-42cc-92db-c00eb29fb465",
    "status": "CompletedSuccess",
    "details": [
        "{\"Id\":\"0a57213a-351a-42cc-92db-c00eb29fb465\",\"TenantId\":\"2fa5f129-04db-4dd4-ba63-7bd45ba59538\",\"Status\":\"Complete\",\"CreatedAt\":\"2023-11-07T20:16:05.5065971+00:00\",\"CreatedBy\":\"AppId: \\u00277b771eea-e15a-4898-ad1a-8f6be5f1b0bd\\u0027\",\"TelephoneNumbers\":[{\"TelephoneNumber\":\"\\u002B97239764578\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\\u002B97239764579\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\\u002B97239764584\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\\u002B97239764585\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\\u002B97239764586\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null}],\"ErrorMessage\":null}"
    ],
    "executionMessages": null,
    "outputData": {
        "MsReleaseJobId": "0a57213a-351a-42cc-92db-c00eb29fb465",
        "MsTenantId": "2fa5f129-04db-4dd4-ba63-7bd45ba59538",
        "MsReleaseJobStatus": "Complete",
        "UmpReleaseJobStatus": "Complete",
        "MsReleaseJobCreatedAt": "11/7/2023 8:16:05 PM +00:00",
        "MsReleaseJobCreatedBy": "AppId: '7b771eea-e15a-4898-ad1a-8f6be5f1b0bd'",
        "PendingIntervention": false
    }
}

You can optionally run the Get Operator Connect Customer Numbers V2 request to check that the number has been removed.

Parameter

Type

Description

totalNumbersCount

integer

Total number of numbers released.

id

string

The task Id that is generated for this action. See Task Status.

status

string

Aggregated status reflecting update status on both the Live Cloud and Operator Connect platforms:

■ In Progress
■ Completed Success
■ Completed Failed

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

details

string

Details includes the following values:

■ Id (task Id)
■ Tenant Id (customer Tenant Id)
■ Status
■ Created At string($date-time)
■ Created By string ($date-time)
■ App Id (customer Tenant App Id)
■ Telephone Numbers:
✔ Telephone Number
✔ Corresponding status for each number
✔ Corresponding Error Code for each number
✔ Corresponding Error Message for each number

executionMessages

null

 Internal debugging messages.

outputData

dictionary

List array including the following parameters:

■ MsReleaseJobId
■ MsTenantId
■ MsReleaseJobStatus
■ UmpReleaseJobStatus
■ MsReleaseJobCreatedAt
■ MsReleaseJobCreatedBy
■ PendingIntervention

MsReleaseJobId

string

Task Id

MsTenantId

string

Microsoft Tenant customer subscription Id.

MsReleaseJobStatus

string

Indicates the status of the number release request on the Microsoft platform:

■ Pending
■ InProgress
■ Complete
■ Error
■ Failed

UmpReleaseJobStatus

string

Indicates the status of the number release request on the Live Cloud platform:

■ Pending
■ InProgress
■ Complete
■ Error
■ Failed

MsReleaseJobCreatedAt

($date-time)

Timestamp indicating when the Microsoft Job was created.

MsReleaseJobCreatedBy

string

App (Client) Id of the Rest API tenant (seeAuthenticating Connection Using Postman).

PendingIntervention

string

Indicates whether internal debugging is required.

createTime

($date-time)

Timestamp indicating when the Job is successfully completed.

In case you wish to “move/edit” an Operator Connect acquired number, you have to release the number and then reupload the number, with the new parameters. After initiating the release operation, check the status of release job until the status is “CompletedSuccess”. This process may take several minutes.

■ 400 Bad Request: Failure to Release Telephone Numbers
Copy 
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "Bad Request",
    "status": 400,
    "detail": "Fail to release telephone numbers: Numbers: [+97239764535] do not belong to the Tenant: 2fa5f129-04db-4dd4-ba63-7bd45ba59538.",
    "traceId": "00-ba6c5c1dc3f885eb904f307fc02f5207-c085acc3e2c4162c-00"
}
■ 403 Forbidden (see error fields below)
■ 404 Not Found (see error fields below)
■ 409 Conflict (see error fields below)
■ 413 Content Too Large (see error fields below)
■ 500 Internal Server Error (see error fields below)

The table below shows the full list of fields returned in this response. The actual fields returned may differ according to the request.

Parameter

Type

Description

type

string

Error type

title

string

Email title

status

integer

StatusCodes.Status400BadRequest

detail

string

Additional error details.

instance

string

HttpContext.Request.Path

errorTicket

string

errId.ToString()

errorCode

string

Error code output in the request

traceId

string

HttpContext.TraceIdentifier

additionalProp1

string

Error related to Custom script parameter

additionalProp2

string

Error related to Custom script parameter

additionalProp3

string

Error related to Custom script parameter