Transition Number to Ready for Removal

The Transition Number to Ready for Removal request transitions acquired telephone numbers from "MarkedForRemoval" status to "ReadyForRemoval" status, which represents the final step before numbers are permanently removed from the Microsoft Teams environment. This status change confirms that numbers are ready for deletion and should no longer be available for assignment.

■

Request handling rules:

●

Only telephone numbers currently in "MarkedForRemoval" status can be updated to "ReadyForRemoval"

●

Numbers with any other status (Active, ReleaseRequested, ReadyForRemoval) are rejected

●

Successfully updated numbers are marked as 'Confirmed for Removal' and excluded from future assignments

●

Each number must exist on Live Platform and be associated with an Operator Connect customer

●

This operation is typically performed after confirming numbers are no longer needed in Microsoft Teams

■

Validation Rules:

●

Request body cannot be null

●

TelephoneNumbers array must contain between 1 and 500 numbers

●

Each telephone number must be in valid E.164 format (see below)

●

Each number must currently be in "MarkedForRemoval" status

■

Other Considerations:

●

This endpoint is subject to a global rate limit of 300 requests per minute

●

Processing is performed sequentially for each number in the request

●

If the client cancels the request during processing, a partial result is returned

●

Large requests may take longer to process; consider breaking them into smaller batches

●

Numbers that fail validation or status checks are included in the error details for troubleshooting

●

"ReadyForRemoval" status is typically the final status before numbers are permanently deleted from the system

●

This operation should only be performed after confirming numbers are no longer required for Microsoft Teams operations

URI

HTTP Method

POST

Request Body

Parameter	Type	Description
telephoneNumbers	array of strings	Lists telephone numbers to transition to "ReadyForRemoval" status. Note: ■ The array must not exceed 500 telephone numbers in a single request. ■ Each telephone number must be a valid format according to E.164 standards. ■ Each telephone number must exist in the system. ■ Each telephone number must be in "MarkedForRemoval" status to be transitioned to “ReadyForRemoval“.
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.

Example Request Body

Example Response

HTTP Responses

■

200 OK

Parameter	Type	Description
processedCount	integer	The total number of telephone numbers that were included in the request and processed by the system, regardless of the outcome (success or failure).
successCount	integer	The total number of telephone numbers that were successfully changed from "MarkedForRemoval" to “ReadyForRemoval“.

■

400 Bad Request

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	The status of the connection with M365 platform: ■ 0-Active ■ 1-Not Active ■ 2-OC Essential
detail	string	Additional error details.
instance	string	Error instance.
errorTicket	string	The error ticket string opened for this request.
errorCode	string	Error code output in the request
traceId	string	The trace id of the request
additionalProp1	string	Custom Script variable argument. For example IP-Network.
additionalProp2	string	Custom Script argument. For example, IP-SubnetBits.
additionalProp3	string	Custom Script argument. For example, Trusted-IP-Network.