Route numbers to voice or SMS endpoints

Create routing endpoints and assign them to your cloudnumbering numbers with API v1.1.

How endpoints and assignments work

An endpoint is a reusable destination for voice or SMS traffic. A number assignment connects an in-service number to a voice endpoint, an SMS endpoint, or both.

Voice endpoints use a sip: URI.
SMS endpoints use an HTTPS callback or mailto: URI.
A default endpoint applies to later default routing decisions. Making an endpoint the default does not reassign numbers that already have an explicit endpoint.

The API v1.1 base URL is https://api.cloudnumbering.com/v1.1. These examples assume your access token is stored in CLOUDNUMBERING_ACCESS_TOKEN.

List existing endpoints

List the active endpoints for your organisation before creating another one:

curl --silent --show-error \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  'https://api.cloudnumbering.com/v1.1/endpoints'

Each entry includes its endpoint SID, type, URI, default and secondary flags, and the number of assigned numbers. See List your endpoints.

Create an endpoint

This example creates an HTTPS destination for inbound SMS:

curl --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "Inbound SMS webhook",
    "endpointType": "sms",
    "uri": "https://example.com/webhooks/cloudnumbering/sms",
    "isDefault": false
  }' \
  'https://api.cloudnumbering.com/v1.1/endpoints'

Save the endpoint sid returned in result. See Create an endpoint for voice fields and the complete request schema.

Assign the endpoint to a number

Use List your assigned numbers or the assigned-number guide to find the number first. Use its assigned-number SID beginning with AN, not the underlying number-pool SID beginning with NB.

Assign the SMS endpoint and set a customer reference:

curl --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "smsEndpointSid": "EP12345678901234567890123456789012",
    "reference": "Support line"
  }' \
  'https://api.cloudnumbering.com/v1.1/numbers/AN12345678901234567890123456789012/endpoints'

At least one of voiceEndpointSid or smsEndpointSid is required. You can provide both in one request. See Assign endpoints to a number.

Warning: reference is required, and it replaces the number's existing reference on every assignment. Read the number first and resend its current reference unless you intend to change it.

The API changes the endpoint assignment before updating reference. Some failures on the assignment, endpoint-list and endpoint-delete paths return HTTP 200 with success: false, so check the success field in the body rather than relying on the status code. If a request fails or its outcome is unclear, do not assume that routing stayed unchanged. Retrieve the number and check its voice and SMS endpoint SIDs before retrying. The reference update may still need separate operational verification.

Update an endpoint

PUT /v1.1/endpoints/{sid} replaces the endpoint's description and URI. It can also change isDefault, but it does not change the endpoint type or the secondary flag — both are fixed when the endpoint is created. To change either, create a new endpoint and reassign the numbers.

curl --silent --show-error \
  --request PUT \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "Inbound SMS webhook",
    "uri": "https://example.com/webhooks/cloudnumbering/sms-v2",
    "isDefault": false
  }' \
  'https://api.cloudnumbering.com/v1.1/endpoints/EP12345678901234567890123456789012'

Changing the URI affects traffic routed to that endpoint. Test the new destination before changing a live endpoint. See Update an endpoint.

Deactivate an endpoint

Warning: Deactivating an endpoint can stop calls or messages from reaching your application.

Before deactivating an endpoint, list endpoints and check its assignedNumbersCount. Reassign affected numbers first.

Deactivate an unused endpoint:

curl --silent --show-error \
  --request DELETE \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  'https://api.cloudnumbering.com/v1.1/endpoints/EP12345678901234567890123456789012'

Only add ?unlinkAssignedNumbers=true if you intend to remove its current number assignments as part of the same operation. See Delete an endpoint.