Phone Lines

Submit holder verification

⚠️ This call is real: it submits the workspace’s identity verification and sends real verification codes to contactEmail (always) and to contactWhatsapp (whenever WhatsApp codes are being sent — contact.requiredChannels says which). Use real data of the account holder only.

Starts the verification and hands it the document, in one call. We check the number (check digits; a CNPJ must also be found and active in the public registry), freeze the required contact channels, send the codes, store the file privately and read the number printed on it. Answers 201 with the state in PENDING_CONTACT; then confirm each code with POST /v1/phone-lines/verification/contact/{channel}/confirm. The request returns once the document has been read — usually within seconds, up to about a minute.

The body is JSON (Content-Type: application/json), not multipart: the file goes in document as a base64 data URI. Any other field is refused with 400 UNKNOWN_FIELDS. The file is checked before anything starts: a wrong type or size sends no code and creates nothing.

Submitting again. While the verification is still PENDING_CONTACT, a new submit replaces it (to fix a typo): the codes already sent stop working and new ones go out. Once it moved on, a submit answers 409 VERIFICATION_WRONG_STATE (IN_REVIEW or APPROVED — you can already buy — or NEEDS_DOCUMENT — send the document to POST /v1/phone-lines/verification/document instead) or 403 VERIFICATION_REJECTED.

Idempotency (Idempotency-Key is REQUIRED), for 24 hours: same key + same request, first one finished → 200 (not 201) with the workspace’s current state and Idempotent-Replayed: true, nothing sent again; same key while the first is still running → 409 IDEMPOTENCY_KEY_IN_USE; same key, different request (any field, the file included) → 409 IDEMPOTENCY_KEY_REUSED; a request refused as a whole frees the key. Limit: 10 submissions per hour per workspace, this endpoint and …/verification/document together → 429 RATE_LIMITED. Requires a tenant-scoped key, like every /v1/phone-lines endpoint (a number-scoped key gets 403 NUMBER_SCOPE_NOT_ALLOWED). Permission phone_lines:purchase, the same as buying: with an OAuth/MCP token only the workspace OWNER may call it (403 PERMISSION_DENIED otherwise). It is the same verification as the dashboard’s (Phone lines → Buy phone lines): whichever you use, the other sees the result. The response is the verification state object, sent with Cache-Control: no-store; the document number and the contacts come back masked.

POST

phone-lines

verification

Submit holder verification

curl --request POST \
  --url https://pilotstatus.com.br/v1/phone-lines/verification \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "documentType": "CNPJ",
  "documentNumber": "11.222.333/0001-81",
  "contactEmail": "ana@example.com",
  "contactWhatsapp": "+55 11 90000-0000",
  "document": "data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg=="
}
'

import requests

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

payload = {
    "documentType": "CNPJ",
    "documentNumber": "11.222.333/0001-81",
    "contactEmail": "ana@example.com",
    "contactWhatsapp": "+55 11 90000-0000",
    "document": "data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg=="
}
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({
    documentType: 'CNPJ',
    documentNumber: '11.222.333/0001-81',
    contactEmail: 'ana@example.com',
    contactWhatsapp: '+55 11 90000-0000',
    document: 'data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg=='
  })
};

fetch('https://pilotstatus.com.br/v1/phone-lines/verification', 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/verification",
  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([
    'documentType' => 'CNPJ',
    'documentNumber' => '11.222.333/0001-81',
    'contactEmail' => 'ana@example.com',
    'contactWhatsapp' => '+55 11 90000-0000',
    'document' => 'data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg=='
  ]),
  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/verification"

	payload := strings.NewReader("{\n  \"documentType\": \"CNPJ\",\n  \"documentNumber\": \"11.222.333/0001-81\",\n  \"contactEmail\": \"ana@example.com\",\n  \"contactWhatsapp\": \"+55 11 90000-0000\",\n  \"document\": \"data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg==\"\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/verification")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"documentType\": \"CNPJ\",\n  \"documentNumber\": \"11.222.333/0001-81\",\n  \"contactEmail\": \"ana@example.com\",\n  \"contactWhatsapp\": \"+55 11 90000-0000\",\n  \"document\": \"data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg==\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"documentType\": \"CNPJ\",\n  \"documentNumber\": \"11.222.333/0001-81\",\n  \"contactEmail\": \"ana@example.com\",\n  \"contactWhatsapp\": \"+55 11 90000-0000\",\n  \"document\": \"data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg==\"\n}"

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

{
  "status": "PENDING_CONTACT",
  "canPurchase": false,
  "verification": {
    "id": "cmg5k0v3r0000vf8example7k",
    "documentType": "CNPJ",
    "documentNumber": "**.***.333/0001-**",
    "legalName": "ACME LTDA",
    "contact": {
      "email": "a***@example.com",
      "whatsapp": "+5511****0000",
      "requiredChannels": [
        "WHATSAPP",
        "EMAIL"
      ],
      "confirmedChannels": [
        "WHATSAPP"
      ],
      "pendingChannels": [
        "EMAIL"
      ]
    },
    "document": {
      "status": "RECEIVED"
    },
    "reviewReason": null,
    "reviewNote": null,
    "createdAt": "2026-10-01T13:55:02.000Z",
    "updatedAt": "2026-10-01T13:56:40.000Z"
  }
}

This submits your workspace’s real identity verification. Send only the account holder’s true data and document.

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 submission. Missing or blank → 400 IDEMPOTENCY_KEY_REQUIRED; longer, or with a control character → 400 IDEMPOTENCY_KEY_INVALID. Remembered for 24 hours per workspace: the same key sent by two workspaces never collides.

Maximum string length: 255

Body

application/json

documentType

enum<string>

required

"CNPJ" or "CPF".

Available options:

CNPJ,

CPF

Example:

"CNPJ"

documentNumber

string

required

The CNPJ or CPF, with or without punctuation (11.222.333/0001-81 or 11222333000181). Alphanumeric CNPJs are accepted.

Example:

"11.222.333/0001-81"

contactEmail

string<email>

required

The account holder's contact e-mail, up to 254 characters. It always receives a code.

Maximum string length: 254

Example:

"ana@example.com"

contactWhatsapp

string

required

The account holder's WhatsApp number in international format — country code, area code and number, e.g. +55 11 90000-0000; punctuation is ignored. It receives a code when WHATSAPP is required.

Example:

"+55 11 90000-0000"

document

string

required

The document file as a base64 data URI: data:<type>;base64,<content>, encoded without line breaks. Types: application/pdf, image/jpeg, image/png, image/webp; at most 10 MB of file (about 14 MB once encoded). For a CNPJ: the CNPJ card (Cartão CNPJ), the articles of incorporation or the registration proof. For a CPF: an ID card (RG), a driver license (CNH) or the CPF registration proof, with the number readable.

Example:

"data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg=="

Response

Idempotent replay: the same Idempotency-Key and the same request already finished. The workspace's current state; nothing was started or sent again.

status

enum<string>

NONE (never started), PENDING_CONTACT (waiting for the contact codes and, if document.status says so, a better document), IN_REVIEW (finished, waiting for a person — purchase allowed), APPROVED (verified — purchase allowed), NEEDS_DOCUMENT (the reviewer asked for another document) or REJECTED (final — talk to support). The phone_line.verification_updated webhook uses the same values for the last four.

Available options:

NONE,

PENDING_CONTACT,

IN_REVIEW,

APPROVED,

NEEDS_DOCUMENT,

REJECTED

canPurchase

boolean

Whether POST /v1/phone-lines is allowed now: true for APPROVED and IN_REVIEW.

verification

object | null

null for NONE.

Show child attributes

Submit holder verification

curl --request POST \
  --url https://pilotstatus.com.br/v1/phone-lines/verification \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "documentType": "CNPJ",
  "documentNumber": "11.222.333/0001-81",
  "contactEmail": "ana@example.com",
  "contactWhatsapp": "+55 11 90000-0000",
  "document": "data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg=="
}
'

import requests

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

payload = {
    "documentType": "CNPJ",
    "documentNumber": "11.222.333/0001-81",
    "contactEmail": "ana@example.com",
    "contactWhatsapp": "+55 11 90000-0000",
    "document": "data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg=="
}
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({
    documentType: 'CNPJ',
    documentNumber: '11.222.333/0001-81',
    contactEmail: 'ana@example.com',
    contactWhatsapp: '+55 11 90000-0000',
    document: 'data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg=='
  })
};

fetch('https://pilotstatus.com.br/v1/phone-lines/verification', 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/verification",
  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([
    'documentType' => 'CNPJ',
    'documentNumber' => '11.222.333/0001-81',
    'contactEmail' => 'ana@example.com',
    'contactWhatsapp' => '+55 11 90000-0000',
    'document' => 'data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg=='
  ]),
  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/verification"

	payload := strings.NewReader("{\n  \"documentType\": \"CNPJ\",\n  \"documentNumber\": \"11.222.333/0001-81\",\n  \"contactEmail\": \"ana@example.com\",\n  \"contactWhatsapp\": \"+55 11 90000-0000\",\n  \"document\": \"data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg==\"\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/verification")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"documentType\": \"CNPJ\",\n  \"documentNumber\": \"11.222.333/0001-81\",\n  \"contactEmail\": \"ana@example.com\",\n  \"contactWhatsapp\": \"+55 11 90000-0000\",\n  \"document\": \"data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg==\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"documentType\": \"CNPJ\",\n  \"documentNumber\": \"11.222.333/0001-81\",\n  \"contactEmail\": \"ana@example.com\",\n  \"contactWhatsapp\": \"+55 11 90000-0000\",\n  \"document\": \"data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg==\"\n}"

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

{
  "status": "PENDING_CONTACT",
  "canPurchase": false,
  "verification": {
    "id": "cmg5k0v3r0000vf8example7k",
    "documentType": "CNPJ",
    "documentNumber": "**.***.333/0001-**",
    "legalName": "ACME LTDA",
    "contact": {
      "email": "a***@example.com",
      "whatsapp": "+5511****0000",
      "requiredChannels": [
        "WHATSAPP",
        "EMAIL"
      ],
      "confirmedChannels": [
        "WHATSAPP"
      ],
      "pendingChannels": [
        "EMAIL"
      ]
    },
    "document": {
      "status": "RECEIVED"
    },
    "reviewReason": null,
    "reviewNote": null,
    "createdAt": "2026-10-01T13:55:02.000Z",
    "updatedAt": "2026-10-01T13:56:40.000Z"
  }
}

Endpoints

Workspace

Submit holder verification

Authorizations

Headers

Body

Response