---
title: "Create a SIP account/extension (e.g. for a Fritz!Box or softphone to register against)"
method: POST
path: "/api/v1/sip-accounts"
tags: ["sip"]
---

# Create a SIP account/extension (e.g. for a Fritz!Box or softphone to register against)

`POST /api/v1/sip-accounts`

## Request

- Base URL: `https://www.callagent.pro`
- URL: `https://www.callagent.pro/api/v1/sip-accounts`
- Auth: HTTP bearer

## Request body

- SipAccountCreate: REQUEST body for an extension; the response is a different shape entirely (see SipAccount). NOTHING IS REQUIRED — POST an empty body and the next free extension is allocated with a generated username and password, which is the normal way to use this. `username` cannot be chosen: it comes from a fixed pool. On CREATE only `display_name` is read; the other fields below apply to PUT/PATCH.
  - `display_name` string: Accepted on create and update
  - `status` 'active' | 'suspended': Update only
  - `direction` 'inbound' | 'outbound': Update only. NOTE there is no "both" here even though the SipAccount response can report one — the validator accepts these two values. Inbound accounts get number auto-discovery and the default-agent fallback.
  - `regenerate_password` boolean: Update only. Server generates a new password and returns it once in the response.
  - `password` string: Update only. Sets a password of your choosing; ignored when regenerate_password is true.

## Response `200`

Created

- object
  - `ok` boolean
  - `connections` Connections: Trunk and SIP-account mutations answer with the whole refreshed connections view rather than the single record you changed, because that is what the dashboard re-renders. Read your result out of these arrays.
    - `trunks` Trunk[], required
      - `id` integer, required
      - `name` string, required: Display name — what you sent as trunk_name
      - `provider` string, required
      - `provider_label` string, required: Human-readable provider name
      - `host` string, required
      - `port` integer, required
      - `username` string, required
      - `true` boolean: Enabled
      - `status` string, required: Live registration state, e.g. active
      - `is_default` boolean, required
      - `inbound_assistant_id` integer, nullable, required: Agent that answers calls arriving on this trunk
      - `calls` integer, required
      - `dur` string, required: Total talk time, HH:MM or MM:SS
    - `sip_accounts` SipAccount[], required
      - `id` integer, required
      - `user` string, required: The extension/username a device registers with
      - `name` string, nullable, required
      - `role` string, required
      - `agent` string, required: Name of the agent this extension reaches
      - `dir` string, required: Short direction label
      - `direction` 'inbound' | 'outbound' | 'both', required
      - `true` boolean
      - `status` string, required: Live registration state
      - `ip` string, required: Address it registered from
      - `ping` integer, required: Round-trip ms to the device
      - `device` string, required
      - `device_ua` string, required: Raw SIP User-Agent
      - `last` string, required: Last seen, humanized
      - `created` string, required
      - `calls` integer, required
      - `dur` string, required
    - `server` string, required: SIP host these register against

## Other responses

- `401`: Missing or invalid Bearer key
- `429`: Too many requests — see the endpoint's rate limit tier (agent-api 120/min, agent-api-heavy 6/min, agent-api-secrets 10/min)

---

[API](https://skmtc.dev/callagent/apis/callagent-pro-agent-api.md) · [All operations](https://skmtc.dev/callagent/apis/callagent-pro-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/callagent/apis/callagent-pro-agent-api/revisions/38072cf8a24b?raw)