Configure SIP routing with API v1.1

Route inbound calls to a SIP destination and manage the source-IP allowlist used for outbound SIP traffic.

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.

Inbound and outbound calls use different configuration

For inbound calls to your cloudnumbering number, create a voice endpoint and assign it to the number.
For outbound calls from your SIP platform, add its public source IP to the voice allowlist, then configure the SIP trunk itself.

API v1.1 does not provide a REST endpoint that places an outbound voice call. Outbound calls are sent as SIP traffic. See Making outbound voice calls for trunk and caller-ID configuration.

Create an inbound voice endpoint

Voice endpoint URIs start with sip: and can use one of these called-number placeholders in the SIP user part:

Placeholder	Value substituted into the URI
`%e164`	The called number in E.164 form.
`%raw`	The raw called-number form.
`%national`	The called number in national form.

Create a voice endpoint:

curl --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "Primary PBX",
    "endpointType": "voice",
    "uri": "sip:%[email protected]:5060",
    "isDefault": false,
    "isSecondary": false
  }' \
  'https://api.cloudnumbering.com/v1.1/endpoints'

Save the endpoint sid returned in result. Setting isDefault to true does not change numbers that already have explicit endpoint assignments. See Create an endpoint.

Assign the voice 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:

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

This changes where inbound voice traffic for the number is routed. Test the number and confirm that your SIP platform receives the call. See Assign endpoints to a number.

The API changes the endpoint assignment before updating reference. If the response is an error or its outcome is unclear, retrieve the number and confirm its voice endpoint SID before retrying. Do not assume that routing stayed unchanged.

List allowed outbound source IPs

The voice allowlist identifies the organisation permitted to send outbound SIP traffic from a source address.

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

See List allowed source IPs.

Add an allowed source IP

The API accepts one IPv4 or IPv6 address without a CIDR prefix or port. Add the public source address from which your SIP traffic reaches cloudnumbering:

curl --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"ip":"203.0.113.10"}' \
  'https://api.cloudnumbering.com/v1.1/endpoints/voice/ips'

Adding an address that is already present succeeds without creating a duplicate. See Add an allowed source IP.

Warning: A source address authorises one organisation at a time. Do not register a shared egress address that another cloudnumbering customer may also use — for example, one belonging to a shared SBC, proxy, or hosting provider NAT — because a later registration of the same address replaces the earlier one.

The API's address validation is wider than the portal form. API acceptance confirms the value's syntax only: a private or loopback address is accepted but can never match a real source address arriving at cloudnumbering's SIP service, so adding one has no effect. Register the public address your SIP traffic actually leaves from, and confirm that your voice network and cloudnumbering's SIP service can exchange traffic over the address family you use.

Remove an allowed source IP

Warning: After you remove an address, SIP traffic from that source can no longer place calls for your organisation.

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

Removing an address that is already absent succeeds without changing the list. See Remove an allowed source IP.

Operational setup and troubleshooting

ReadMe documents the API integration. Use the help centre for SIP and portal operations: