Skip to main content
GET
Calling Add-ons
The Try it panel runs against production with the key you paste. POST charges your card, unless it uses an add-on you already paid for at checkout.
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: Add-ons bought at checkout are already paid for. Checkout buys one per phone line in your plan. Each phone line ordered after that gets one automatically, and adding one to an existing line uses it first, with no new charge. See how many are left with Calling Add-on Slots, or in prepaidFree below.

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

string
required
The line’s _id.
status is one of none, awaiting_payment (pay paymentUrl), pending_setup (paid — we’re setting it up), active, or canceled. prepaidFree is how many of this add-on the workspace already paid for (at checkout) that no line uses yet. More than 0 means adding it to this line costs nothing today. It is 0 if billing can’t be read at that moment. Each add-on also carries points, the plain-English description shown in the dashboard. The response also has potentialSpam, the dashboard’s explanation of the “Potential spam” label. recordingDisclosure is the line’s free call recording notice setting (message: null = the default text). Turn it on or change the text with Update a Line. It isn’t an add-on and costs nothing. It doesn’t play on FaceTime Audio calls.

Add to a line — POST /api/lines/{id}/calling-addons

There are two ways to add an add-on to a line. Use one you already paid for at checkout. No charge, no consent needed:
Buy a new one. Charged to the card on file now:
  • addon — facetime_audio or caller_id_registration.
  • usePrepaidSlot — true to use an add-on already paid for at checkout. Never charges. If none is left (prepaidFree is 0), it returns 409 with "code": "PREPAID_SLOT_TAKEN" and nothing is charged.
  • acceptCharges — must be true to buy a new one: you agree to the setup fee plus today’s prorated share of the monthly, then monthly. Non-refundable. Without it, and with no add-on already paid for: 422.
An add-on you already paid for is always used first. While prepaidFree is more than 0, any POST for that add-on uses it and charges nothing, even if you sent acceptCharges: true. If another order took the last one a moment earlier, a request with acceptCharges: true (and no usePrepaidSlot) goes on to buy a new one. Any other request gets 409 PREPAID_SLOT_TAKEN and is not charged.
chargedCents is what this request charged (0 when a paid-for add-on was used), and usedPrepaidSlot is true when it used one. A new purchase charges the card on file immediately. It 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. Registered caller ID calls are billed at $0.075 each, added to your next invoice. Registered caller ID can’t go live until the workspace’s caller ID details are submitted.

Errors

Errors return { "error": "…", "code": "…" }.

Removing an add-on

Add-ons can’t be removed after purchase. Contact 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. Add-ons bought with your plan at checkout attach to new phone lines automatically, with no second charge, so leave those out of callingAddons. Calling Add-on Slots shows how many are left.