SIP Accounts

SIP Accounts are credentials used by SIP-compatible softphones, desk phones, or other devices to register with the Firetell platform. Each SIP account can optionally be assigned an outbound_caller_id (a workspace phone number) for making external PSTN calls.

Endpoints

Method	Endpoint	Description
`GET`	`/sip-accounts`	List all SIP accounts
`POST`	`/sip-accounts`	Create a SIP account
`PATCH`	`/sip-accounts/:id`	Update a SIP account
`DELETE`	`/sip-accounts/:id`	Delete a SIP account

The SIP Account Object

Field	Type	Description
`id`	string	Unique SIP account identifier (prefixed with `si_`)
`title`	string	Display name of the SIP account
`username`	string	SIP registration username
`workspace_id`	string	Workspace identifier
`domain`	string	SIP domain for registration (e.g., `yourcompany.firetell.app`)
`outbound_caller_id`	string \| null	Assigned phone number used as Caller ID for external PSTN calls, or `null`
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 last update timestamp

info

The password field is never returned in API responses. SIP registration credentials are stored securely with HA1/HA1B digest hashing.

List SIP Accounts

GET /sip-accounts

Retrieve a paginated list of all SIP accounts in the workspace.

Authentication

Requires ApiKey with any scope.

Query Parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number (min: 1)
`limit`	number	`10`	Items per page (min: 1, max: 100)
`search`	string	—	Search by title or username (case-insensitive)
`sort_field`	string	`created_at`	Sort field. Allowed: `created_at`, `title`
`sort_order`	string	`desc`	Sort order: `asc` or `desc`

Request

curl -X GET "https://{workspace_id}.firetell.app/api/v1/sip-accounts?page=1&limit=10" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "si_01h8abcdef0123456789",
      "title": "Reception Desk Phone",
      "username": "reception01",
      "workspace_id": "yourcompany",
      "domain": "yourcompany.firetell.app",
      "outbound_caller_id": "+84901234567",
      "created_at": "2026-01-15T08:30:00.000Z",
      "updated_at": "2026-03-20T14:00:00.000Z"
    },
    {
      "id": "si_01h8abcdef0123456790",
      "title": "Softphone - John",
      "username": "john01",
      "workspace_id": "yourcompany",
      "domain": "yourcompany.firetell.app",
      "outbound_caller_id": null,
      "created_at": "2026-02-10T10:00:00.000Z",
      "updated_at": "2026-02-10T10:00:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}

Create SIP Account

POST /sip-accounts

Create a new SIP account. The system automatically registers the SIP subscriber credentials in the SIP registrar database.

Authentication

Requires ApiKey with full scope.

Request Body

Field	Type	Required	Description
`title`	string	✅	Display name. 1–36 characters.
`username`	string	✅	SIP username. 3–30 characters, lowercase letters and numbers only. Must be unique per workspace.
`password`	string	✅	SIP registration password. 6–50 characters.
`outbound_caller_id`	string \| null	—	Assigned phone number for making external calls. Set to `null` or empty string to disable outbound.

Request (Without Outbound Calls)

curl -X POST "https://{workspace_id}.firetell.app/api/v1/sip-accounts" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Conference Room Phone",
    "username": "confroom01",
    "password": "securePass123"
  }'

Response

{
  "id": "si_01h8abcdef0123456791",
  "title": "Conference Room Phone",
  "username": "confroom01",
  "workspace_id": "yourcompany",
  "domain": "yourcompany.firetell.app",
  "outbound_caller_id": null,
  "created_at": "2026-07-09T08:00:00.000Z",
  "updated_at": "2026-07-09T08:00:00.000Z"
}

Request (With Outbound Calls)

curl -X POST "https://{workspace_id}.firetell.app/api/v1/sip-accounts" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sales Desk Phone",
    "username": "sales01",
    "password": "securePass456",
    "outbound_caller_id": "+84901234567"
  }'

Response

{
  "id": "si_01h8abcdef0123456792",
  "title": "Sales Desk Phone",
  "username": "sales01",
  "workspace_id": "yourcompany",
  "domain": "yourcompany.firetell.app",
  "outbound_caller_id": "+84901234567",
  "created_at": "2026-07-09T08:00:00.000Z",
  "updated_at": "2026-07-09T08:00:00.000Z"
}

Error Responses

Duplicate username:

{
  "statusCode": 409,
  "message": "username confroom01 is exists",
  "error": "Conflict"
}

Phone number not found in workspace:

{
  "statusCode": 400,
  "message": "Outbound caller ID phone number '+84999999999' not found or does not belong to this workspace",
  "error": "Bad Request"
}

tip

SIP Registration Details

After creating a SIP account, configure your SIP device with:

SIP Server / Registrar: The domain value from the response (e.g., yourcompany.firetell.app)
Username: The username you provided
Password: The password you provided
Transport: UDP (default), TCP, or TLS

Update SIP Account

PATCH /sip-accounts/:id

Update an existing SIP account. Only include the fields you want to change. The username cannot be changed after creation.

Authentication

Requires ApiKey with full scope.

Path Parameters

Parameter	Type	Description
`id`	string	The SIP account ID (e.g., `si_01h8abcdef0123456789`)

Request Body

All fields are optional:

Field	Type	Description
`title`	string	New display name. 1–36 characters.
`password`	string	New SIP registration password. 6–50 characters.
`outbound_caller_id`	string \| null	New Outbound Caller ID phone number, or `null` / `""` to remove outbound calling capabilities.

Request

curl -X PATCH "https://{workspace_id}.firetell.app/api/v1/sip-accounts/si_01h8abcdef0123456789" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Main Reception Phone",
    "outbound_caller_id": "+84901234567"
  }'

Response

Returns the updated SIP account object:

{
  "id": "si_01h8abcdef0123456789",
  "title": "Main Reception Phone",
  "username": "reception01",
  "workspace_id": "yourcompany",
  "domain": "yourcompany.firetell.app",
  "outbound_caller_id": "+84901234567",
  "created_at": "2026-01-15T08:30:00.000Z",
  "updated_at": "2026-08-12T10:00:00.000Z"
}

Remove Outbound Caller ID

To disable outbound calling for a SIP account, set outbound_caller_id to null:

curl -X PATCH "https://{workspace_id}.firetell.app/api/v1/sip-accounts/si_01h8abcdef0123456789" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "outbound_caller_id": null
  }'

Error Response

{
  "statusCode": 404,
  "message": "Sip account not found or does not belong to this workspace",
  "error": "Not Found"
}

Delete SIP Account

DELETE /sip-accounts/:id

Permanently delete a SIP account. The SIP subscriber credentials are also removed from the registrar database, immediately preventing the device from registering.

Authentication

Requires ApiKey with full scope.

caution

This action is irreversible. Any SIP devices registered with this account will be immediately disconnected and unable to make or receive calls.

Path Parameters

Parameter	Type	Description
`id`	string	The SIP account ID

Request

curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/sip-accounts/si_01h8abcdef0123456789" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"

Response

Returns the deleted SIP account object:

{
  "id": "si_01h8abcdef0123456789",
  "title": "Reception Desk Phone",
  "username": "reception01",
  "workspace_id": "yourcompany",
  "domain": "yourcompany.firetell.app",
  "outbound_caller_id": "+84901234567",
  "created_at": "2026-01-15T08:30:00.000Z",
  "updated_at": "2026-08-12T10:00:00.000Z"
}

Error Response

{
  "statusCode": 404,
  "message": "Sip account not found or does not belong to this workspace",
  "error": "Not Found"
}

Endpoints​

The SIP Account Object​

List SIP Accounts​

Authentication​

Query Parameters​

Request​

Response​

Create SIP Account​

Authentication​

Request Body​

Request (Without Outbound Calls)​

Response​

Request (With Outbound Calls)​

Response​

Error Responses​

Update SIP Account​

Authentication​

Path Parameters​

Request Body​

Request​

Response​

Remove Outbound Caller ID​

Error Response​

Delete SIP Account​

Authentication​

Path Parameters​

Request​

Response​

Error Response​

Endpoints

The SIP Account Object

List SIP Accounts

Authentication

Query Parameters

Request

Response

Create SIP Account

Authentication

Request Body

Request (Without Outbound Calls)

Response

Request (With Outbound Calls)

Response

Error Responses

Update SIP Account

Authentication

Path Parameters

Request Body

Request

Response

Remove Outbound Caller ID

Error Response

Delete SIP Account

Authentication

Path Parameters

Request

Response

Error Response