--- sidebar_position: 6 title: SIP Accounts description: Create and manage SIP accounts for softphones and SIP-compatible devices to register with the Firetell platform via the REST API. --- # 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 ```bash curl -X GET "https://{workspace_id}.firetell.app/api/v1/sip-accounts?page=1&limit=10" \ -H "Authorization: ApiKey sk-YOUR_API_KEY" ``` ### Response ```json { "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) ```bash 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 ```json { "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) ```bash 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 ```json { "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:** ```json { "statusCode": 409, "message": "username confroom01 is exists", "error": "Conflict" } ``` **Phone number not found in workspace:** ```json { "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 ```bash 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: ```json { "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`: ```bash 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 ```json { "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 ```bash 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: ```json { "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 ```json { "statusCode": 404, "message": "Sip account not found or does not belong to this workspace", "error": "Not Found" } ```