Phone Numbers

Phone numbers are the entry point for your AI assistants. Incoming calls to registered numbers are handled by the assigned assistant.

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

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

Phone Number Properties

Property	Type	Description
`id`	UUID	Unique identifier
`phone_number`	string	Phone number in E.164 format (e.g., `+31850835037`)
`name`	string	Display name for the number
`assistant_id`	UUID	Assigned assistant (nullable)
`transfer_trunk_id`	UUID	SIP trunk for call transfers (nullable)

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.

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.

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.

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

On this page