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 |
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": "+14155550100",
"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": "+14155550100"
}'
Response
{
"id": "si_01h8abcdef0123456792",
"title": "Sales Desk Phone",
"username": "sales01",
"workspace_id": "yourcompany",
"domain": "yourcompany.firetell.app",
"outbound_caller_id": "+14155550100",
"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 '+16505550111' not found or does not belong to this workspace",
"error": "Bad Request"
}
SIP Registration Details
After creating a SIP account, configure your SIP device with:
- SIP Server / Registrar: The
domainvalue from the response (e.g.,yourcompany.firetell.app) - Username: The
usernameyou provided - Password: The
passwordyou 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": "+14155550100"
}'
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": "+14155550100",
"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.
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": "+14155550100",
"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"
}