Phone Lines

Buy phone lines

⚠️ Real side effect: this call charges money — it is NOT a simulation, including from the playground. Each number costs the full monthly price (R $33,90 for BRL workspaces, US$ 33.90 for USD), taken from your wallet credits first and then from your saved card, and becomes a line of your workspace, ACTIVE and paid for its first month. There is no proration and no checkout link: with no credits and no saved card the item fails with PAYMENT_FAILED.

Buys 1 to 10 numbers taken from GET /v1/phone-lines/available. The numbers are independent: each one is charged and acquired on its own, in the order sent, and one that fails does not undo the others. So the request answers 200 when it was processed, with one result per number — a 200 does not mean you bought anything; always read results[i].ok. A failed item carries code and a bilingual error, but no HTTP status of its own:

Item `code`	What happened	Charged?
`REQUEST_ALREADY_PROCESSED`	This `Idempotency-Key` was already used for this number within the last hour — whatever that attempt’s outcome was.	Not by this request.
`NUMBER_UNAVAILABLE`	Already held by a line (any workspace, yours included), being bought in another request right now, or the carrier no longer has it.	No — or refunded to the wallet.
`PAYMENT_FAILED`	Credits plus saved card did not cover the price, or the card charge did not go through.	No — credits taken were put back.
`PAYMENT_PROVIDER_ERROR`	The card processor did not answer. The card may have been charged.	Wallet: no. Card: check your statement.
`PURCHASE_NOT_COMPLETED`	Charged and acquired, but the line could not be recorded.	Refunded to the wallet.
`SUPPLIER_UNAVAILABLE`	The carrier failed while acquiring the number.	Refunded to the wallet.

A refund after a charge always goes to the wallet, including any part paid by card.

Anything other than 200 means no number was attempted, with one exception: a 500 (or a timeout) can come after earlier numbers were already charged and bought — retry the same request with the same Idempotency-Key, then list your lines with GET /v1/phone-lines.

Idempotency (required header). The key is tracked per number, for one hour: the same key with the same number charges nothing and answers ok: false, REQUEST_ALREADY_PROCESSED — whether the first attempt bought the number or failed (a replay does not return the original result). To retry a failed number, use a new key. A request refused as a whole (400/403) records nothing, so it can be resent with the same key. The key is scoped to your workspace. If the idempotency cache is unavailable the protection is skipped rather than blocking purchases.

Identity verification first. The account holder must be verified (through /v1/phone-lines/verification or the dashboard): never started or unfinished → 403 VERIFICATION_REQUIRED; rejected → 403 VERIFICATION_REJECTED; under manual review → proceeds, but lines bought during the review are returned and refunded to the wallet if it is rejected.

Permissions: with an OAuth / MCP token, only the workspace Owner may buy (phone_lines:purchase) — 403 PERMISSION_DENIED otherwise.

Every /v1/phone-lines endpoint takes a tenant-scoped key only: a line belongs to the workspace, not to a WhatsApp number, so a number-scoped key (or a per-number OAuth grant) gets 403 NUMBER_SCOPE_NOT_ALLOWED before any role is looked at. A 403 PERMISSION_DENIED / WORKSPACE_MEMBERSHIP_REQUIRED is sent with Cache-Control: no-store.

Requires a tenant-scoped key.

POST

phone-lines

Buy phone lines

curl --request POST \
  --url https://pilotstatus.com.br/v1/phone-lines \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "numbers": [
    "551148637200",
    "551148637201"
  ]
}
'

import requests

url = "https://pilotstatus.com.br/v1/phone-lines"

payload = { "numbers": ["551148637200", "551148637201"] }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({numbers: ['551148637200', '551148637201']})
};

fetch('https://pilotstatus.com.br/v1/phone-lines', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://pilotstatus.com.br/v1/phone-lines",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'numbers' => [
        '551148637200',
        '551148637201'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://pilotstatus.com.br/v1/phone-lines"

	payload := strings.NewReader("{\n  \"numbers\": [\n    \"551148637200\",\n    \"551148637201\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://pilotstatus.com.br/v1/phone-lines")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"numbers\": [\n    \"551148637200\",\n    \"551148637201\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://pilotstatus.com.br/v1/phone-lines")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"numbers\": [\n    \"551148637200\",\n    \"551148637201\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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."
    }
  ]
}

This is a real purchase. Each number costs the full monthly price, taken from your wallet credits first and then from your saved card. Use a new Idempotency-Key for each purchase, and repeat a key only to retry that same purchase. See Buy phone lines.

Authorizations

x-api-key

string

header

required

Your ps_ API key

Headers

Idempotency-Key

string

required

Required. Any string up to 255 characters with no control characters — a UUID per purchase is the usual choice. Tracked per number for one hour, scoped to your workspace: a retry with the same key never charges twice for the same number (the item answers REQUEST_ALREADY_PROCESSED). Missing, empty or whitespace-only → 400 IDEMPOTENCY_KEY_REQUIRED; too long or with a control character (tab included) → 400 IDEMPOTENCY_KEY_INVALID. It is a header, never a body field.

Required string length: 1 - 255

Body

application/json

numbers

string[]

required

1 to 10 distinct numbers, each exactly as GET /v1/phone-lines/available returned it in number: E.164 digits without + — 55, a two-digit area code starting 1–9, then 8 digits (551148637200). Numbers from different area codes can go in the same request. numbers is the only accepted field: anything else is refused with 400 UNKNOWN_FIELDS (the dashboard's requestId does not exist here).

Required array length: 1 - 10 elements

Pattern: ^55[1-9][0-9][0-9]{8}$

Example:

["551148637200", "551148637201"]

Response

Processed: one result per number, in the order sent. Read results[i].ok — every item may have failed.

results

object[]

One entry per number, in the order sent.

Show child attributes

Buy phone lines

curl --request POST \
  --url https://pilotstatus.com.br/v1/phone-lines \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "numbers": [
    "551148637200",
    "551148637201"
  ]
}
'

import requests

url = "https://pilotstatus.com.br/v1/phone-lines"

payload = { "numbers": ["551148637200", "551148637201"] }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({numbers: ['551148637200', '551148637201']})
};

fetch('https://pilotstatus.com.br/v1/phone-lines', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://pilotstatus.com.br/v1/phone-lines",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'numbers' => [
        '551148637200',
        '551148637201'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://pilotstatus.com.br/v1/phone-lines"

	payload := strings.NewReader("{\n  \"numbers\": [\n    \"551148637200\",\n    \"551148637201\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://pilotstatus.com.br/v1/phone-lines")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"numbers\": [\n    \"551148637200\",\n    \"551148637201\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://pilotstatus.com.br/v1/phone-lines")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"numbers\": [\n    \"551148637200\",\n    \"551148637201\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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."
    }
  ]
}

Endpoints

Workspace

Buy phone lines

Authorizations

Headers

Body

Response