​

Phone lines

​

Endpoints

​

Credentials and permissions

​

Before the first purchase: identity verification

​

Pricing and payment

• R$ 33,90 per line per month for BRL workspaces, US$ 33.90 for USD workspaces. The price is frozen on each line at purchase: price and currency on the line are what every renewal of that line charges.
• The first month is charged in full at purchase — no proration.
• Each line has its own cycle, anchored on its purchase date. It renews on the same day of the following month; when that day does not exist, on the last day of the month, and the shorter day then sticks: bought on Jan 31 → renews Feb 28 (or 29) → Mar 28 → Apr 28. Dates are computed in UTC. currentPeriodEnd on the line is the next renewal.
• Payment comes from the prepaid wallet first, and whatever the credits do not cover is charged to your saved card. If the card step fails, the credits already taken are put back. Top the wallet up in the dashboard (card or PIX), or through the API with POST /v1/billing/checkout — wallet_topup (card only) or add_card to save a card.
• Lines are available on every plan, including Free, with no limit on how many a workspace holds. A single POST buys at most 10.
• Lines share the wallet with the WhatsApp product. The dashboard shows the statement grouped by product.

​

Line lifecycle

                 renewal fails                2 days unpaid              1 more day unpaid
   ACTIVE ─────────────────────▶ PAYMENT_PENDING ─────────────▶ SUSPENDED ───────────────▶ RETURNED
     ▲                                  │                            │                     (final)
     └──────────── a renewal charge succeeds (retried every 6 hours) ┘

   ACTIVE ── DELETE ──▶ ACTIVE + cancelAtPeriodEnd: true ── period ends ──▶ CANCELED (final)
   PAYMENT_PENDING / SUSPENDED ── DELETE ──▶ RETURNED (immediately, final)

• Renewal is attempted when currentPeriodEnd is reached. Billing runs once an hour, so the charge — and every transition below — happens within about an hour after its deadline.
• A failed renewal moves the line to PAYMENT_PENDING and is retried every 6 hours. Adding credits or a card is picked up at the next retry; the dashboard’s Pay for all button retries at once.
• 2 days after the failure the line is SUSPENDED; 1 day later it is RETURNED. From the first failed charge to losing the number: about 3 days.
• A late payment keeps the anniversary. When a renewal finally succeeds — even while SUSPENDED — the line goes back to ACTIVE and the new period runs from the original renewal date, not from the payment date.
• Each step sends a notice and a webhook event: phone_line.payment_failed (once per renewal, on its first failed attempt), phone_line.suspended and phone_line.returned. A successful renewal sends phone_line.renewed.

​

Cancelling

• ACTIVE — no refund. The line stays ACTIVE and usable (codes included) until currentPeriodEnd, with cancelAtPeriodEnd: true; it is not renewed and becomes CANCELED at the end of the period. Undoing a scheduled cancellation is dashboard-only.
• PAYMENT_PENDING / SUSPENDED — there is no paid period left, so the line is returned immediately (RETURNED).
• RETURNED / CANCELED — 409 NOT_CANCELABLE.

​

The activation-code flow

​

Idempotency

​

Limits

• 1 to 10 numbers per purchase request, with no duplicates. No limit on lines per workspace.
• One waiting code request per line.
• Code history: limit 1–100 per call (default 20).
• Calls that reach our carrier — searching, buying, requesting a code, cancelling an unpaid line — draw on a request budget that is shared by the whole platform. When it runs out they answer 503 SUPPLIER_UNAVAILABLE (“Try again in a few minutes”), or the per-number SUPPLIER_UNAVAILABLE inside a purchase. Search once per area code and reuse the result instead of polling it.
• There is no other rate limit specific to these endpoints.

​

Errors

{
  "error": "Line not found. | Linha não encontrada.",
  "code": "LINE_NOT_FOUND"
}

​

Per-number results of a purchase

​

Dashboard-only

• Identity verification (document upload and contact code).
• Listening to the call recording of a code request.
• Undoing a scheduled cancellation.
• Pay for all and Choose which lines to keep for unpaid lines.
• The wallet statement grouped by product.
• Creating and managing phone-line webhooks and reading their delivery log.