> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Calling Add-ons

> List and buy per-line calling add-ons — the FaceTime Audio add-on and the Registered caller ID add-on — for a phone line in your workspace.

> [!WARNING]
>
> **The Try it panel runs against production** with the key you paste. `POST` charges your card.

Every phone line includes calling: **500 outgoing minutes per line per month** (pooled across your
phone lines) with **call recording**, **unlimited incoming calls** forwarded to one number in the
same country as the eSIM, and extra minutes at **\$3 per 100**.

Regular calls go out through Telnyx using your line's number. The person you call may see
**"Potential spam"** unless they saved your number or tapped "Mark as known" — text them first.
Carriers grade each call with a STIR/SHAKEN attestation, and because Telnyx can't own the number your
line uses for iMessage, calls are attested **B** rather than **A**. This is industry-wide: every iMessage provider, Sendblue included, calls from an iMessage number with B — an **A** needs a carrier-owned number, and those can only do SMS, not iMessage. Two add-ons avoid that:

| `addon` | Price | What it does |
| - | - | - |
| `facetime_audio` | \$100/mo per line | Calls go over FaceTime Audio — no carrier spam label. Costs more because it needs different hardware than iMessage. |
| `caller_id_registration` | $50 setup + $50/mo per line + \$0.075 per call | A separate, fully-attested calling number registered with carriers (Branded Calling) that shows your business name on US-to-US calls to T-Mobile and Verizon mobiles. Calls come from that number, not your iMessage number. Carrier vetting can take a few business days. |

## List — `GET /api/lines/{id}/calling-addons`

**id** `string` *required*

The line's `_id`.

```json theme={null}
{
  "lineId": "6a091e74542d9e3d645925ae",
  "included": ["500 outgoing minutes per line per month, with call recording.", "…"],
  "addons": [
    { "key": "facetime_audio", "label": "FaceTime Audio add-on", "beta": false, "price": "$100/mo per line",
      "monthlyCents": 10000, "setupCents": 0, "perCallCents": 0, "status": "none", "paymentUrl": null },
    { "key": "caller_id_registration", "label": "Registered caller ID add-on", "beta": false,
      "price": "$50 setup + $50/mo + $0.075/call per line", "monthlyCents": 5000, "setupCents": 5000,
      "perCallCents": 7.5, "status": "active", "paymentUrl": null, "callingNumber": "+12125550199" }
  ]
}
```

`status` is one of `none`, `awaiting_payment` (pay `paymentUrl`), `pending_setup` (paid — we're
setting it up), `active`, or `canceled`.

## Buy — `POST /api/lines/{id}/calling-addons`

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/lines/6a091e74542d9e3d645925ae/calling-addons" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "addon": "facetime_audio", "acceptCharges": true }'
```

* `addon` — `facetime_audio` or `caller_id_registration`.
* `acceptCharges` — must be `true`: you agree to the setup fee plus today's prorated share of the
  monthly, then monthly. Non-refundable. Without it: `422`.

The card on file is charged immediately. Returns `201` with `status: "pending_setup"` once paid, or
`202` with `status: "awaiting_payment"` and a `paymentUrl` only when the card is declined or the bank
requires authentication (3-D Secure) — the customer confirms there, and the add-on starts once paid.
An unpaid `paymentUrl` lapses after about 23 hours; the add-on then goes back to `none` and can be
bought again. Buying an add-on the line already has returns `409`, and so does buying one while
another add-on payment on the workspace is still waiting (`"code": "PAYMENT_IN_PROGRESS"`) — pay or
let that one lapse first. Registered caller ID calls are billed at \$0.075 each, added to your next invoice.

## Removing an add-on

> [!WARNING]
>
> **Add-ons can't be removed after purchase.** Contact [support@tuco.ai](mailto:support@tuco.ai) to change them.
> `DELETE /api/lines/{id}/calling-addons` returns `403` with `"code": "ADDON_REMOVAL_SUPPORT_ONLY"`.

## Ordering add-ons with a new line

Send `callingAddons` and `acceptCallingAddonCharges: true` on
[Create Line Request](/api-reference/endpoint/create-line-request.md). Add-ons bought with your plan at
checkout attach to new lines automatically, with no second charge.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.