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 are claimed from our pool in the dashboard onboarding, with no SIP setup. They are meant for your pilot phase — the fastest way to get an assistant answering a real call. They come with two limits:

• One managed number per account.
• Inbound calls only. Outbound calls from a managed number are rejected (see Calls); connect your own SIP trunk to place outbound calls.

Your own numbers (bring-your-own SIP) are numbers you provision with your own carrier and connect over a SIP trunk. This is the recommended path for production: 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.

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