​

Buy phone lines

​

Endpoint

​

Headers

​

Request body

​

Example

curl -X POST "https://pilotstatus.com.br/v1/phone-lines" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -H "Idempotency-Key: 6f1c2a0e-7b1d-4c2e-9a5f-3d8e1b2c4a70" \
  -d '{ "numbers": ["551148637200", "551148637201"] }'

{
  "results": [
    {
      "number": "551148637200",
      "ok": true,
      "lineId": "cmg5k2l1n0001pl8example9x"
    },
    {
      "number": "551148637201",
      "ok": false,
      "code": "PAYMENT_FAILED",
      "error": "The payment did not go through. Add balance or check your card. | O pagamento não foi concluído. Adicione saldo ou confira seu cartão."
    }
  ]
}

​

Response: 200 with one result per number

​

Order of operations, per number

1. Reserve the number under your Idempotency-Key (see below). Already reserved → REQUEST_ALREADY_PROCESSED.
2. Check that no line holds it — in any workspace, yours included — and that no other purchase of it is in flight → otherwise NUMBER_UNAVAILABLE, nothing charged.
3. Charge the full monthly price: wallet credits first, the remainder on the saved card. If the card step fails, the credits already taken are put back → PAYMENT_FAILED.
4. Acquire the number at the carrier. If that fails, the full price is refunded to your wallet — including any part that was paid by card — → NUMBER_UNAVAILABLE or SUPPLIER_UNAVAILABLE.
5. Create the line: status: "ACTIVE", currentPeriodEnd one month ahead, and the phone_line.purchased webhook event.

​

Whole-request errors

{
  "error": "Not a number from GET /v1/phone-lines/available: +551148637201, 11948637202. Use E.164 digits without \"+\", e.g. 551148637200. | Não é um número de GET /v1/phone-lines/available: +551148637201, 11948637202. Use os dígitos E.164 sem \"+\", ex.: 551148637200.",
  "code": "INVALID_NUMBERS",
  "details": { "invalidNumbers": ["+551148637201", "11948637202"] }
}

​

Idempotency

• The key is tracked per number, for one hour. Before anything else, each number is recorded under (your workspace, the key, the number). For the next hour, sending the same key again with that number charges nothing and buys nothing: the item answers ok: false, REQUEST_ALREADY_PROCESSED.
• A replay does not return the original result. REQUEST_ALREADY_PROCESSED comes back whether the first attempt bought the number or failed. To know which, call GET /v1/phone-lines: a number that was bought is in your list.
• A number that failed is locked under that key for the hour. After a PAYMENT_FAILED you top up and retry — with a new key, or the retry answers REQUEST_ALREADY_PROCESSED.
• After the hour the key is forgotten. A number you bought then answers NUMBER_UNAVAILABLE (it is yours — there is no second charge); a number that had failed is attempted again. To retry a failed number, always use a new key.
• Only the numbers are protected, not the request. Sending the same key with a different number buys that number.
• A request refused as a whole records nothing. After any 400 or 403 above, fix the request and resend it with the same key.
• Concurrent duplicates. If two deliveries of the same request are in flight together, each number proceeds in one of them; the other gets REQUEST_ALREADY_PROCESSED for it.
• Scoped to your workspace. The same key sent by another workspace never collides with yours.

​

Recommended retry pattern

​

After the purchase

• The line is ACTIVE until currentPeriodEnd — one month after the purchase — and then renews monthly. See the line lifecycle.
• Request the WhatsApp activation code with POST /v1/phone-lines/{id}/activations.