openapi: 3.1.0

info:
  title: Telebroad Public API
  version: "1.0.0"
  summary: Manage SMS, faxes, users, call recordings and webhook subscriptions on a Telebroad account.
  description: |
    The Telebroad public REST API. Every endpoint lives under
    `/api/public/v1` and takes a machine credential — an **API key** or an
    **OAuth 2.1 access token** — as `Authorization: Bearer …`.

    A browser session cannot reach this surface. That is deliberate: there is no
    ambient authority to borrow, so a page a user happens to have open cannot be
    made to call the API on their behalf.

    ### Two things gate every request

    1. **The scope** on the credential (listed on each operation).
    2. **The role permission** of the person behind the credential, in the admin
       center. A scope can only narrow what that person could already do — never
       widen it.

    A `403` with `"type": "insufficient_scope"` is the first gate. A `403` with
    `"type": "permission_denied"` is the second, and the fix is in the portal, not
    in your code.

    ### Envelope

    Success is `{"data": …}`. Errors are
    `{"error": {"type": …, "message": …}}`. Branch on `error.type` — it is stable.
    Never parse `error.message`.
  contact:
    name: Telebroad
    url: https://telebroad.com
  x-logo:
    altText: Telebroad

servers:
  - url: https://api.account.telebroad.com/api/public/v1
    description: Production

tags:
  - name: SMS
    description: |
      Send a text message from one of the account's numbers, and discover which
      numbers those are. Sending is **billed** — see the SMS billing concept page.
  - name: Conversations
    description: |
      A text thread's state. A conversation has no id: it is the pair
      (one of your numbers, the other party's number).
  - name: Users
    description: The account's users — who works here, and how to reach them.
  - name: Calls
    description: |
      Call history, one call's journey, its recordings and its transcripts. A
      call with transfers is ONE call with several legs — and several
      recordings and transcripts. Placing a call (click to call) is
      **charged** — see the Click to call concept page.
  - name: Faxes
    description: |
      Sent and received faxes, their delivery status and documents, and sending
      a fax from one of the account's fax numbers. Sending is **charged** — see
      the Faxes concept page.
  - name: Webhooks
    description: |
      Subscriptions to account events. This is the configuration API; the payloads
      that get delivered to your endpoint are documented in the Webhooks guide.

security:
  - apiKey: []

paths:
  # ---------------------------------------------------------------- SMS -----
  /sms/lines:
    get:
      operationId: listSMSLines
      summary: List the numbers you can send from
      tags: [SMS]
      description: |
        Every number in this list is one `POST /sms/messages` will accept as
        `from`; a number missing from it is one it would reject. Both read the
        same setting, so this is the authoritative answer to "what can I put in
        `from`".

        | | |
        | --- | --- |
        | **Scope** | `sms:read` |
        | **Role permission** | Phone numbers |
        | **Cost** | Free. Sends nothing. |
      security:
        - apiKey: []
        - oauth2: [sms:read]
      responses:
        "200":
          description: The numbers the credential may send from.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/SMSLine" }
              examples:
                default:
                  summary: Two lines, one shared
                  value:
                    data:
                      - number: "12125550188"
                        name: Acme Support
                        userIds: [481920, 481925]
                        bulkEnabled: false
                      - number: "12125550199"
                        name: Acme Sales
                        userIds: []
                        bulkEnabled: true
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /sms/messages:
    post:
      operationId: sendSMS
      x-tb-suggest-body: { from: sms-lines }
      summary: Send a text message
      tags: [SMS]
      description: |
        **This spends money.** Every message is priced from the account's rate
        card and lands on its invoice. The charge is in the response — you never
        have to wait for an invoice to find out what a call cost.

        | | |
        | --- | --- |
        | **Scope** | `sms:send` |
        | **Role permission** | Phone numbers — `from` must be one of theirs |
        | **Cost** | Per segment (`sms`) or once (`mms`) |

        **Two things make a message an MMS**, and either alone is enough: more
        than one recipient, or any attachment. An MMS is charged **once**,
        whatever the body length or participant count.

        **One recipient or many changes the product and the price.** One number
        in `to` sends a direct SMS, billed per segment. Two or more creates a
        **group thread** — one conversation all participants see and can reply
        into — which is an MMS, billed **once** regardless of body length or
        participant count.

        To send separate, private messages — one to each person — make **one
        request per person**. Putting several people in a single `to` array instead
        creates one shared group conversation they can all see and reply into, not
        separate texts.

        Unknown fields are rejected, so a typo like `"mesage"` gets a `400`
        instead of silently sending nothing.
      security:
        - apiKey: []
        - oauth2: [sms:send]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SendSMSInput" }
            examples:
              direct:
                summary: One recipient — SMS, billed per segment
                value:
                  from: "12125550188"
                  to: ["13475550123"]
                  message: Your appointment is confirmed for Tuesday at 10am.
              group:
                summary: Three recipients — group thread, billed once as MMS
                value:
                  from: "12125550188"
                  to: ["13475550123", "13475550124", "13475550125"]
                  message: Crew, the Tuesday job moved to 9am.
              mms:
                summary: One recipient with a picture — MMS, billed once
                value:
                  from: "12125550188"
                  to: ["13475550123"]
                  message: Here's the signed copy.
                  attachments:
                    - filename: receipt.png
                      contentType: image/png
                      content: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==
      responses:
        "201":
          description: Sent, and charged.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/SendResult" }
              examples:
                default:
                  value:
                    data:
                      from: "12125550188"
                      billing:
                        billed: true
                        currency: USD
                        type: sms
                        units: 1
                        totalPrice: 0.0025
                        recipientCount: 1
                        skippedCount: 0
                      messages:
                        - id: 88214417
                          to: ["13475550123"]
                          type: sms
                          status: sent
                          units: 1
                          unitPrice: 0.0025
                          price: 0.0025
                      skipped: []
        "200":
          description: |
            Nothing was sent because every recipient was skipped (opted out,
            duplicate, or unparseable). **Nothing was charged.**
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/SendResult" }
              examples:
                allSkipped:
                  value:
                    data:
                      from: "12125550188"
                      billing:
                        billed: true
                        currency: USD
                        type: sms
                        units: 0
                        totalPrice: 0
                        recipientCount: 0
                        skippedCount: 1
                      messages: []
                      skipped:
                        - to: "13475550123"
                          reason: opted_out
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/Unpriced" }
        "500": { $ref: "#/components/responses/InternalErrorSend" }

  # ------------------------------------------------------ Conversations -----
  /sms/conversations/{line}/{number}/resolve:
    post:
      operationId: resolveConversation
      summary: Mark a conversation handled
      tags: [Conversations]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:write` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free. Cannot reach the other party. |

        Two behaviours worth knowing:

        - **It creates the thread's state if there is none.** Most conversations
          have never been actioned, so an endpoint that `404`'d on those would
          fail on exactly the common case.
        - **It is idempotent.** Re-resolving returns `200` with the stored state
          and does not re-stamp who closed it or when, so a retry after a
          timeout cannot rewrite history.

        The body is entirely optional — a bare `POST` resolves the thread.
      security:
        - apiKey: []
        - oauth2: [sms:write]
      parameters:
        - $ref: "#/components/parameters/Line"
        - $ref: "#/components/parameters/OtherNumber"
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ResolveInput" }
            examples:
              bare:
                summary: Just resolve it
                value: {}
      responses:
        "200":
          description: The thread's state after the call.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Conversation" }
              examples:
                default:
                  value:
                    data:
                      line: "12125550188"
                      number: "13475550123"
                      resolved: true
                      resolvedBy: 481920
                      resolvedAt: "2026-08-11T14:02:11Z"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  # ------------------------------------------------------------ Reading -----
  /sms/conversations:
    get:
      operationId: listConversations
      summary: List conversations (the inbox)
      tags: [Conversations]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `messages:read` |
        | **Role permission** | Phone numbers — only lines the credential is authorized for |
        | **Cost** | Free |

        One entry per thread, newest first, with the thread's queue state
        attached — so a queue view needs one call, not one per conversation.

        **Filters combine as AND.** `unresolved=true&assignedToMe=true` is "my
        open threads", which is the message center's default view.

        Omit `lines` and every texting number on the account is listed. A fresh
        integration therefore does not need to call `GET /sms/lines` first, and
        keeps working when the customer buys a number.
      security:
        - apiKey: []
        - oauth2: [messages:read]
      parameters:
        - name: lines
          in: query
          required: false
          description: Comma-separated account numbers to list. Leave it out to include every number.
          x-tb-suggest: sms-lines
          schema: { type: string }
          example: "12125550188,12125550199"
        - name: unread
          in: query
          required: false
          description: Only threads you have not read. Read state is per user, so a thread a colleague has read is still unread for you.
          schema: { type: boolean }
        - name: unresolved
          in: query
          required: false
          description: Only threads not marked handled.
          schema: { type: boolean }
        - name: assignedToMe
          in: query
          required: false
          description: Only threads assigned to the calling user.
          schema: { type: boolean }
        - name: unassigned
          in: query
          required: false
          description: Only threads nobody owns.
          schema: { type: boolean }
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: The conversations, newest first.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/ConversationSummary" }
              examples:
                default:
                  value:
                    data:
                      - line: "12125550188"
                        number: "13475550123"
                        lastMessage: Can we move it to Thursday?
                        lastMessageId: 90218841
                        lastMessageAt: "2026-08-19T13:41:02Z"
                        direction: in
                        unread: true
                        unreadCount: 2
                        resolved: false
                        assignedTo: 481920
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /sms/conversations/{line}/{number}:
    get:
      operationId: getConversation
      summary: Read a conversation's messages
      tags: [Conversations]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `messages:read` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free |

        Reading does NOT mark anything read. `markRead` defaults to **false**,
        which differs from the portal, where opening a thread clears it. An
        integration polling for new messages would otherwise silently empty the
        unread badges your staff work from, with nothing to explain it. Pass
        `markRead=true` when a **person** has actually seen the messages.

        Media URLs in the response are publicly readable — the URL is the only
        thing protecting the file. Treat them as secrets and do not log them.
      security:
        - apiKey: []
        - oauth2: [messages:read]
      parameters:
        - $ref: "#/components/parameters/Line"
        - $ref: "#/components/parameters/OtherNumber"
        - name: markRead
          in: query
          required: false
          description: Also mark the returned messages read for you. Default false.
          schema: { type: boolean }
        - name: groupParticipants
          in: query
          required: false
          description: Comma-separated participants, to address a group thread rather than a 1:1.
          schema: { type: string }
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: The conversation's messages.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Thread" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }
    delete:
      operationId: deleteConversation
      summary: Delete a conversation
      tags: [Conversations]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `messages:write` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free |

        **PERMANENT.** Every message in the thread is destroyed and there is no
        recovery through this API.

        Additionally gated by the account's **restrict deleting SMS** setting.
        Holding `messages:write` does **not** override it — that setting exists
        precisely so an account owner can stop their own staff and integrations
        from destroying message history. A restricted account gets `403`.
      security:
        - apiKey: []
        - oauth2: [messages:write]
      parameters:
        - $ref: "#/components/parameters/Line"
        - $ref: "#/components/parameters/OtherNumber"
      responses:
        "204": { description: Deleted. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /sms/conversations/{line}/{number}/messages/{id}:
    get:
      operationId: getConversationPage
      summary: Read the page containing a message
      tags: [Conversations]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `messages:read` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free |

        "Open this thread at this message." You hold a message id from a webhook,
        a search result or a notification and do not know its position — this
        returns the surrounding page directly instead of making you walk the
        thread with `limit`/`offset` until you find it.
      security:
        - apiKey: []
        - oauth2: [messages:read]
      parameters:
        - $ref: "#/components/parameters/Line"
        - $ref: "#/components/parameters/OtherNumber"
        - $ref: "#/components/parameters/MessageID"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: The page of the conversation containing that message.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Thread" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }
    delete:
      operationId: deleteMessage
      summary: Delete one message
      tags: [Conversations]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `messages:write` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free |

        **PERMANENT** — no recovery through this API. Also gated by the account's
        **restrict deleting SMS** setting, which `messages:write` does not
        override.
      security:
        - apiKey: []
        - oauth2: [messages:write]
      parameters:
        - $ref: "#/components/parameters/Line"
        - $ref: "#/components/parameters/OtherNumber"
        - $ref: "#/components/parameters/MessageID"
      responses:
        "204": { description: Deleted. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /sms/conversations/{line}/{number}/read:
    post:
      operationId: markMessagesRead
      summary: Mark messages read or unread
      tags: [Conversations]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `messages:write` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free |

        **Read state is per user.** This edits only *your* membership of each
        message's reader list, so it cannot clear a colleague's unread badges.

        To clear a whole line at once, use `POST /sms/lines/{line}/read` — there
        is deliberately no "mark the entire thread" here, because two spellings
        of the same bulk action invite a client to loop the wrong one.
      security:
        - apiKey: []
        - oauth2: [messages:write]
      parameters:
        - $ref: "#/components/parameters/Line"
        - $ref: "#/components/parameters/OtherNumber"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MarkReadInput" }
            examples:
              read:
                summary: Mark two messages read
                value:
                  messageIds: [90218841, 90218842]
              unread:
                summary: Put one back to unread
                value:
                  messageIds: [90218841]
                  read: false
      responses:
        "204": { description: Applied. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /sms/conversations/{line}/{number}/reopen:
    post:
      operationId: reopenConversation
      summary: Reopen a resolved conversation
      tags: [Conversations]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:write` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free. Cannot reach the other party. |

        Resolve's counterpart: flip a closed thread back to **unresolved** so it
        returns to the active queue — usually because the customer replied after
        it was marked handled and someone has to pick it up again.

        Two behaviours worth knowing:

        - **It is idempotent, and it never `404`s.** Re-opening an already-open
          thread — including one nobody ever resolved, which is open by default —
          returns `200` with the stored state. A retry after a timeout changes
          nothing.
        - **It clears the resolution.** `resolved` goes to `false`, and
          `resolvedBy` / `resolvedAt` drop off the returned thread.
      security:
        - apiKey: []
        - oauth2: [sms:write]
      parameters:
        - $ref: "#/components/parameters/Line"
        - $ref: "#/components/parameters/OtherNumber"
      responses:
        "200":
          description: The thread's state after the call.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Conversation" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /sms/conversations/{line}/{number}/assign:
    post:
      operationId: assignConversation
      summary: Assign a conversation to a user
      tags: [Conversations]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:write` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free. Cannot reach the other party. |

        **A null or absent `userId` unassigns**, returning the thread to the
        unassigned queue — which is why there is no separate unassign endpoint
        for one nullable field.

        Assigning does **not** resolve, and unassigning does not reopen. They are
        independent axes: a resolved thread can stay assigned to whoever closed
        it, and an open thread can sit unassigned.

        A `userId` for someone not on your account is a `400`, so assignment can
        only ever land on a real teammate.
      security:
        - apiKey: []
        - oauth2: [sms:write]
      parameters:
        - $ref: "#/components/parameters/Line"
        - $ref: "#/components/parameters/OtherNumber"
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AssignInput" }
            examples:
              assign:
                summary: Hand it to a user
                value:
                  userId: 481920
              unassign:
                summary: Return it to the queue
                value:
                  userId: null
      responses:
        "200":
          description: The thread's state after the call.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Conversation" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /sms/unread:
    get:
      operationId: getUnreadCounts
      summary: Unread counts
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `messages:read` |
        | **Role permission** | Phone numbers — only lines the credential is authorized for |
        | **Cost** | Free |

        This endpoint gives your unread message count **two ways**: a **per-line**
        count, and a single **grand total**. Both are returned so a UI showing one
        overall badge can use the grand total directly — no need to add up the
        per-line counts — and that badge can never disagree with the per-line
        numbers, since the server computes the total from the same data.

        An API key has no user behind it and therefore no personal unread state;
        it gets the line-level counts, which is the only honest answer available
        to a credential that is not a person.
      security:
        - apiKey: []
        - oauth2: [messages:read]
      parameters:
        - name: lines
          in: query
          required: false
          description: Comma-separated account numbers. Leave it out to include every number.
          x-tb-suggest: sms-lines
          schema: { type: string }
        - name: since
          in: query
          required: false
          description: Only count messages after this instant, RFC 3339.
          schema: { type: string, format: date-time }
      responses:
        "200":
          description: Unread counts.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/UnreadSummary" }
              examples:
                default:
                  value:
                    data:
                      total: 7
                      lines:
                        - line: "12125550188"
                          count: 5
                        - line: "12125550199"
                          count: 2
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /sms/lines/{line}/read:
    post:
      operationId: markLineRead
      summary: Mark a whole line read
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `messages:write` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free |

        Clears a line's unread state **for you**, without walking every thread.

        **This endpoint needs an OAuth token** (a credential that represents a
        person). Whether a message is read is tracked per user, so an API key —
        which stands for the whole account, not any one person — has no personal
        unread state to clear here, and gets a `400`. Use OAuth for this one.
      security:
        - apiKey: []
        - oauth2: [messages:write]
      parameters:
        - $ref: "#/components/parameters/SMSLinePath"
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MarkLineReadInput" }
            examples:
              all:
                summary: Everything
                value: {}
              since:
                summary: Only recent messages
                value:
                  since: "2026-08-01T00:00:00Z"
      responses:
        "204": { description: Applied. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  # ----------------------------------------------------- Blocked senders -----
  /sms/lines/{line}/blocked:
    get:
      operationId: listBlockedSenders
      summary: List blocked senders
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:read` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free |

        There are **two separate lists**, and this endpoint is only one of them:

        - **Your block list — this endpoint.** Numbers *you* have blocked from
          texting your line. You control it, and can add or remove entries.
        - **The opt-out list — not this endpoint.** People who texted **STOP** to
          stop receiving *your* messages. Carriers require it, and this API
          deliberately **cannot** edit it — you must not be able to undo someone's
          opt-out. The only way to tell that someone has opted out is when a send
          to them comes back as `skipped` with the reason `opted_out`.
      security:
        - apiKey: []
        - oauth2: [sms:read]
      parameters:
        - $ref: "#/components/parameters/SMSLinePath"
      responses:
        "200":
          description: The blocked senders on this line.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/BlockedSender" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }
    post:
      operationId: blockSender
      summary: Block a sender
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:write` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free |

        Stops a number texting this line. Idempotent — blocking an
        already-blocked number succeeds, so a retry after a timeout is safe.
      security:
        - apiKey: []
        - oauth2: [sms:write]
      parameters:
        - $ref: "#/components/parameters/SMSLinePath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/BlockInput" }
            examples:
              default:
                value:
                  number: "13475550123"
                  reason: Repeated spam
      responses:
        "201":
          description: Blocked.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/BlockedSender" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /sms/lines/{line}/blocked/{number}:
    get:
      operationId: getBlockedSender
      summary: Check whether a number is blocked
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:read` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free |

        Answers "is this number blocked?" If it **is**, you get a `200` with the
        block details; if **not**, a `404` (a clear "no"). It returns `404` rather
        than a `200` with an empty body, which your code could easily confuse with
        an error.
      security:
        - apiKey: []
        - oauth2: [sms:read]
      parameters:
        - $ref: "#/components/parameters/SMSLinePath"
        - $ref: "#/components/parameters/OtherNumber"
      responses:
        "200":
          description: The blocked sender.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/BlockedSender" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }
    delete:
      operationId: unblockSender
      summary: Unblock a sender
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:write` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free |

        Lets the number text this line again.
      security:
        - apiKey: []
        - oauth2: [sms:write]
      parameters:
        - $ref: "#/components/parameters/SMSLinePath"
        - $ref: "#/components/parameters/OtherNumber"
      responses:
        "204": { description: Unblocked. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  # ---------------------------------------------------------- Schedules ------
  /sms/lines/{line}/scheduled:
    get:
      operationId: listScheduledMessages
      summary: List scheduled messages
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:read` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free |

        What is queued to go out from this line, with the price each will cost.
      security:
        - apiKey: []
        - oauth2: [sms:read]
      parameters:
        - $ref: "#/components/parameters/SMSLinePath"
      responses:
        "200":
          description: The queued messages.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/ScheduledMessage" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }
    post:
      operationId: scheduleMessage
      summary: Schedule a message
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:send` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | **THIS SPENDS MONEY** — later. |

        **Why this needs `sms:send`, not `sms:write`:** scheduling still charges
        the account — just later. `sms:write` is the permission for things that
        don't cost money (drafts, templates, block lists); `sms:send` is the one
        that authorizes spending. If scheduling only needed `sms:write`, a
        credential that isn't allowed to send a message now could still queue one
        to send — and bill the account — later. That is a back door around the
        spending permission, so scheduling requires the same `sms:send` consent a
        live send does.

        **The price is fixed at the moment you schedule.** A later rate-card
        change does not re-price a message you already committed to.

        The STOP list is checked at **dispatch**, not now: a recipient can opt out
        between scheduling and sending, and clearing them now would let the
        message reach someone who has since said stop.
      security:
        - apiKey: []
        - oauth2: [sms:send]
      parameters:
        - $ref: "#/components/parameters/SMSLinePath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ScheduleInput" }
            examples:
              default:
                value:
                  to: ["13475550123"]
                  message: "Reminder: your appointment is tomorrow at 2pm."
                  sendAt: "2026-08-20T14:30:00Z"
      responses:
        "201":
          description: Queued.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/ScheduledMessage" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422":
          description: A destination is not on the account's rate card, so it cannot be priced. Nothing was queued.
        "500": { $ref: "#/components/responses/InternalErrorSend" }

  /sms/lines/{line}/scheduled/{id}:
    delete:
      operationId: cancelScheduledMessage
      summary: Cancel a scheduled message
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:write` |
        | **Role permission** | Phone numbers — `line` must be one of theirs |
        | **Cost** | Free — and it prevents the future charge. |

        Cancelling requires only `sms:write`: stopping a charge is not a
        money-spending action, and requiring `sms:send` to undo one would be the
        wrong way round.
      security:
        - apiKey: []
        - oauth2: [sms:write]
      parameters:
        - $ref: "#/components/parameters/SMSLinePath"
        - $ref: "#/components/parameters/ScheduleID"
      responses:
        "204": { description: Cancelled. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  # ------------------------------------------------ Templates and drafts -----
  /sms/templates:
    get:
      operationId: listTemplates
      summary: List saved replies
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:read` |
        | **Cost** | Free |

        Saved replies are canned messages you reuse — opening hours, a booking
        link, "we'll call you back". Each belongs to the user who created it, not
        the account, so one agent can't see another's. An API key isn't a person,
        so it owns none and gets an empty list — expected, not an error.
      security:
        - apiKey: []
        - oauth2: [sms:read]
      responses:
        "200":
          description: The caller's saved replies.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Template" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }
    post:
      operationId: createTemplate
      summary: Save a reply
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:write` |
        | **Cost** | Free |

        Needs a user credential — see the note on `GET /sms/templates`.
      security:
        - apiKey: []
        - oauth2: [sms:write]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TemplateInput" }
            examples:
              default:
                value:
                  title: Callback promise
                  body: Thanks for reaching out — someone will call you back within the hour.
      responses:
        "201":
          description: Saved.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Template" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /sms/templates/{id}:
    put:
      operationId: updateTemplate
      summary: Edit a saved reply
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:write` |
        | **Cost** | Free |

        Send both `title` and `body` every time — this replaces the saved reply
        rather than patching it, so anything you leave out is overwritten, not
        kept. A saved reply belonging to another user is `404`.
      security:
        - apiKey: []
        - oauth2: [sms:write]
      parameters:
        - $ref: "#/components/parameters/TemplateID"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TemplateInput" }
      responses:
        "200":
          description: The updated reply.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Template" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }
    delete:
      operationId: deleteTemplate
      summary: Delete a saved reply
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:write` |
        | **Cost** | Free |

        Permanently removes the saved reply. One belonging to another user is `404`.
      security:
        - apiKey: []
        - oauth2: [sms:write]
      parameters:
        - $ref: "#/components/parameters/TemplateID"
      responses:
        "204": { description: Deleted. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

  /sms/drafts/{draftId}:
    get:
      operationId: getDraft
      summary: Read a draft
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:read` |
        | **Cost** | Free |

        A draft is unsent text stored under a key **you** choose — normally the
        conversation (your line plus the other number, like the example below).
        Since you pick the key, you can read any conversation's draft even if none
        was ever saved: a missing one returns **`204`, not `404`**, because
        "nothing typed yet" is normal, not an error.
      security:
        - apiKey: []
        - oauth2: [sms:read]
      parameters:
        - $ref: "#/components/parameters/DraftID"
      responses:
        "200":
          description: The draft.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Draft" }
        "204": { description: No draft saved under that key. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }
    put:
      operationId: saveDraft
      summary: Save a draft
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:write` |
        | **Cost** | Free |

        Because you supply the key, this `PUT` is idempotent — saving twice is the
        same as saving once — so you can auto-save on every keystroke, overlapping
        saves and all.

        An empty `message` is legal: it stores "the user cleared the box" without
        deleting the draft.
      security:
        - apiKey: []
        - oauth2: [sms:write]
      parameters:
        - $ref: "#/components/parameters/DraftID"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DraftInput" }
            examples:
              default:
                value:
                  message: "Hi Dana — checking in about"
      responses:
        "200":
          description: The saved draft.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Draft" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }
    delete:
      operationId: deleteDraft
      summary: Discard a draft
      tags: [SMS]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `sms:write` |
        | **Cost** | Free |

        Deleting a draft that doesn't exist still **succeeds** (`204`), not
        `404`: the goal is that no draft remains, and if there's already none,
        that goal is met. This matters because the usual caller is the code that
        just sent a message and is now clearing its draft — if that cleanup got a
        `404`, it would look like the send failed, even though the message went
        out fine.
      security:
        - apiKey: []
        - oauth2: [sms:write]
      parameters:
        - $ref: "#/components/parameters/DraftID"
      responses:
        "204": { description: Discarded. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  # -------------------------------------------------------------- Users -----
  /users:
    get:
      operationId: listUsers
      summary: List the account's users
      tags: [Users]
      description: |
        The company's users — this is what turns a user id or an extension into a
        person.

        | | |
        | --- | --- |
        | **Scope** | `users:read` |
        | **Role permission** | Users |
        | **Cost** | Free |

        **Personal data.** Names, emails and mobile numbers.

        Sorted by last name, then first name, then id. That order is fixed, so
        the same user sits in the same position on every call — which means
        comparing two responses shows only real changes: which users were added,
        removed, or had their details edited. There are no filter or paging
        parameters: one call returns the complete list the credential may see.

        This is **not** an address book. It returns the company's users only,
        never anyone's personal contacts.
      security:
        - apiKey: []
        - oauth2: [users:read]
      responses:
        "200":
          description: The users the credential may see.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/User" }
              examples:
                default:
                  value:
                    data:
                      - id: 481920
                        username: dspencer
                        firstName: Dana
                        lastName: Spencer
                        title: Support Lead
                        email: dana@acme.example
                        mobile: "13475550188"
                        company: Acme Inc
                        timeZone: America/New_York
                        extension: "204"
                        extensions: ["204"]
                        lines: ["acme-204"]
                        numbers: ["12125550188"]
                        voicemails: ["204"]
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  # ------------------------------------------------------------- Calls -----
  /calls:
    post:
      operationId: placeCall
      summary: Place a call (click to call)
      tags: [Calls]
      description: |
        **This spends money.** Every call placed is charged to the account.

        Rings a phone on the account first. When someone answers it, the call
        goes on to `to`, so the person at that phone is connected to the
        number. This is the API version of clicking a number to call it.

        | | |
        | --- | --- |
        | **Scope** | `calls:make` |
        | **Key grants** | **Phones — required.** `phone` must be one of the key's phones. Phone numbers limit `callerId`. |
        | **Role permission** | Phone numbers — a `callerId` number must be one of the role's numbers |
        | **Cost** | Charged per call, on the account's plan |

        **An API key must list the phones it may ring.** Pick them on the key
        under **Phones**. A key with no phones selected **cannot place calls**:
        every request is refused with `403`. An OAuth token may ring only the
        authorizing user's own phones.

        **`201` means the phone is ringing, not that anyone answered.** Nothing
        reports whether the call connected. When it ends, it is in call
        history (`GET /calls/{callid}` with `reports:read`) and in the call
        webhooks.

        **`callerId`** is what the person you call sees:

        | Value | Shows |
        | --- | --- |
        | omitted or `""` | The phone's own outbound caller ID |
        | `default` | The account's main caller ID |
        | `original`, `original_own_number` | The phone's own number |
        | a number | That number. It must be on the user's TeleConsole caller ID list, among the role's Phone numbers, and within the key's number grants if it has any. |

        **The caller ID must be one the user could pick in TeleConsole.** A
        number is on the user's list when: it is a number or verified caller
        ID of the account in a group that allows caller ID; the user's
        phone-system role may see the company's numbers, or it is the caller
        ID of one of the user's own phones; it is not a fax number; it is not
        limited to other users in the admin center; and, when the account
        restricts numbers, it is set up in the admin center. An account that
        restricts numbers also refuses `""` and `default`.

        Two things can override what you ask for:

        - Users whose phone-system role may not change caller ID always call
          with the phone's own caller ID, whatever `callerId` says.
        - A key with **number grants** must end on a granted number. Send that
          number as `callerId`, or `default` when the account's main caller ID
          is granted. Omitted, `""` and `original` are refused for such a key,
          because the number they show is not known in advance.

        **One destination per request.** `to` is a number or an extension:
        10 digits get a leading `1`; `+` and international numbers get the
        `011` prefix; spaces, dashes, dots and parentheses are ignored. Letters
        are refused.

        Unknown fields are rejected.
      security:
        - apiKey: []
        - oauth2: [calls:make]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PlaceCallInput" }
            examples:
              ownCallerId:
                summary: Ring a phone, show its own caller ID
                value:
                  phone: "6589455"
                  to: "13475550123"
              number:
                summary: Show one of the account's numbers
                value:
                  phone: "6589455"
                  to: "(347) 555-0123"
                  callerId: "12125550188"
      responses:
        "201":
          description: |
            Handed to the phone system: the phone is ringing. `callId` is the
            call's id, the one call history and webhooks use. It is missing
            when the phone system did not name the call within a couple of
            seconds; the call is placed either way. **Do not retry a `201`**:
            that places a second call.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/PlacedCall" }
              examples:
                default:
                  value:
                    data:
                      callId: "1761755203.884213"
                      phone: "6589455"
                      to: "13475550123"
                      callerId: "12125550188"
        "400":
          description: |
            `invalid_request` — a missing or malformed field, an unknown field,
            or the phone system refused the destination. **No call was placed.**
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
              examples:
                to:
                  summary: "`to` with letters"
                  value:
                    error:
                      type: invalid_request
                      message: "to must be a phone number: digits, optionally with a leading + and spaces, dashes, dots or parentheses"
                destination:
                  summary: The phone system refused the destination
                  value:
                    error:
                      type: invalid_request
                      message: invalid destination
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403":
          description: |
            `insufficient_scope` (the credential lacks `calls:make`) or
            `permission_denied` (the credential may not ring that phone or use
            that caller ID). **No call was placed.**

            - `insufficient_scope` — **fix: add the scope** to the key.
            - `permission_denied` — **fix: in the admin center** — the key's
              phones and number grants, the role's Phone numbers, or the
              number's access (a `callerId` must be on the user's TeleConsole
              caller ID list). When the account restricts numbers, send a
              caller ID number instead of `""` or `default`.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
              examples:
                noPhones:
                  summary: The key has no phones selected
                  value:
                    error:
                      type: permission_denied
                      message: "this API key has no phones it may ring; add phones to the key to place calls"
                phone:
                  summary: "`phone` is not one of the key's phones"
                  value:
                    error:
                      type: permission_denied
                      message: this API key is not allowed to ring phone 6589456
                callerId:
                  summary: "`callerId` is not one of the role's numbers, or not granted to the key"
                  value:
                    error:
                      type: permission_denied
                      message: your credentials are not authorized to use 12125550199 as caller ID
                notOnList:
                  summary: "`callerId` is not on the user's TeleConsole caller ID list"
                  value:
                    error:
                      type: permission_denied
                      message: "12125550177 is not one of your caller ID numbers (the numbers you could pick as caller ID in TeleConsole)"
                blocked:
                  summary: The account restricts numbers, and `callerId` is `""` or `default`
                  value:
                    error:
                      type: permission_denied
                      message: "this account does not allow calls with the default or no caller ID; set callerId to one of your caller ID numbers"
                narrowed:
                  summary: A key with number grants, and no `callerId` number
                  value:
                    error:
                      type: permission_denied
                      message: "this API key is limited to specific numbers: set callerId to one of them"
        "500": { $ref: "#/components/responses/InternalError" }

  /calls/search:
    post:
      operationId: searchCalls
      summary: Search call history
      tags: [Calls]
      description: |
        A page of calls, newest first, for a time window you specify.

        | | |
        | --- | --- |
        | **Scope** | `reports:read` |
        | **Role permission** | Call reports |
        | **Cost** | Free |

        **It searches; it changes nothing.** It uses `POST`, which usually means
        "create or update," but this one only reads — so if a response gets lost,
        you can safely send it again. We use `POST` because the search is too
        detailed to fit in a web address, and web addresses get recorded in
        server logs along the way; the request body keeps it both workable and
        private.

        **You must give a `start` and an `end`** — the beginning and end of the
        time range to search, each as a Unix timestamp (seconds since January 1,
        1970) and no more than 366 days apart (about a year). There is no default
        on purpose: if these could be left out, a program that forgot them might
        get back a single day of calls and present it as the whole month.

        **Paged.** Up to `limit` calls per response — 50 by default, 500 at most —
        with `offset` to walk further in and `total` in the response to size the
        full set. Newest first unless you set `sort`.
      security:
        - apiKey: []
        - oauth2: [reports:read]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CallSearchInput" }
            examples:
              window:
                summary: Everything in a time window
                value:
                  start: 1754006400
                  end: 1754092800
                  timeZone: America/New_York
                  limit: 50
              missedInbound:
                summary: Inbound calls nobody answered
                value:
                  start: 1754006400
                  end: 1754092800
                  timeZone: America/New_York
                  direction: inbound
                  filters:
                    statuses: [missed]
              queueByPurpose:
                summary: One queue, filtered on the AI purpose field
                value:
                  start: 1754006400
                  end: 1754092800
                  filters:
                    queues: ["501"]
                    callPurpose: [billing]
                  sort:
                    field: startTime
                    direction: desc
      responses:
        "200":
          description: A page of matching calls.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/CallPage" }
              examples:
                default:
                  value:
                    data:
                      total: 812
                      limit: 50
                      offset: 0
                      calls:
                        - id: "1754489201.884213"
                          direction: inbound
                          status: answered
                          statusCode: 1
                          callerType: external
                          callerName: ACME ROOFING
                          callerNumber: "13475550123"
                          calledType: user
                          calledName: Dana Spencer
                          calledNumber: "204"
                          dialledNumber: "12125550188"
                          startTime: "2026-08-11T13:20:01Z"
                          endTime: "2026-08-11T13:24:00Z"
                          durationSeconds: 239
                          talkTimeSeconds: 220
                          transferred: 0
                          abandoned: false
                          recorded: true
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /calls/{callid}:
    get:
      operationId: getCall
      summary: Get one call with its legs
      tags: [Calls]
      description: |
        One call's full journey: the summary fields, plus a `legs` array
        describing what happened inside it.

        | | |
        | --- | --- |
        | **Scope** | `reports:read` |
        | **Role permission** | Call reports |
        | **Cost** | Free |

        A call that rang a queue, was answered and was transferred is **one call
        and several legs**. Follow a transfer by chaining on each leg's
        `bridgedFromCallId`.
      security:
        - apiKey: []
        - oauth2: [reports:read]
      parameters:
        - $ref: "#/components/parameters/CallID"
      responses:
        "200":
          description: The call.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/CallDetail" }
              examples:
                transferred:
                  summary: A transferred inbound call — one call, two legs
                  value:
                    data:
                      id: "1754489201.884213"
                      direction: inbound
                      status: answered
                      statusCode: 2
                      callerType: external
                      callerName: ACME ROOFING
                      callerNumber: "13475550123"
                      calledType: user
                      calledName: Dana Spencer
                      calledNumber: "204"
                      dialledNumber: "12125550188"
                      startTime: "2026-08-11T13:20:01Z"
                      endTime: "2026-08-11T13:24:00Z"
                      durationSeconds: 239
                      talkTimeSeconds: 220
                      transferred: 1
                      abandoned: false
                      recorded: true
                      legs:
                        - uniqueId: "1754489201.884213"
                          callId: "1754489201.884213"
                          startTime: "2026-08-11T13:20:01Z"
                          endTime: "2026-08-11T13:21:37Z"
                          durationSeconds: 96
                          talkTimeSeconds: 81
                          fromType: external
                          from: "13475550123"
                          fromName: ACME ROOFING
                          toType: user
                          to: "204"
                          hasRecording: true
                        - uniqueId: "1754489288.884219"
                          callId: "1754489288.884219"
                          bridgedFromCallId: "1754489201.884213"
                          startTime: "2026-08-11T13:21:28Z"
                          endTime: "2026-08-11T13:23:50Z"
                          durationSeconds: 142
                          talkTimeSeconds: 139
                          fromType: user
                          from: "204"
                          fromName: Dana Spencer
                          toType: user
                          to: "301"
                          hasRecording: true
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

  /calls/{callid}/transcripts:
    get:
      operationId: getCallTranscripts
      summary: Get a call's transcripts
      tags: [Calls]
      description: |
        Every transcript for a call — **one per recorded leg**, not one per call.

        | | |
        | --- | --- |
        | **Scope** | `recordings:read` |
        | **Role permission** | Call reports → allow recordings |
        | **Cost** | Free |

        **Why `recordings:read` and not `reports:read`:** a transcript is the
        conversation written down, so it carries the same privacy weight as the
        audio. The platform gates both on the same role permission, so they share
        one scope — a consent screen offering "transcripts but not recordings"
        would be describing a separation that does not exist.

        A transferred call produces several recordings and therefore several
        transcripts, all sharing this call id. Pair them to legs with
        `recording`, which embeds the leg's `uniqueId`.

        **`200` with `[]` is normal** — the call was not recorded, was too short,
        or transcription has not finished. It does not mean the call is missing.
      security:
        - apiKey: []
        - oauth2: [recordings:read]
      parameters:
        - $ref: "#/components/parameters/CallID"
      responses:
        "200":
          description: The call's transcripts. Empty when there are none.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/CallTranscript" }
              examples:
                default:
                  value:
                    data:
                      - id: 44219
                        callId: "1754489201.884213"
                        recording: record_1754489201884213_93458.wav
                        shortSummary: Caller asked to reschedule Tuesday's roof inspection to 9am.
                        bulletPoints:
                          - Reschedule requested
                          - Agent confirmed the new slot
                        callPurpose: scheduling
                        callSentiment: positive
                        customerSatisfactionScore: 9
                        agentPerformanceScore: 8
                        actionRequired: true
                        actionRequiredNote: Update the crew calendar.
                        urgentActionRequired: false
                        agentName: Dana Spencer
                        agentSpeaker: 1
                        segments:
                          - start: 0.42
                            end: 3.10
                            speaker: 0
                            text: Hi, can we move Tuesday to nine?
                          - start: 3.40
                            end: 6.85
                            speaker: 1
                            text: Sure, nine works. I will update the crew.
                      - id: 44220
                        callId: "1754489201.884213"
                        recording: record_1754489288884219_93458.wav
                        shortSummary: Dana warm-transferred the caller to the scheduling desk and passed on the new 9am slot.
                        bulletPoints:
                          - Warm transfer to scheduling
                          - New 9am slot handed over
                        callPurpose: scheduling
                        callSentiment: positive
                        agentName: Dana Spencer
                        agentSpeaker: 0
                        segments:
                          - start: 0.30
                            end: 4.20
                            speaker: 0
                            text: Transferring a customer — they want Tuesday moved to nine.
                          - start: 4.50
                            end: 7.10
                            speaker: 1
                            text: Got it, I will update the crew calendar.
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

  # ------------------------------------------------- Calls & recordings -----
  /calls/{callid}/recordings:
    get:
      operationId: listCallRecordings
      summary: List a call's recordings
      tags: [Calls]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `recordings:read` |
        | **Role permission** | Call reports → allow recordings (OAuth only) |
        | **Cost** | Free |

        **The most sensitive capability on this surface** — a recording is the
        contents of a conversation, not metadata about it.

        **A call is not one recording.** A call that rang a queue, was answered
        and then transferred has several legs, and each answered leg is recorded
        separately. Picking "the" recording of a transferred call is a judgement
        only you can make, so every leg's timings and endpoints are here.

        `200` with an **empty array** means the call exists but nothing was
        recorded — recording is per-number and per-user opt-in. That is different
        from `404`, which means the call id isn't this account's. A client
        polling for a recording still being written should treat `[]` as
        "not yet" and retry; recordings usually appear within a minute of hangup.

        One gate no credential opens: if the account has **sensitive-content
        re-verification** on, recordings are unavailable over the API entirely.
      security:
        - apiKey: []
        - oauth2: [recordings:read]
      parameters:
        - $ref: "#/components/parameters/CallID"
      responses:
        "200":
          description: Every recorded leg of the call. Empty if nothing was recorded.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Recording" }
              examples:
                transferred:
                  summary: A transferred call — two recorded legs
                  value:
                    data:
                      - uniqueId: "1754489201.884213"
                        callId: "1754489201.884213"
                        url: https://api.account.telebroad.com/recordings/play/9f2c…
                        startTime: "2026-08-11T13:20:01Z"
                        durationSeconds: 96
                        talkTimeSeconds: 81
                        from: "13475550123"
                        to: "204"
                      - uniqueId: "1754489288.884219"
                        callId: "1754489288.884219"
                        url: https://api.account.telebroad.com/recordings/play/1ab4…
                        startTime: "2026-08-11T13:21:28Z"
                        durationSeconds: 142
                        talkTimeSeconds: 139
                        from: "204"
                        to: "301"
                notRecorded:
                  summary: Call exists, nothing recorded
                  value: { data: [] }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

  /calls/{callid}/recordings/{uniqueid}:
    get:
      operationId: getCallRecording
      summary: Get one recorded leg
      tags: [Calls]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `recordings:read` |
        | **Role permission** | Call reports → allow recordings (OAuth only) |
        | **Cost** | Free |

        `404` for a leg that isn't recorded on this call, whatever the reason —
        saying more would let a caller probe which leg ids exist.
      security:
        - apiKey: []
        - oauth2: [recordings:read]
      parameters:
        - $ref: "#/components/parameters/CallID"
        - name: uniqueid
          in: path
          required: true
          description: The leg identifier, from `uniqueId` in the list response.
          schema: { type: string }
          example: "1754489201.884213"
      responses:
        "200":
          description: The recorded leg.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Recording" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

  # ------------------------------------------------------------- Faxes -----
  /faxes:
    get:
      operationId: listFaxes
      summary: List sent and received faxes
      tags: [Faxes]
      description: |
        A page of the account's faxes — sent and received — newest first, for a
        time window.

        | | |
        | --- | --- |
        | **Scope** | `fax:read` |
        | **Role permission** | Fax History not set to **Block**; Phone numbers — only faxes on the role's numbers |
        | **Cost** | Free |

        **The window defaults to the last 30 days.** `end` defaults to now and
        `start` to 30 days before `end`; the two may be at most 366 days apart.
        Both take RFC 3339 or unix seconds. To filter by a fax number, use
        `number`.

        Every user's faxes on the visible numbers are returned, not only the
        faxes the credential's own user sent. A key with
        [number grants](/docs/authentication/api-keys#resource-grants-narrowing-a-key-to-specific-objects)
        sees only the granted numbers that its user's role also allows.

        A filter on a number the credential cannot see is not an error — it
        simply matches nothing.

        `total` is returned on the first page (`offset=0`) only.
      security:
        - apiKey: []
        - oauth2: [fax:read]
      parameters:
        - name: number
          in: query
          required: false
          description: |
            Only faxes on these fax lines of yours. Comma-separated; US numbers,
            10 digits or 11 starting with `1`. A value that is not a US number
            is a `400`.
          schema: { type: string }
          x-tb-suggest: fax-lines
          example: "12125550188"
        - name: direction
          in: query
          required: false
          description: Only sent, or only received, faxes. Omit for both.
          schema: { type: string, enum: [sent, received] }
        - name: user
          in: query
          required: false
          description: |
            Only faxes sent by these users — ids from `GET /users`,
            comma-separated. A received fax has no user, so this filter returns
            sent faxes only.
          schema: { type: string }
          example: "481920"
        - name: status
          in: query
          required: false
          description: |
            Comma-separated: `success`, `failed`, `pending`. A received fax is
            always `success`.
          schema: { type: string }
          example: failed
        - name: start
          in: query
          required: false
          description: |
            Start of the window — RFC 3339 or unix seconds. Defaults to 30 days
            before `end`.
          schema: { type: string }
          example: "2026-10-01T00:00:00Z"
        - name: end
          in: query
          required: false
          description: End of the window — RFC 3339 or unix seconds. Defaults to now.
          schema: { type: string }
          example: "2026-10-28T00:00:00Z"
        - $ref: "#/components/parameters/FaxLimit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: A page of matching faxes.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/FaxPage" }
              examples:
                default:
                  value:
                    data:
                      faxes:
                        - id: 7731402
                          direction: sent
                          line: "12125550188"
                          from: "12125550188"
                          to: "13475550123"
                          userId: 481920
                          pages: 3
                          status: failed
                          statusCode: 3
                          statusDetail: No answer
                          createdAt: "2026-10-27T15:02:11Z"
                        - id: 7731388
                          direction: received
                          line: "12125550188"
                          from: "17185550142"
                          to: "12125550188"
                          pages: 2
                          status: success
                          createdAt: "2026-10-27T14:40:56Z"
                      total: 2
                      limit: 50
                      offset: 0
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

    post:
      operationId: sendFax
      x-tb-suggest-body: { from: fax-lines }
      summary: Send a fax
      tags: [Faxes]
      description: |
        **This spends money.** Every fax sent is charged to the account.

        | | |
        | --- | --- |
        | **Scope** | `fax:send` |
        | **Role permission** | TeleConsole → Fax on; Phone numbers — `from` must be one of the role's numbers |
        | **Cost** | Charged per fax, on the account's plan |

        **The fax is recorded before it is handed over.** Every send that
        passes validation gets an `id` and is in `GET /faxes` at once, also
        when the fax service then refuses it (`400` / `502` carry it as
        `error.id`; the fax is listed as `failed`).

        **`201` means handed over, not delivered.** The fax goes out over the
        phone network afterwards, which takes minutes, and a `pending` fax can
        still end `failed`. Poll `GET /faxes/{id}` until `status` leaves
        `pending`.

        **Never resend a fax that has an `id`.** Follow it with
        `GET /faxes/{id}`; send again only once it is `failed` (a new fax with
        a new id).

        **One recipient per request.** To fax several people, make one request
        each.

        `from` must be a number on the account **with fax enabled**, among the
        numbers the credential's user's role allows, and within the key's
        number grants if it has any. US numbers only, on both ends.

        Files are faxed in the order given, after the cover page if you send
        one. The type is read from each file's **content**, never its name:
        PDF, PNG, TIFF, JPEG, GIF, DOC, DOCX, XLS, XLSX, PPT or PPTX. At most
        10 MB per file and 200 MB in all, decoded.

        Unknown fields are rejected, so a typo like `"flies"` gets a `400`
        instead of sending an empty fax.
      security:
        - apiKey: []
        - oauth2: [fax:send]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SendFaxInput" }
            examples:
              document:
                summary: One PDF, no cover page
                value:
                  from: "12125550188"
                  to: "13475550123"
                  files:
                    - name: invoice-1042.pdf
                      data: JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK
              withCover:
                summary: A cover page and two documents
                value:
                  from: "12125550188"
                  to: "13475550123"
                  cover:
                    name: Dr. Rivera
                    company: Midtown Clinic
                    note: |-
                      Signed referral attached.
                      Please call us with any questions.
                  files:
                    - name: referral.pdf
                      data: JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK
                    - name: insurance-card.png
                      data: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==
      responses:
        "201":
          description: |
            Recorded and handed to the fax service — **not yet delivered**.
            Almost always `pending`; it shows `failed` when the fax service
            already reported a failure. The `Location` header points at the new
            fax; poll it for the result.
          headers:
            Location:
              description: "`/api/public/v1/faxes/{id}` of the new fax."
              schema: { type: string }
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Fax" }
              examples:
                default:
                  value:
                    data:
                      id: 7731455
                      direction: sent
                      line: "12125550188"
                      from: "12125550188"
                      to: "13475550123"
                      userId: 481920
                      pages: 4
                      status: pending
                      statusCode: -1
                      statusDetail: queued
                      createdAt: "2026-10-28T16:20:03Z"
        "400":
          description: |
            `invalid_request` — a missing or malformed field, a number that is
            not a US number, an unsupported file type, a file over the size
            limits, an unknown field, or the fax service refused the fax.
            **Nothing was sent.** When the fax service refused it, `error.id`
            is the fax, listed as `failed`; fix the request before sending
            again.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
              examples:
                badType:
                  summary: A file that is not a supported type
                  value:
                    error:
                      type: invalid_request
                      message: "files[0]: file type not supported; send pdf, png, tiff, jpg, gif, doc, docx, xls, xlsx, ppt or pptx"
                tooBig:
                  summary: A file over 10 MB
                  value:
                    error:
                      type: invalid_request
                      message: "files[1]: a file may be at most 10 MB"
                refused:
                  summary: The fax service refused the fax (it is recorded as failed)
                  value:
                    error:
                      type: invalid_request
                      message: "the fax was rejected: request too large"
                      id: 7731456
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403":
          description: |
            `insufficient_scope` (the credential lacks `fax:send`) or
            `permission_denied` (the credential's user may not send faxes or use
            `from`, or `from` is not a fax line of this account). **Nothing was
            sent.**

            - `insufficient_scope` — **fix: add the scope** to the key.
            - `permission_denied` — **fix: in the admin center** — the role's
              TeleConsole → Fax setting and Phone numbers, the key's number
              grants, or fax on the number.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
              examples:
                role:
                  summary: The role has TeleConsole → Fax off
                  value:
                    error:
                      type: permission_denied
                      message: "the user this credential acts as is not allowed to send faxes (role: Teleconsole fax is off)"
                number:
                  summary: "`from` is not one of the role's numbers, or not granted to the key"
                  value:
                    error:
                      type: permission_denied
                      message: your credentials are not authorized to send from 12125550188
                line:
                  summary: "`from` is not a fax line of this account"
                  value:
                    error:
                      type: permission_denied
                      message: "12125550188 cannot send faxes: either it is not a number on this account, or fax is not enabled for it"
        "500": { $ref: "#/components/responses/InternalError" }
        "502":
          description: |
            `unavailable` — the fax was recorded, but the fax service did not
            take it. `error.id` is the fax; it is in `GET /faxes` as `failed`,
            and nothing was sent. Sending again sends a new fax. Without an
            `id`, nothing was recorded or sent.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
              examples:
                default:
                  value:
                    error:
                      type: unavailable
                      message: the fax server did not accept the fax; it is recorded as failed (see id). Sending it again sends a new fax.
                      id: 7731456
        "503":
          description: |
            `unavailable` — fax sending is not available. When the message is
            `fax sending is not configured`, retrying will not help; contact
            support.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
              examples:
                default:
                  value:
                    error:
                      type: unavailable
                      message: fax sending is not configured

  /faxes/lines:
    get:
      operationId: listFaxLines
      summary: List the fax numbers you can use
      tags: [Faxes]
      description: |
        The account's fax-enabled numbers that this credential may use: the
        user's role must grant the number, and an API key's number grants
        narrow it further. Each `number` is in the exact form `POST /faxes`
        takes for `from` and `GET /faxes` takes for `number`.

        Sending still needs `fax:send` and the role's **Teleconsole fax**
        permission; this list only says which numbers are yours to use.

        | | |
        | --- | --- |
        | **Scope** | `fax:read` |
        | **Role permission** | Phone numbers |
        | **Cost** | Free. Sends nothing. |
      security:
        - apiKey: []
        - oauth2: [fax:read]
      responses:
        "200":
          description: The fax numbers the credential may use. An empty list when it may use none.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/FaxLine" }
              examples:
                default:
                  summary: Two fax lines
                  value:
                    data:
                      - number: "12125550188"
                        name: Acme Billing
                      - number: "12125550199"
                        name: ""
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /faxes/{id}:
    get:
      operationId: getFax
      summary: Get one fax and its delivery status
      tags: [Faxes]
      description: |
        One fax, under the same visibility rules as the list. This is what to
        poll after sending: `status` is `pending` until delivery finishes, then
        `success` or `failed`, with the reason in `statusDetail`.

        | | |
        | --- | --- |
        | **Scope** | `fax:read` |
        | **Role permission** | Fax History not set to **Block**; Phone numbers |
        | **Cost** | Free |

        Not limited to a time window — any fax id the credential may see.
        `404` for an id that does not exist, was deleted, belongs to another
        account, or is on a number the credential cannot see; the cases are
        deliberately indistinguishable.

        Faxes take minutes to deliver. Poll every 30–60 seconds, not in a tight
        loop.
      security:
        - apiKey: []
        - oauth2: [fax:read]
      parameters:
        - $ref: "#/components/parameters/FaxID"
      responses:
        "200":
          description: The fax.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Fax" }
              examples:
                delivered:
                  summary: A sent fax that was delivered
                  value:
                    data:
                      id: 7731455
                      direction: sent
                      line: "12125550188"
                      from: "12125550188"
                      to: "13475550123"
                      userId: 481920
                      pages: 4
                      status: success
                      statusCode: 0
                      statusDetail: Success
                      createdAt: "2026-10-28T16:20:03Z"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

  /faxes/{id}/file:
    get:
      operationId: getFaxFile
      summary: Download a fax document
      tags: [Faxes]
      description: |
        The fax itself, as **raw bytes** — usually a PDF. Not JSON: there is
        no `data` envelope on success. Errors still come back as the usual JSON
        error envelope.

        | | |
        | --- | --- |
        | **Scope** | `fax:read` |
        | **Role permission** | Fax History set to **Allow with View Fax**; Phone numbers |
        | **Cost** | Free |

        `Content-Type` is the document's type (`application/pdf` when unknown)
        and `Content-Disposition` names it `fax-{id}.pdf` (or the matching
        extension).

        **A sent fax's document can be missing until delivery finishes.** The
        final document is stored when the fax service reports the result, so
        while a sent fax is `pending` this may answer `404` — retry once
        `GET /faxes/{id}` shows `success` or `failed`.

        A role with Fax History set to **Allow** (without View Fax) can list
        faxes but gets `403 permission_denied` here.
      security:
        - apiKey: []
        - oauth2: [fax:read]
      parameters:
        - $ref: "#/components/parameters/FaxID"
      responses:
        "200":
          description: |
            The document's bytes, with `Content-Type` set to its type (usually
            `application/pdf`) and `Content-Disposition: attachment;
            filename=fax-{id}.pdf`.
          content:
            application/pdf:
              schema: { type: string, format: binary }
            application/octet-stream:
              schema: { type: string, format: binary }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404":
          description: |
            `not_found` — no such fax visible to the credential, or the fax has
            no document **yet**. For a sent fax still `pending`, retry after it
            completes.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorEnvelope" }
              examples:
                notYet:
                  summary: The document is not available yet
                  value:
                    error:
                      type: not_found
                      message: the fax document is not available
        "500": { $ref: "#/components/responses/InternalError" }

  # ----------------------------------------------------------- Webhooks -----
  /webhooks:
    get:
      operationId: listWebhooks
      summary: List webhook subscriptions
      tags: [Webhooks]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `webhooks:read` |
        | **Cost** | Free |

        Omit both filters to list **every** subscription; add `type` or `enabled` to
        narrow it.

        New to webhooks? The [Webhooks guide](/docs/webhooks/overview) covers how
        delivery works and the event payloads you will receive.
      security:
        - apiKey: []
        - oauth2: [webhooks:read]
      parameters:
        - name: type
          in: query
          required: false
          description: Only subscriptions for this event type. An unknown type is a `400`.
          schema: { $ref: "#/components/schemas/WebhookType" }
          example: AccountSMS
        - name: enabled
          in: query
          required: false
          description: |
            Only enabled subscriptions. **`enabled=false` is not supported** —
            omit the parameter and filter the result client-side.
          schema: { type: boolean, enum: [true] }
          example: true
      responses:
        "200":
          description: The account's subscriptions.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Webhook" }
              examples:
                default:
                  value:
                    data:
                      - id: 2074
                        name: real time
                        description: ""
                        url: https://example.com/hook
                        type: AccountRealTimeCalls
                        enabled: true
                        createdAt: "2026-08-05T12:00:00Z"
                        updatedAt: "2026-08-05T12:00:00Z"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

    post:
      operationId: createWebhook
      summary: Create a webhook subscription
      tags: [Webhooks]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `webhooks:write` |
        | **Cost** | Free |

        `enabled` defaults to **`false`**, so a half-configured integration
        cannot start firing at an endpoint that is not ready.

        Returns `201`. The **`Location` header** on the response — a standard HTTP
        header that points to a newly created resource — holds the path of the new
        subscription (its `/webhooks/{id}`). Use it to fetch or manage what you just
        created.

        For the end-to-end flow — subscribing, delivery guarantees and verifying —
        see the [Webhooks guide](/docs/webhooks/subscribing).
      security:
        - apiKey: []
        - oauth2: [webhooks:write]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WebhookCreateInput" }
            examples:
              default:
                value:
                  name: My hook
                  url: https://example.com/hook
                  type: AccountSMS
                  enabled: true
      responses:
        "201":
          description: Created.
          headers:
            Location:
              description: Path of the new subscription.
              schema: { type: string }
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Webhook" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /webhooks/types:
    get:
      operationId: listWebhookTypes
      summary: List the valid event types
      tags: [Webhooks]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `webhooks:read` |
        | **Cost** | Free |

        Use this endpoint to get the current list of valid event-type names, rather
        than copying them from documentation that might be out of date.

        It matters because a wrong or misspelled `type` is **rejected** when you
        create a subscription (a `400`). That's deliberate: the alternative — a
        subscription that saves with a typo, shows as enabled, and then silently
        never delivers — would be the worst kind of bug to track down.
      security:
        - apiKey: []
        - oauth2: [webhooks:read]
      responses:
        "200":
          description: The event types a subscription may register for.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/WebhookType" }
              examples:
                default:
                  value:
                    data:
                      - AccountRealTimeCalls
                      - AccountEndedCalls
                      - UserEndedCalls
                      - AccountSMS
                      - AccountAITranscription
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "500": { $ref: "#/components/responses/InternalError" }

  /webhooks/{id}:
    get:
      operationId: getWebhook
      summary: Get one subscription
      tags: [Webhooks]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `webhooks:read` |
        | **Cost** | Free |

        Fetch a single subscription by its id — the same `Webhook` shape that
        `GET /webhooks` returns for each entry in its list. A `404` means there is
        no subscription with that id on your account.
      security:
        - apiKey: []
        - oauth2: [webhooks:read]
      parameters: [{ $ref: "#/components/parameters/WebhookID" }]
      responses:
        "200":
          description: The subscription.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Webhook" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

    patch:
      operationId: updateWebhook
      summary: Update a subscription (merge)
      tags: [Webhooks]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `webhooks:write` |
        | **Cost** | Free |

        **`PUT` and `PATCH` both merge** — any field you leave out keeps its current
        value. (Normally `PUT` *replaces* the whole record, but here it behaves
        exactly like `PATCH`; there's no replace-everything option.)

        A body that contains no updatable field returns a `400`, rather than silently
        doing nothing.
      security:
        - apiKey: []
        - oauth2: [webhooks:write]
      parameters: [{ $ref: "#/components/parameters/WebhookID" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WebhookUpdateInput" }
            examples:
              retarget:
                summary: Point it at a new URL
                value: { url: https://example.com/hook/v2 }
      responses:
        "200":
          description: The stored subscription, re-read after the write.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Webhook" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

    put:
      operationId: replaceWebhook
      summary: Update a subscription (merge — identical to PATCH)
      tags: [Webhooks]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `webhooks:write` |
        | **Cost** | Free |

        Identical to `PATCH` — this **merges**, keeping any field you leave out.
        Normally `PUT` would replace the whole record; it does not here. It's here
        only because clients expect a `PUT` to exist.
      security:
        - apiKey: []
        - oauth2: [webhooks:write]
      parameters: [{ $ref: "#/components/parameters/WebhookID" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WebhookUpdateInput" }
            examples:
              retarget:
                summary: Point it at a new URL
                value: { url: https://example.com/hook/v2 }
      responses:
        "200":
          description: The stored subscription, re-read after the write.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Webhook" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

    delete:
      operationId: deleteWebhook
      summary: Delete a subscription
      tags: [Webhooks]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `webhooks:write` |
        | **Cost** | Free |

        Permanently removes a subscription. Returns `204` with an empty body —
        there's nothing to return. Deletion can't be undone, so if you might want
        the subscription back, disable it instead (`POST /webhooks/{id}/disable`).
      security:
        - apiKey: []
        - oauth2: [webhooks:write]
      parameters: [{ $ref: "#/components/parameters/WebhookID" }]
      responses:
        "204": { description: Deleted. No body. }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

  /webhooks/{id}/enable:
    post:
      operationId: enableWebhook
      summary: Start delivering to a subscription
      tags: [Webhooks]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `webhooks:write` |
        | **Cost** | Free |

        Turns delivery **on** for a subscription.

        It's a `POST`, not a `GET`, on purpose: software all over the internet —
        browsers, proxies, link-preview bots — automatically fetches `GET` URLs, so
        a `GET` that changed state could switch your subscription on just from
        someone's software loading the link.
      security:
        - apiKey: []
        - oauth2: [webhooks:write]
      parameters: [{ $ref: "#/components/parameters/WebhookID" }]
      responses:
        "200":
          description: The subscription, now enabled.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Webhook" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

  /webhooks/{id}/disable:
    post:
      operationId: disableWebhook
      summary: Stop delivering to a subscription
      tags: [Webhooks]
      description: |
        | | |
        | --- | --- |
        | **Scope** | `webhooks:write` |
        | **Cost** | Free |

        Turns delivery **off** for a subscription.

        The subscription is kept, so you can re-enable it later without
        reconfiguring. Disable rather than delete when you want a pause, not a
        removal.
      security:
        - apiKey: []
        - oauth2: [webhooks:write]
      parameters: [{ $ref: "#/components/parameters/WebhookID" }]
      responses:
        "200":
          description: The subscription, now disabled.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Webhook" }
        "401": { $ref: "#/components/responses/Unauthenticated" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "500": { $ref: "#/components/responses/InternalError" }

components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: |
        A customer API key — `tbk_live_…` — created in the admin center under
        **Integrations → API Keys**. Sent as `Authorization: Bearer tbk_live_…`.

        A key authenticates the account, not a browser session, so it needs no
        consent flow. Its capabilities are the scopes selected when it was
        issued. Treat it like a password: it is shown once, and anyone holding
        it can act as the account within those scopes.

        A key reaches an endpoint only if it carries that endpoint's scope. A key
        with no scopes selected reaches nothing — it does not default to full
        access.
    oauth2:
      type: oauth2
      description: |
        OAuth 2.1 authorization code + **PKCE (S256, required)** for public
        clients — no client secret is issued. Use this when your application
        acts on behalf of a specific user; the token can never exceed what that
        user could do themselves.

        Read the live endpoints from the discovery document at
        `/.well-known/oauth-authorization-server` rather than hardcoding them.
      flows:
        authorizationCode:
          authorizationUrl: https://api.account.telebroad.com/api/v1/oauth/authorize
          tokenUrl: https://api.account.telebroad.com/api/v1/oauth/token
          refreshUrl: https://api.account.telebroad.com/api/v1/oauth/token
          scopes:
            webhooks:read: List and view webhook subscriptions
            webhooks:write: Create, update, delete, enable and disable subscriptions
            reports:read: Read call history and analytics
            users:read: List the account's users — names, emails, extensions. Personal data.
            sms:read: Texting configuration — which numbers can text, blocked senders, templates, schedules. Not message content.
            sms:write: Resolve or assign a conversation, and manage blocked senders, templates and drafts. Cannot send to anyone.
            messages:read: Read message content — the inbox, a thread's text and media, delivery receipts, unread counts.
            messages:write: Mark messages read or unread, and permanently delete messages or conversations.
            sms:send: Send SMS from the account's numbers. THIS SPENDS MONEY.
            recordings:read: Fetch links to call-recording audio. The contents of conversations.
            fax:read: List the account's sent and received faxes with their delivery status, and download the fax documents. The contents of communications.
            fax:send: Send faxes from the account's fax numbers. THIS SPENDS MONEY.
            calls:make: Place click-to-call calls — ring a phone, then connect it to a number. THIS SPENDS MONEY.

  parameters:
    Line:
      name: line
      in: path
      required: true
      description: One of your account's numbers — the line the thread is on. Digits.
      # Populates the playground's picker from GET /sms/lines, so nobody has to
      # know one of their own numbers by heart to try an endpoint.
      x-tb-suggest: sms-lines
      schema: { type: string }
      example: "12125550188"
    OtherNumber:
      name: number
      in: path
      required: true
      description: The other party's number. Digits.
      schema: { type: string }
      example: "13475550123"
    MessageID:
      name: id
      in: path
      required: true
      description: The message id, from a thread read or an `AccountSMS` webhook.
      schema: { type: integer, format: int64 }
      example: 90218841
    ScheduleID:
      name: id
      in: path
      required: true
      description: The scheduled-message id.
      schema: { type: integer, format: int64 }
      example: 55120
    TemplateID:
      name: id
      in: path
      required: true
      description: The saved reply's id.
      schema: { type: integer, format: int64 }
      example: 3312
    DraftID:
      name: draftId
      in: path
      required: true
      description: The key you chose for this draft. At most 128 characters.
      schema: { type: string, maxLength: 128 }
      example: "12125550188:13475550123"
    SMSLinePath:
      name: line
      in: path
      required: true
      description: One of your account's numbers. Digits.
      x-tb-suggest: sms-lines
      schema: { type: string }
      example: "12125550188"
    Limit:
      name: limit
      in: query
      required: false
      description: |
        Page size. An out-of-range value is a `400` rather than a silent clamp —
        a client asking for 5000 and receiving 200 with no explanation concludes
        the account only has 200 messages.
      schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
    Offset:
      name: offset
      in: query
      required: false
      description: How many results to skip before this page, for paging. Defaults to 0.
      schema: { type: integer, minimum: 0, default: 0 }
    FaxID:
      name: id
      in: path
      required: true
      description: The fax id, from `GET /faxes` or a send.
      schema: { type: integer, format: int64 }
      example: 7731455
    FaxLimit:
      name: limit
      in: query
      required: false
      description: |
        Page size. An out-of-range value is a `400` rather than a silent clamp.
      schema: { type: integer, minimum: 1, maximum: 500, default: 50 }
    CallID:
      name: callid
      in: path
      required: true
      description: |
        The call id from call history, reports or a call webhook — a unix
        timestamp, a dot, and a sequence number. A malformed id is a `400` that
        names the expected shape, not a `404`.
      schema:
        type: string
        pattern: '^\d{10,14}\.\d{1,10}$'
      example: "1754489201.884213"
    WebhookID:
      name: id
      in: path
      required: true
      description: The subscription id.
      schema: { type: integer, format: int64 }
      example: 2074

  schemas:
    FaxLine:
      type: object
      title: Fax line
      description: One fax number on the account that this credential may use.
      required: [number, name]
      properties:
        number:
          type: string
          description: |
            The fax number in the exact form `from` and the `number` filter
            want. Copy it straight through.
          example: "12125550188"
        name:
          type: string
          description: The number's caller-ID name. Empty if none is set.
          example: Acme Billing
    SMSLine:
      type: object
      title: SMS line
      description: One number on the account that can text.
      required: [number, name, userIds, bulkEnabled]
      properties:
        number:
          type: string
          description: |
            The sending number, already in the exact form `from` wants. Copy it
            straight through — no reformatting.
          example: "12125550188"
        name:
          type: string
          description: The line's caller-ID name, as shown in the portal. Empty if none is set.
          example: Acme Support
        userIds:
          type: array
          description: |
            The users assigned to this line in the message center. Each value is a
            user's numeric id — the `id` field returned by `GET /users`, which is
            where you look up which id belongs to which person. **An empty `userIds`
            means the line is unrestricted — available to everyone, not that nobody
            has it.**
          items: { type: integer, format: int64 }
        bulkEnabled:
          type: boolean
          description: |
            Whether the number is registered for 10DLC bulk/campaign traffic.
            Shown for information only — you can't filter the list by it. Campaign
            registration is **not** required to send through this API, so a line
            with `false` sends fine.

    SendSMSInput:
      type: object
      title: Send input
      required: [from, to]
      properties:
        from:
          type: string
          description: |
            A number on your account with SMS enabled — one of the entries from
            `GET /sms/lines`. Digits only; formatting is stripped. Required and
            never guessed: it is what the recipient sees and what the carrier
            attributes your traffic to.
          example: "12125550188"
        to:
          type: array
          description: |
            1–20 **distinct** recipients. **More than one creates a group
            thread**, billed once as MMS — not N separate texts.
          minItems: 1
          maxItems: 20
          items: { type: string }
          example: ["13475550123"]
        message:
          type: string
          description: |
            The text. Required **unless** you send `attachments` — a picture with
            no caption is an ordinary MMS. Without attachments, a whitespace-only
            body is rejected rather than sent, because it would be charged for.
          example: Your appointment is confirmed for Tuesday at 10am.
        attachments:
          type: array
          description: |
            Files to send as **MMS**. Up to 10, each at most 5 MB decoded.

            **Attachments change the price.** A message carrying any file is an
            MMS at the carrier, so it is charged **once at the MMS rate** rather
            than per segment — whether it goes to one recipient or twenty.

            You send the **bytes**, not a URL. We host the file and return its
            URL in the response.
          maxItems: 10
          items: { $ref: "#/components/schemas/SendAttachment" }

    SendAttachment:
      type: object
      title: Attachment
      required: [filename, contentType, content]
      properties:
        filename:
          type: string
          description: |
            The filename. Its **extension is load-bearing** — it decides the
            content type the recipient's handset is told, so a name without one
            is rejected rather than delivered as a file nothing can open.
          example: receipt.png
        contentType:
          type: string
          enum: [image/jpeg, image/png, image/bmp, image/gif]
          description: |
            The file's MIME type. Only these four are deliverable; anything else
            is rejected here rather than accepted, charged at the MMS rate, and
            then silently not rendered by the handset.
          example: image/png
        content:
          type: string
          format: byte
          description: |
            The file itself, standard base64, **at most 5 MB decoded**.

            Note that 5 MB is what this API accepts, not what arrives: carriers
            routinely transcode or drop large MMS. **1 MB or under** is what
            delivers reliably.
          example: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==

    SendResult:
      type: object
      title: Send result
      required: [from, billing, messages, skipped]
      properties:
        from:
          type: string
          description: The number the message was sent from.
        billing: { $ref: "#/components/schemas/SMSBilling" }
        messages:
          type: array
          description: What was dispatched. Empty when every recipient was skipped.
          items: { $ref: "#/components/schemas/SentMessage" }
        skipped:
          type: array
          description: Recipients dropped before sending, and never charged for.
          items: { $ref: "#/components/schemas/SkippedMessage" }

    SentMessage:
      type: object
      title: Sent message
      required: [to, type, status, units, unitPrice, price]
      properties:
        id:
          type: integer
          format: int64
          description: The message id. Absent when the gateway returned none.
        to:
          type: array
          description: |
            The **normalized** destinations — what was actually dialled and what
            the charge is against. Always an array, including for one recipient,
            so you never branch on the shape.
          items: { type: string }
        type:
          type: string
          enum: [sms, mms]
          description: |
            Which billing model applied. `mms` means the message was **either** a
            group thread **or** carried attachments — either one alone is enough.
        status:
          type: string
          description: |
            `sent` means the carrier gateway **accepted** the message — not that
            a handset received it. Subscribe to the `AccountSMS` webhook for
            delivery events.
          example: sent
        media:
          type: array
          description: |
            The hosted URLs of the attachments you sent, in the order supplied.
            Absent when the message had none.

            **These URLs are publicly fetchable** — unguessable, but nothing else
            protects them. Treat one as a secret, and don't forward it to anyone
            who shouldn't see the message.
          items: { type: string, format: uri }
        units:
          type: integer
          description: What you were charged for — segments for `sms`, always 1 for `mms`.
        unitPrice:
          type: number
          format: double
          description: |
            Rate per unit. On a group thread whose participants sit on different
            rates, this is the highest that applied.
        price:
          type: number
          format: double
          description: "`unitPrice` × `units`, always."

    SkippedMessage:
      type: object
      title: Skipped recipient
      required: [to, reason]
      properties:
        to:
          type: string
          description: |
            The recipient **as you supplied it**, so you can match it back to
            your own input — a skipped recipient may not have normalized at all.
        reason:
          type: string
          enum: [opted_out, duplicate, invalid]
          description: |
            A stable token, safe to branch on. `opted_out` — the recipient sent
            STOP to this number. `duplicate` — the number appeared twice in
            `to`. `invalid` — not a dialable number.

    SMSBilling:
      type: object
      title: Billing
      description: |
        Present on every send response, always — including when nothing was
        charged.
      required: [billed, currency, type, units, totalPrice, recipientCount, skippedCount]
      properties:
        billed:
          type: boolean
          description: |
            Always `true`. It describes the **endpoint**, not the individual
            call, so it stays `true` even when a particular call cost nothing.
            Unlike the portal, API traffic never consumes the rate card's
            monthly free allowance.
        currency:
          type: string
          description: The currency of every price in this response. Always `USD` today.
          example: USD
        type:
          type: string
          enum: [sms, mms]
          description: |
            `sms` — one recipient and no attachments, charged **per segment**,
            so a long body costs a multiple of a short one. `mms` — a group
            thread **or** a message carrying attachments, charged **once**,
            regardless of body length or participant count.
        units:
          type: integer
          description: Segments for `sms`, 1 for `mms`.
        totalPrice:
          type: number
          format: double
          description: What this request cost. `0` if nothing was sent.
        recipientCount:
          type: integer
          description: How many destinations it went to. For `mms` this does **not** multiply the price.
        skippedCount:
          type: integer
          description: How many supplied recipients were dropped, and so never charged for.

    ResolveInput:
      type: object
      title: Resolve input
      description: Entirely optional — a bare POST resolves the thread.
      properties:
        resolvedBy:
          type: integer
          format: int64
          description: |
            Credit a specific user, matching `id` in `GET /users`. **Honoured
            for API keys only** — an OAuth token always credits its own owner,
            because inventing a different one would corrupt "who closed this".

    Conversation:
      type: object
      title: Conversation
      description: The state of one thread after the action.
      required: [line, number, resolved]
      properties:
        line:
          type: string
          description: Your account number the thread is on, **normalized**.
        number:
          type: string
          description: The other party's number, **normalized**.
        resolved:
          type: boolean
          description: The thread's state after this call.
        resolvedBy:
          type: integer
          format: int64
          description: |
            The user credited, matching `id` in `GET /users`. Absent when an
            integration resolved it with no person named.
        resolvedAt:
          type: string
          format: date-time
          description: When, RFC 3339 UTC. Absent when not resolved.

    ConversationSummary:
      type: object
      title: Conversation summary
      description: One thread in the inbox — its newest message plus its queue state.
      required: [line, number, lastMessage, lastMessageAt, direction, unread, resolved]
      properties:
        line:
          type: string
          description: Your account number the thread is on, normalized.
        number:
          type: string
          description: The other party's number, normalized.
        groupParticipants:
          type: array
          description: Every number on a group thread. Absent for a 1:1.
          items: { type: string }
        lastMessage:
          type: string
          description: Preview text of the newest message.
        lastMessageId:
          type: integer
          format: int64
          description: Its id, so you can open the thread at the right place.
        lastMessageAt:
          type: string
          format: date-time
          description: When the newest message was sent, RFC 3339 UTC.
        direction:
          type: string
          enum: [in, out]
          description: Direction of that newest message, so a client can render the "you" prefix without reading the thread.
        hasMedia:
          type: boolean
          description: Whether the newest message carries an attachment, so a client can flag it without opening the thread.
        unread:
          type: boolean
          description: Whether YOU have unread messages here. Per user — a thread a colleague read is still unread for you.
        unreadCount:
          type: integer
          description: How many unread messages YOU have in this thread.
        resolved:
          type: boolean
          description: Whether the thread is marked resolved.
        resolvedBy:
          type: integer
          format: int64
          description: The user who resolved it, matching `id` in `GET /users`. Absent when the thread is open or an integration resolved it.
        resolvedAt:
          type: string
          format: date-time
          description: When it was resolved, RFC 3339 UTC. Absent when the thread is open.
        assignedTo:
          type: integer
          format: int64
          description: |
            The user who owns the thread, matching `id` in `GET /users`. Absent
            when nobody does — which is a real state the filters use, not missing
            data.

    Message:
      type: object
      title: Message
      description: One SMS or MMS in a conversation.
      required: [id, direction, from, to, text, sentAt, read]
      properties:
        id:
          type: integer
          format: int64
          description: The message's id.
        direction:
          type: string
          enum: [in, out]
          description: |
            `in` = they texted you, `out` = you texted them. Spelled this way
            rather than the carrier's MO/MT, which reads backwards to everyone
            the first time.
        from:
          type: string
          description: The sender's number, normalized.
        to:
          type: string
          description: The recipient's number, normalized.
        text:
          type: string
          description: The body. Empty is legal and normal for an MMS that carries only an image.
        media:
          type: array
          description: |
            Attachment URLs. **Publicly readable** — the URL is the only thing
            protecting the file. Treat them as secrets and do not log them.
          items: { type: string }
        sentAt:
          type: string
          format: date-time
          description: When it was sent, RFC 3339 UTC.
        read:
          type: boolean
          description: Whether YOU have read it.
        readBy:
          type: array
          description: Every user who has read it, matching `id` in `GET /users`.
          items: { type: integer, format: int64 }
        sentBy:
          type: integer
          format: int64
          description: The user who sent it. Absent when an integration sent it rather than a person.
        delivery:
          $ref: "#/components/schemas/MessageDelivery"
        groupParticipants:
          type: array
          description: Every number on a group thread. Absent for a 1:1.
          items: { type: string }
        scheduled:
          type: boolean
          description: Queued for future delivery — in the thread, but not sent yet.
        scheduledAt:
          type: string
          format: date-time
          description: When it is queued to go out, RFC 3339 UTC. Present only while `scheduled` is true.
        blocked:
          type: boolean
          description: |
            Not delivered because the other party is on this line's blocked-sender
            list. The message exists and was charged for.
        blockReason:
          type: string
          description: Why it was blocked, when `blocked` is true.

    MessageDelivery:
      type: object
      title: Delivery receipt
      description: |
        The carrier's receipt. **Absent means the carrier has not reported yet** —
        normal for a message sent seconds ago, and permanent for an inbound one.
        Absent is NOT "failed"; a client that treats it that way shows a false
        failure on every fresh send.
      properties:
        status:
          type: string
          description: The carrier's own word for the outcome, passed through unmapped so the detail that makes a failure diagnosable survives.
        error:
          type: string
          description: The carrier's failure detail. Empty on success.
        at:
          type: string
          format: date-time
          description: When the carrier reported this status, RFC 3339 UTC.

    Thread:
      type: object
      title: Thread
      description: One conversation's messages.
      required: [line, number, messages]
      properties:
        line:
          type: string
          description: Your account number the thread is on, normalized.
        number:
          type: string
          description: The other party's number, normalized.
        messages:
          type: array
          description: The thread's messages, oldest first.
          items: { $ref: "#/components/schemas/Message" }
        markedRead:
          type: boolean
          description: Whether this request also marked the messages read. Only ever true when you passed `markRead=true`.

    UnreadSummary:
      type: object
      title: Unread summary
      required: [total, lines]
      properties:
        total:
          type: integer
          description: The sum across every line reported, so one badge cannot disagree with the per-line numbers.
        lines:
          type: array
          description: The per-line breakdown — one entry per line you can see.
          items:
            type: object
            required: [line, count]
            properties:
              line:
                type: string
                description: The account number (the line) these counts are for.
              count:
                type: integer
                description: How many messages you have not read on this line.

    BlockedSender:
      type: object
      title: Blocked sender
      description: |
        One number blocked from texting a line. **Not** the STOP list — see
        `GET /sms/lines/{line}/blocked`.
      required: [line, number]
      properties:
        line:
          type: string
          description: Your account number (the line) the sender is blocked on.
        number:
          type: string
          description: The blocked sender's phone number.
        reason:
          type: string
          description: Free text for your own records. Never shown to the blocked party.
        blockedAt:
          type: string
          format: date-time
          description: When the block was added, RFC 3339 UTC.

    ScheduledMessage:
      type: object
      title: Scheduled message
      required: [id, line, recipients, sendAt, price, currency]
      properties:
        id:
          type: integer
          format: int64
          description: The scheduled message's id — pass it to cancel this one before it sends.
        line:
          type: string
          description: The number it will be sent from (one of your account's numbers).
        recipients:
          type: array
          description: The numbers it will be sent to.
          items: { type: string }
        subject:
          type: string
          description: The MMS subject line, if one was set.
        text:
          type: string
          description: The message body.
        media:
          type: array
          description: Attachment URLs to send with it, if any — attachments make it an MMS.
          items: { type: string }
        sendAt:
          type: string
          format: date-time
          description: When it is scheduled to go out, RFC 3339 UTC.
        price:
          type: number
          format: double
          description: |
            What it will cost, **fixed at the moment it was scheduled**. A later
            rate-card change does not re-price a message you already committed
            to; the charge lands when it goes out.
        currency:
          type: string
          enum: [USD]
          description: The currency of `price` — always `USD`.

    Template:
      type: object
      title: Saved reply
      required: [id, title, body]
      properties:
        id:
          type: integer
          format: int64
          description: The saved reply's id.
        title:
          type: string
          description: The saved reply's name, for your own reference.
        body:
          type: string
          description: The message text.

    Draft:
      type: object
      title: Draft
      required: [draftId, message]
      properties:
        draftId:
          type: string
          description: The key YOU chose, not one this API minted.
        message:
          type: string
          description: The saved draft text.

    MarkReadInput:
      type: object
      title: Mark read input
      required: [messageIds]
      properties:
        messageIds:
          type: array
          maxItems: 50
          description: The messages to mark. At most 50 per request.
          items: { type: integer, format: int64 }
        read:
          type: boolean
          default: true
          description: "`true` marks read, `false` marks unread. Defaults to true."

    MarkLineReadInput:
      type: object
      title: Mark line read input
      properties:
        since:
          type: string
          format: date-time
          description: Only mark messages received after this time. Leave it out to mark every message.

    AssignInput:
      type: object
      title: Assign input
      properties:
        userId:
          type: integer
          format: int64
          nullable: true
          description: |
            The user to hand the thread to, matching `id` in `GET /users`. **Null
            or absent unassigns it.** A user who is not on your account is a
            `400`.

    BlockInput:
      type: object
      title: Block input
      required: [number]
      properties:
        number:
          type: string
          description: The sender to block, in digits.
        reason:
          type: string
          description: Free text for your own records.

    ScheduleInput:
      type: object
      title: Schedule input
      required: [to, sendAt]
      properties:
        to:
          type: array
          minItems: 1
          description: The numbers to send to. At least one — two or more makes it a group MMS.
          items: { type: string }
        message:
          type: string
          description: Required unless `media` is set.
        subject:
          type: string
          description: An optional title shown above the message, like an email's subject line. Only picture/group messages (MMS) carry it; a plain SMS ignores it.
        media:
          type: array
          description: |
            Hosted URLs, not inline file content — a scheduled MMS references
            files that already exist rather than carrying megabytes that must be
            stored until the send time.
          items: { type: string }
        sendAt:
          type: string
          format: date-time
          description: When to send it, RFC 3339. Must be in the future — a past time is almost always a timezone bug in the caller, so it is rejected rather than sent immediately.

    TemplateInput:
      type: object
      title: Template input
      required: [title, body]
      properties:
        title:
          type: string
          minLength: 1
          description: The saved reply's name, for your own reference.
        body:
          type: string
          minLength: 1
          description: The message text.

    DraftInput:
      type: object
      title: Draft input
      required: [message]
      properties:
        message:
          type: string
          description: The unsent text. An empty string is legal — it stores "the user cleared the box" without deleting the draft.

    User:
      type: object
      title: User
      description: One user of the company.
      required: [id, username, firstName, lastName, title, email, mobile, company, timeZone, extension, extensions, lines, numbers, voicemails]
      properties:
        id:
          type: integer
          format: int64
          description: |
            The user's id on the phone system. This is the value every other
            endpoint means by a user id — the entries in `SMSLine.userIds` are
            these ids.
        username:
          type: string
          description: The login this person signs in with. Empty for a user created without portal access.
        firstName:
          type: string
          description: The user's first name.
        lastName:
          type: string
          description: The user's last name.
        title:
          type: string
          description: Job title as entered in the portal. Free text.
        email:
          type: string
          description: The user's email address. May be blank.
        mobile:
          type: string
          description: |
            The personal/cell number on the user's profile — **not** a number on
            the account. May be blank.
        company:
          type: string
          description: |
            The per-user company override, falling back to the account's own
            name — so it is always populated and always a name a caller would
            recognize.
        timeZone:
          type: string
          description: |
            The user's IANA zone. Every timestamp on this surface is UTC; this
            is what turns one into the wall-clock time this person saw.
          example: America/New_York
        extension:
          type: string
          description: |
            The **dial-by-name** extension — the digits the auto-attendant
            matches for this person. Not necessarily a phone extension they can
            be reached on; see `extensions`.
        extensions:
          type: array
          description: The PBX extensions assigned to this user — what a colleague dials internally.
          items: { type: string }
        lines:
          type: array
          description: The SIP lines (devices/registrations) the user owns.
          items: { type: string }
        numbers:
          type: array
          description: The account DIDs owned by this user. A number with no owner appears on nobody.
          items: { type: string }
        voicemails:
          type: array
          description: The mailbox names the user owns.
          items: { type: string }

    CallSearchInput:
      type: object
      title: Call search
      required: [start, end]
      properties:
        start:
          type: integer
          format: int64
          description: Start of the window, **unix seconds**. Required.
          example: 1754006400
        end:
          type: integer
          format: int64
          description: |
            End of the window, unix seconds. Required, must be after `start`, and
            at most **366 days** later.
          example: 1754092800
        timeZone:
          type: string
          description: |
            IANA zone, e.g. `America/New_York`. Decides where a day boundary
            falls for the day-of-week and day-of-month filters. **Defaults to
            UTC, which shifts every daily figure** — send it.
          example: America/New_York
        limit:
          type: integer
          description: Page size. Defaults to 50, capped at 500.
          default: 50
          maximum: 500
        offset:
          type: integer
          description: Rows to skip.
          default: 0
        direction:
          type: string
          enum: [inbound, outbound]
          description: Omit for both.
        filters: { $ref: "#/components/schemas/CallFilters" }
        sort: { $ref: "#/components/schemas/CallSort" }

    CallFilters:
      type: object
      title: Call filters
      description: Every field is optional. Excludes are applied after includes.
      properties:
        numbers:
          type: array
          items: { type: string }
          description: Match these account numbers.
        numbersExclude:
          type: array
          description: Exclude these account numbers.
          items: { type: string }
        extensions:
          type: array
          description: Match these extensions.
          items: { type: string }
        extensionsExclude:
          type: array
          description: Exclude these extensions.
          items: { type: string }
        queues:
          type: array
          description: Match calls that went through these queues.
          items: { type: string }
        queuesExclude:
          type: array
          description: Exclude calls that went through these queues.
          items: { type: string }
        huntgroups:
          type: array
          description: Match calls that went through these hunt groups.
          items: { type: string }
        huntgroupsExclude:
          type: array
          description: Exclude calls that went through these hunt groups.
          items: { type: string }
        users:
          type: array
          description: Match calls involving these users, by user id.
          items: { type: string }
        directions:
          type: array
          description: Match these call directions.
          items: { type: string, enum: [inbound, outbound] }
        statuses:
          type: array
          items: { type: string, enum: [answered, missed, voicemail] }
          description: The words, not the numeric codes.
        search:
          type: string
          description: Matches caller and called names and numbers.
        duration: { $ref: "#/components/schemas/CallRange" }
        talkTime: { $ref: "#/components/schemas/CallRange" }
        waitTime: { $ref: "#/components/schemas/CallRange" }
        timeOfDay: { $ref: "#/components/schemas/CallRange" }
        callPurpose:
          type: array
          items: { type: string }
          description: |
            **Per-account vocabulary**, not a fixed enum. A value your account
            does not use matches nothing — that is not an error, and not a typo
            we can catch for you.
        callSentiment:
          type: array
          items: { type: string }
          description: Per-account vocabulary, as `callPurpose`.

    CallRange:
      type: object
      title: Range
      description: |
        Either end may be omitted for an open bound. Durations are **seconds**;
        `timeOfDay` takes `HH:MM`.
      properties:
        start:
          type: string
          description: The low end of the range. Omit for an open bound.
        end:
          type: string
          description: The high end of the range. Omit for an open bound.

    CallSort:
      type: object
      title: Sort
      description: How to order the results.
      properties:
        field:
          type: string
          description: A response field name, e.g. `startTime`.
          example: startTime
        direction:
          type: string
          enum: [asc, desc]
          default: desc
          description: Sort order. Defaults to `desc`.

    CallPage:
      type: object
      title: Call page
      required: [calls, total, limit, offset]
      properties:
        calls:
          type: array
          description: The calls on this page.
          items: { $ref: "#/components/schemas/Call" }
        total:
          type: integer
          format: int64
          description: |
            How many calls match the filter across **all** pages — what a
            "1–50 of 812" control needs. Not the size of this page.
        limit:
          type: integer
          description: |
            The page size actually applied, after defaulting and capping. Send
            `limit: 10000` and this comes back `500`, so a short page is
            explained rather than mysterious.
        offset:
          type: integer
          description: How many matching calls were skipped before this page — the `offset` you sent, echoed back.

    Call:
      type: object
      title: Call
      required: [id, direction, status, statusCode, startTime, durationSeconds, talkTimeSeconds]
      properties:
        id:
          type: string
          description: |
            The call id — the same value in call webhooks and the recordings
            endpoints. **Keep it a string:** it looks like a decimal number and
            is not one, and parsing it as a float destroys the low digits.
          example: "1754489201.884213"
        direction:
          type: string
          enum: [inbound, outbound]
          description: Whether the call came in (`inbound`) or went out (`outbound`).
        status:
          type: string
          enum: [answered, missed, voicemail, unknown]
          description: The word rather than the switch's integer.
        statusCode:
          type: integer
          format: int64
          description: |
            The raw code, because `status` flattens a distinction some clients
            need: `-1` missed, `0` voicemail, `1` answered, and **anything above
            1 means answered by that many people** — a call that rang a group and
            was picked up after a transfer. All of those report `answered`.
        callerType:
          type: string
          description: |
            `external`, `user`, `queue`, `huntgroup`. **Read this before assuming
            a number field holds a phone number** — on an internal leg it is an
            extension.
        callerName:
          type: string
          description: The caller's name, when known.
        callerNumber:
          type: string
          description: The caller's number. On an internal leg this is an extension — check `callerType` first.
        calledType:
          type: string
          description: What was called — `external`, `user`, `queue`, or `huntgroup`, same vocabulary as `callerType`.
        calledName:
          type: string
          description: The called party's name, when known.
        calledNumber:
          type: string
          description: The called party's number. On an internal leg this is an extension — check `calledType` first.
        dialledNumber:
          type: string
          description: What was actually dialled — for an inbound call, your DID.
        callerIdInternal:
          type: string
          description: The caller ID shown on internal (on-switch) legs.
        callerIdExternal:
          type: string
          description: The caller ID shown on external (off-switch) legs.
        startTime:
          type: string
          format: date-time
          description: RFC 3339 UTC.
        endTime:
          type: string
          format: date-time
          description: Omitted for a call with no recorded end.
        durationSeconds:
          type: integer
          format: int64
          description: Includes ringing.
        talkTimeSeconds:
          type: integer
          format: int64
          description: |
            Connected time only. On a missed call this is `0` and
            `durationSeconds` is how long it rang.
        transferred:
          type: integer
          description: A **count**, not a boolean — a call can be transferred more than once.
        abandoned:
          type: boolean
          description: |
            The **caller** hung up before anyone answered. This is what separates
            "we missed it" from "they gave up" — reporting on missed calls
            without it blames agents for calls nobody could have taken.
        recorded:
          type: boolean
          description: |
            Audio was captured. Fetch it with `GET /calls/{callid}/recordings` —
            this stays `true` for a call whose recording was since deleted, so it
            means "was recorded", not "can be played".
        calledBack:
          type: string
          description: The id of the call that returned this one, when an abandoned call was called back.
        repeated:
          type: integer
          format: int64
          description: Earlier calls from the same caller within the window.

    CallDetail:
      allOf:
        - $ref: "#/components/schemas/Call"
        - type: object
          title: Call detail
          required: [legs]
          properties:
            legs:
              type: array
              description: |
                The per-leg breakdown, in the order the switch recorded them. A
                call that rang a queue, was answered and was transferred is one
                call and several legs.
              items: { $ref: "#/components/schemas/CallLeg" }

    CallLeg:
      type: object
      title: Call leg
      required: [uniqueId, callId, startTime, durationSeconds, talkTimeSeconds]
      properties:
        uniqueId:
          type: string
          description: Identifies this leg, and is what `GET /calls/{callid}/recordings/{uniqueid}` takes.
        callId:
          type: string
          description: The switch's id for **this leg**, which on a transferred call differs from the call id you asked for.
        bridgedFromCallId:
          type: string
          description: The leg this one was bridged from. **Chain on it to follow a transfer.**
        startTime: { type: string, format: date-time }
        endTime: { type: string, format: date-time }
        durationSeconds: { type: integer }
        talkTimeSeconds: { type: integer }
        fromType: { type: string }
        from:
          type: string
          description: On an internal leg this is an extension, not a phone number.
        fromName: { type: string }
        toType: { type: string }
        to: { type: string }
        hasRecording:
          type: boolean
          description: |
            Whether **playable** audio still exists for this leg — checked
            against the recording stores, not inferred from the CDR, which keeps
            its recording path after a deletion. Only populated for a credential
            allowed to hear recordings, so `false` means "no, or you may not
            know".

    CallTranscript:
      type: object
      title: Transcript
      required: [id, callId, segments]
      properties:
        id:
          type: integer
          format: int64
          description: The transcript's id.
        callId:
          type: string
          description: Shared by every transcript of the call.
        recording:
          type: string
          description: |
            The audio file this was transcribed from, and **the reliable way to
            tell which leg it is**: the name embeds the leg's `uniqueId` with the
            dot removed — `1785979165.372492` becomes
            `record_1785979165372492_93458.wav`. Without it the only option is
            pairing transcripts to legs by position and hoping the orders agree.
          example: record_1754489201884213_93458.wav
        segments:
          type: array
          description: The diarized utterances in time order. Empty when the audio produced no transcript.
          items: { $ref: "#/components/schemas/TranscriptSegment" }
        shortSummary:
          type: string
          description: Absent when summarization did not run, which is normal rather than an error.
        bulletPoints:
          type: array
          description: Key points from the call as short bullets. Absent when summarization did not run.
          items: { type: string }
        callPurpose:
          type: string
          description: Per-account vocabulary, not a fixed enum.
        callSentiment:
          type: string
          description: Per-account vocabulary, not a fixed enum.
        customerSatisfactionScore:
          type: integer
          description: |
            **Absent is not zero.** A missing score means the call was never
            analyzed; zero would mean it scored nothing. Averaging nulls as zeros
            is the most common way these numbers get misreported.
        customerSatisfactionScoreNote:
          type: string
          description: The model's reasoning behind `customerSatisfactionScore`, when it gave one.
        agentPerformanceScore:
          type: integer
          description: Absent when not scored — see `customerSatisfactionScore`.
        agentPerformanceScoreNote:
          type: string
          description: The model's reasoning behind `agentPerformanceScore`, when it gave one.
        actionRequired:
          type: boolean
          description: Whether the call flagged something that needs follow-up.
        actionRequiredNote:
          type: string
          description: What needs following up, when `actionRequired` is true.
        urgentActionRequired:
          type: boolean
          description: Whether that follow-up is urgent.
        urgentActionRequiredNote:
          type: string
          description: What is urgent, when `urgentActionRequired` is true.
        agentName:
          type: string
          description: The agent's name, as identified by the analysis.
        agentSpeaker:
          type: integer
          description: |
            Which diarized speaker is the agent. **Absent when the analysis could
            not tell them apart** — do not fall back to assuming speaker `0`.
        customKpis:
          type: array
          description: Your account's custom KPIs, scored for this call.
          items: { $ref: "#/components/schemas/TranscriptKPI" }

    TranscriptSegment:
      type: object
      title: Transcript segment
      required: [start, end, speaker, text]
      properties:
        start:
          type: number
          description: Seconds from the start of the audio. Fractional.
        end:
          type: number
          description: Seconds from the start of the audio. Fractional.
        speaker:
          type: integer
          description: |
            A **diarization index, not an identity**. `0` and `1` distinguish
            voices, and the mapping is not stable between calls. Use the
            transcript's `agentSpeaker` to tell which one is the agent.
        text:
          type: string
          description: What was said in this segment.

    TranscriptKPI:
      type: object
      title: KPI
      required: [name]
      properties:
        name:
          type: string
          description: The KPI as your account defined it — these are per-account.
        value:
          type: integer
          description: Absent means the KPI was not scored on this call, which is not the same as scoring zero.
        note:
          type: string
          description: The model's reasoning, when it gave one.

    Recording:
      type: object
      title: Recording
      description: One recorded leg of a call.
      required: [uniqueId, callId, url, startTime, durationSeconds, talkTimeSeconds, from, to]
      properties:
        uniqueId:
          type: string
          description: Identifies this leg. Pass it back to the per-leg endpoint to re-fetch just this one.
        callId:
          type: string
          description: |
            The switch's call id **for the leg**. On a transferred call it can
            differ from the id in the request path — the request id names the
            whole journey, this one names the leg.
        url:
          type: string
          format: uri
          description: |
            Plays the audio. A stable **signed** link on this platform, not the
            storage location:

            - Requires **no** `Authorization` header, so it can go straight into
              an `<audio>` element or a transcription service.
            - The account id is sealed inside the signature, so it cannot be
              edited to reach another account's recording.
            - **It does not expire. Treat it as a secret** — anyone holding it
              can play the conversation.
        startTime:
          type: string
          format: date-time
          description: When this leg started, RFC 3339 UTC.
        durationSeconds:
          type: integer
          description: The leg's full length **including ringing**.
        talkTimeSeconds:
          type: integer
          description: Only the connected portion — the closer match to the length of the audio.
        from:
          type: string
          description: The leg's originating endpoint. On an internal leg this is an extension, not a phone number.
        to:
          type: string
          description: The leg's destination endpoint. On an internal leg this is an extension.

    Fax:
      type: object
      title: Fax
      required: [direction, line, from, to, pages, status, createdAt]
      properties:
        id:
          type: integer
          format: int64
          description: |
            The fax id, for `GET /faxes/{id}`. Always present. A send records
            the fax before handing it over, so the id exists from the start.
          example: 7731455
        direction:
          type: string
          enum: [sent, received]
        line:
          type: string
          description: |
            Your fax number the fax went out on (`sent`) or came in to
            (`received`). Equal to `from` on a sent fax and to `to` on a
            received one.
          example: "12125550188"
        from:
          type: string
          description: |
            Who sent it. On a received fax this is the sender's number as the
            phone network reported it.
          example: "12125550188"
        to:
          type: string
          description: Who it was sent to.
          example: "13475550123"
        userId:
          type: integer
          format: int64
          description: |
            The user who sent it — `id` in `GET /users`. For a fax sent through
            this API, the user the credential acts as. **Absent on received
            faxes.**
          example: 481920
        pages:
          type: integer
          description: Page count, **including the cover page**.
          example: 4
        status:
          type: string
          enum: [pending, success, failed]
          description: |
            `pending` — queued or still sending. `success` — delivered.
            `failed` — not delivered; the reason is in `statusDetail`. A
            received fax is always `success`.
        statusCode:
          type: integer
          description: |
            Sent faxes only. The fax service's delivery code: `-1` pending, `0`
            delivered, **anything else a failure**. Branch on `status`; keep
            this for logs and support.
          example: 0
        statusDetail:
          type: string
          description: |
            Sent faxes only. The delivery result as text — `queued` while
            pending, `Success` once delivered, otherwise **the failure reason**
            (for example a busy line or no answer). Human-readable; do not
            parse it.
          example: Success
        createdAt:
          type: string
          format: date-time
          description: When the fax was sent or received. RFC 3339 UTC.
          example: "2026-10-28T16:20:03Z"

    FaxPage:
      type: object
      title: Fax page
      required: [faxes, limit, offset]
      properties:
        faxes:
          type: array
          description: Newest first.
          items: { $ref: "#/components/schemas/Fax" }
        total:
          type: integer
          format: int64
          description: |
            How many faxes match across **all** pages. Returned on the first
            page (`offset=0`) only — keep the value from there.
        limit:
          type: integer
          description: The page size applied.
        offset:
          type: integer

    SendFaxInput:
      type: object
      title: Send fax input
      required: [from, to]
      properties:
        from:
          type: string
          description: |
            One of your account's numbers **with fax enabled**, that the
            credential's user's role (and the key's number grants, if any)
            allows. US number: 10 digits, or 11 starting with `1`; formatting is
            stripped.
          example: "12125550188"
        to:
          type: string
          description: |
            The one recipient. US number: 10 digits, or 11 starting with `1`.
            There is no list form — one fax, one recipient.
          example: "13475550123"
        files:
          type: array
          description: |
            The documents, faxed in this order. Required unless you send a
            `cover` — a cover page alone is a valid fax.

            Each file at most **10 MB**, all files together at most **200 MB**
            (decoded sizes).
          items: { $ref: "#/components/schemas/FaxFileInput" }
        cover:
          $ref: "#/components/schemas/FaxCoverInput"

    FaxFileInput:
      type: object
      title: Fax file
      required: [data]
      properties:
        name:
          type: string
          description: |
            Your own label for the file. **Not used to decide its type** — that
            is read from the content.
          example: invoice-1042.pdf
        data:
          type: string
          format: byte
          description: |
            The file, standard base64. Accepted types, recognized from the
            content: PDF, PNG, TIFF, JPEG, GIF, DOC, DOCX, XLS, XLSX, PPT, PPTX.
            Anything else is a `400`. At most 10 MB decoded.
          example: JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK

    FaxCoverInput:
      type: object
      title: Cover page
      description: |
        Adds the standard cover page as the first page. Include the object
        (even empty, `{}`) to send a cover; omit it to send none.
      properties:
        template:
          type: string
          description: Leave this out. Only the standard cover page is supported; naming another template is a `400`.
        name:
          type: string
          maxLength: 200
          description: The recipient's name. One line.
          example: Dr. Rivera
        company:
          type: string
          maxLength: 200
          description: The recipient's company. One line.
          example: Midtown Clinic
        note:
          type: string
          maxLength: 2000
          description: A message on the cover page. Line breaks are kept.
          example: Signed referral attached.

    WebhookType:
      type: string
      title: Event type
      description: |
        The event a subscription fires on. Fetch the live list from
        `GET /webhooks/types`.
      enum:
        - AccountRealTimeCalls
        - AccountEndedCalls
        - UserEndedCalls
        - AccountSMS
        - AccountAITranscription

    Webhook:
      type: object
      title: Webhook subscription
      required: [id, name, description, url, type, enabled, createdAt, updatedAt]
      properties:
        id:
          type: integer
          format: int64
          description: The subscription's id.
        name:
          type: string
          description: A label for the subscription, for your own reference.
        description:
          type: string
          description: A longer note about the subscription, for your own reference.
        url:
          type: string
          format: uri
          description: Where events are delivered. `http` or `https`, max 1024 characters.
        type: { $ref: "#/components/schemas/WebhookType" }
        enabled:
          type: boolean
          description: Whether events are being delivered.
        createdAt:
          type: string
          format: date-time
          description: When the subscription was created, RFC 3339 UTC.
        updatedAt:
          type: string
          format: date-time
          description: When the subscription was last changed, RFC 3339 UTC.
      description: |
        There is no `customerId`: the credential already determines the account,
        so echoing it back would invite a client to think it can send a
        different one.

    WebhookCreateInput:
      type: object
      title: Create input
      required: [name, url, type]
      properties:
        name:
          type: string
          maxLength: 255
          description: Required, non-empty. Max 255 characters.
        description:
          type: string
          description: An optional longer note about the subscription, for your own reference.
        url:
          type: string
          format: uri
          maxLength: 1024
          description: Required. Must use `http` or `https` and include a host. Max 1024 characters.
        type: { $ref: "#/components/schemas/WebhookType" }
        enabled:
          type: boolean
          default: false
          description: Defaults to `false` so nothing fires at an endpoint that is not ready.

    WebhookUpdateInput:
      type: object
      title: Update input
      description: |
        A **merge** — omit a field to leave it unchanged. An explicit `""`
        clears `description`. A body with no updatable field is a `400`.
      properties:
        name:
          type: string
          maxLength: 255
          description: A new label for the subscription. Omit to leave unchanged.
        description:
          type: string
          description: A new note for the subscription. Send `""` to clear it; omit to leave unchanged.
        url:
          type: string
          format: uri
          maxLength: 1024
          description: A new delivery URL. `http` or `https`, max 1024 characters. Omit to leave unchanged.
        type: { $ref: "#/components/schemas/WebhookType" }
        enabled:
          type: boolean
          description: Turn delivery on or off. Omit to leave unchanged.

    PlaceCallInput:
      type: object
      title: Place call input
      required: [phone, to]
      properties:
        phone:
          type: string
          description: |
            The phone (line) that rings first, digits only. For an API key it
            must be one of the key's **phones**; for an OAuth token, one of
            the user's own phones.
          example: "6589455"
        to:
          type: string
          description: |
            The number or extension to connect the phone to. 10 digits get a
            leading `1`; a `+` or international number gets the `011` prefix.
            Spaces, dashes, dots and parentheses are ignored; letters are
            refused.
          example: "13475550123"
        callerId:
          type: string
          description: |
            What the called person sees. Omit (or `""`) for the phone's own
            caller ID; `default` for the account's main caller ID; `original`
            or `original_own_number` for the phone's own number; or one of the
            numbers on the user's TeleConsole caller ID list, among the role's
            numbers and the key's number grants. See the operation for the
            rules.
          example: "12125550188"

    PlacedCall:
      type: object
      title: Placed call
      required: [phone, to]
      properties:
        callId:
          type: string
          description: |
            The call's id, as call history and webhooks show it. Missing when
            the phone system did not name the call within a couple of seconds;
            the call was placed either way.
          example: "1761755203.884213"
        phone:
          type: string
          description: The phone that is ringing.
          example: "6589455"
        to:
          type: string
          description: "`to` as dialled, after normalization."
          example: "13475550123"
        callerId:
          type: string
          description: |
            The caller ID sent to the phone system. Missing means the phone's
            own. `default` is shown as the number it stands for.
          example: "12125550188"

    ErrorEnvelope:
      type: object
      title: Error
      required: [error]
      properties:
        error:
          type: object
          required: [type, message]
          properties:
            type:
              type: string
              description: |
                The stable, machine-readable classifier. **Branch on this.**
                New values may be added; an existing one is never repurposed.
              enum:
                - invalid_request
                - unauthenticated
                - insufficient_scope
                - permission_denied
                - not_found
                - conflict
                - unsupported
                - rate_limited
                - unavailable
                - internal_error
            message:
              type: string
              description: Human-readable, and **may change at any time**. Never parse it.
            scope:
              type: string
              description: |
                Set on `insufficient_scope` — exactly which capability to
                request at your next authorization.
            id:
              type: integer
              format: int64
              description: |
                Set when the failed request still left a record behind — on
                `POST /faxes`, the fax, listed as `failed`. Store it like a
                success's id; don't repeat the request blindly.
              example: 7731456

  responses:
    BadRequest:
      description: |
        `invalid_request` — a missing or malformed field, an unknown enum value,
        or an unknown field in the body. **Nothing was charged.**
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ErrorEnvelope" }
          examples:
            missingField:
              value:
                error:
                  type: invalid_request
                  message: "from is required: the account number to send from"
    Unauthenticated:
      description: |
        `unauthenticated` — no credential, or one that is invalid, revoked or
        expired. The `WWW-Authenticate` header names the scope the endpoint
        wanted.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ErrorEnvelope" }
          examples:
            missing:
              value:
                error:
                  type: unauthenticated
                  message: 'authentication required: send an OAuth access token or an API key as "Authorization: Bearer …"'
    Forbidden:
      description: |
        Two different failures share this status; the `type` field tells them
        apart — `insufficient_scope` (the credential lacks the scope) or
        `permission_denied` (the scope is fine, but the user's role lacks the
        permission).

        - `insufficient_scope` — the credential is valid but lacks the scope.
          The `scope` field names what to request. **Fix: re-authorize.**
        - `permission_denied` — the scope is fine, but the person behind the
          credential lacks the role permission. **Fix: change their role in the
          admin center.**
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ErrorEnvelope" }
          examples:
            scope:
              summary: Missing scope — fix in your code
              value:
                error:
                  type: insufficient_scope
                  message: credential is not authorized for sms:send
                  scope: sms:send
            role:
              summary: Missing role permission — fix in the portal
              value:
                error:
                  type: permission_denied
                  message: the user who authorized this application does not have access to call recordings
    Unpriced:
      description: |
        `invalid_request` — **no active rate applies to one of the destinations.**
        This API will not send a message it cannot price.

        Not a malformed request, and **retrying will never succeed**: the
        destination is not on the account's rate card, which only support can
        change. Nothing was sent and nothing was charged.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ErrorEnvelope" }
          examples:
            default:
              value:
                error:
                  type: invalid_request
                  message: destination is not priced
    NotFound:
      description: |
        `not_found` — no such object, or it is not this account's. The two are
        deliberately indistinguishable.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ErrorEnvelope" }
          examples:
            default:
              value: { error: { type: not_found, message: not found } }
    InternalError:
      description: |
        `internal_error` — something failed on our side, not with your request.
        Safe to retry.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ErrorEnvelope" }
          examples:
            default:
              value: { error: { type: internal_error, message: internal error } }
    InternalErrorSend:
      description: |
        `internal_error` — something failed on our side. **Nothing was charged**
        and no message went out, guaranteed — which is what makes a retry safe.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ErrorEnvelope" }
          examples:
            default:
              value: { error: { type: internal_error, message: internal error } }
