Phone Numbers

Phone numbers are the entry point for your AI assistants. When a call comes in to a registered number, the assigned assistant handles the conversation.

How It Works

1. You configure a phone number with your SIP provider to forward calls to HMS Sovereign
2. You register the number in HMS Sovereign via the API
3. You assign an assistant to the number
4. Incoming calls are automatically handled by the assigned assistant

Managed numbers vs your own numbers

There are two ways to get a number onto the platform, meant for two different stages.

Managed numbers come from our own pool and are assigned by us, on request. Ask for one from the dashboard, under Numbers, and we get back to you. They need no SIP setup and are meant for testing and setting up your assistant, not for real callers. They are inbound only: outbound calls from a managed number are rejected (see Calls).

A managed number cannot be registered through the API or typed into the dashboard yourself, even if you know the number. POST /numbers with a number from our pool is refused with a 403.

Your own numbers (bring-your-own SIP) are numbers you provision with your own carrier and connect over a SIP trunk. This is the path for going live with real callers: the most stable connections, lowest cost, telephony you keep under your own control, and full inbound and outbound. Registering a number via the API (below) is how you bring your own number onto the platform. Need a hand connecting your provider? Ask for help from the dashboard under Numbers, or email us at info@voicedock.ai.

Phone Number Properties

Registering a Phone Number

curl -X POST https://api.hmsovereign.com/api/v1/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+31850835037",
    "name": "Main Support Line",
    "assistant_id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88"
  }'

Response:

{
  "number": {
    "id": "abc12345-1234-5678-9012-abcdef123456",
    "phone_number": "+31850835037",
    "name": "Main Support Line",
    "assistant_id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
    "transfer_trunk_id": null,
    "created_at": "2025-12-13T10:00:00.000Z",
    "updated_at": "2025-12-13T10:00:00.000Z"
  }
}

See Register a Phone Number for details.

Updating Assistant Assignment

Change which assistant handles calls for a number:

curl -X PATCH https://api.hmsovereign.com/api/v1/numbers/NUMBER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "new-assistant-uuid-here"
  }'

To unassign an assistant (calls will not be handled):

curl -X PATCH https://api.hmsovereign.com/api/v1/numbers/NUMBER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": null
  }'

See Update a Phone Number for details.

Attaching a Workflow

A number can run a workflow instead of a single assistant prompt: the workflow drives the conversation, while the assigned assistant keeps supplying the voice, models and call settings.

curl -X PATCH https://api.hmsovereign.com/api/v1/numbers/NUMBER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "workflow-uuid-here"
  }'

Pass "workflow_id": null to detach and return to normal assistant behaviour.

Configuring Call Transfers

To enable call transfers from this number, assign a SIP trunk:

curl -X PATCH https://api.hmsovereign.com/api/v1/numbers/NUMBER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transfer_trunk_id": "trunk-uuid-here"
  }'

See SIP Trunks for trunk configuration.

Number-Level Webhook

A phone number can carry its own webhook, configured in the dashboard under Phone numbers → (a number) → Webhooks: a URL, an optional signing secret, and the events to send (status updates and end-of-call reports).

A number's webhook is used when its assigned assistant has no webhook of its own, and takes precedence over the account-wide webhook. This is especially useful for numbers that resolve their assistant dynamically at call time — the Assistant Request is sent to the number's webhook so your server can return the right assistant. See Webhooks overview for the full precedence order.

Listing All Numbers

curl https://api.hmsovereign.com/api/v1/numbers \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "numbers": [
    {
      "id": "abc12345-...",
      "phone_number": "+31850835037",
      "name": "Main Support Line",
      "assistant_id": "17a0cb75-...",
      "transfer_trunk_id": null
    },
    {
      "id": "def67890-...",
      "phone_number": "+31201234567",
      "name": "Sales Line",
      "assistant_id": "28b1dc86-...",
      "transfer_trunk_id": "trunk-123-..."
    }
  ]
}

See List All Phone Numbers for details.

Deleting a Phone Number

curl -X DELETE https://api.hmsovereign.com/api/v1/numbers/NUMBER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

See Delete a Phone Number for details.

Related

• Assistants - Create assistants to assign to numbers
• SIP Trunks - Configure trunks for call transfers
• Calls - View call history for your numbers