Linhas telefônicas

Enviar verificação do titular

⚠️ Esta chamada é real: ela envia a verificação de identidade do workspace e envia códigos de verificação reais para contactEmail (sempre) e para contactWhatsapp (sempre que a Pilot Status está enviando códigos pelo WhatsApp — contact.requiredChannels diz quais). Use apenas dados reais do titular da conta.

Inicia a verificação e entrega o documento, numa só chamada. Conferimos o número (dígitos verificadores; um CNPJ também precisa ser encontrado e estar ativo na Receita), congelamos os canais de contato exigidos, enviamos os códigos, guardamos o arquivo de forma privada e lemos o número impresso nele. Responde 201 com o estado em PENDING_CONTACT; depois, confirme cada código com POST /v1/phone-lines/verification/contact/{channel}/confirm. A requisição volta depois que o documento foi lido — em geral em segundos, no máximo cerca de um minuto.

O corpo é JSON (Content-Type: application/json), não multipart: o arquivo vai em document como data URI em base64. Qualquer outro campo é recusado com 400 UNKNOWN_FIELDS. O arquivo é conferido antes de qualquer coisa começar: tipo ou tamanho errado não envia código nem cria nada.

Enviar de novo. Enquanto a verificação ainda está em PENDING_CONTACT, um novo envio a substitui (para corrigir um erro de digitação): os códigos já enviados deixam de valer e novos são enviados. Depois que ela avançou, um envio responde 409 VERIFICATION_WRONG_STATE (IN_REVIEW ou APPROVED — você já pode comprar — ou NEEDS_DOCUMENT — envie o documento em POST /v1/phone-lines/verification/document) ou 403 VERIFICATION_REJECTED.

Idempotência (Idempotency-Key é OBRIGATÓRIO), durante 24 horas: mesma chave + mesma requisição, a primeira já terminou → 200 (não 201) com o estado atual do workspace e Idempotent-Replayed: true, nada é enviado de novo; mesma chave enquanto a primeira ainda está rodando → 409 IDEMPOTENCY_KEY_IN_USE; mesma chave, requisição diferente (qualquer campo, inclusive o arquivo) → 409 IDEMPOTENCY_KEY_REUSED; uma requisição recusada como um todo libera a chave. Limite: 10 envios por hora por workspace, somando este endpoint e …/verification/document → 429 RATE_LIMITED. Exige uma chave com escopo de tenant, como todo endpoint /v1/phone-lines (uma chave com escopo de número recebe 403 NUMBER_SCOPE_NOT_ALLOWED). Permissão phone_lines:purchase, a mesma da compra: com um token OAuth/MCP, só o OWNER do workspace pode chamar (403 PERMISSION_DENIED caso contrário). É a mesma verificação do painel (Linhas → Comprar linhas): o que você fizer por um caminho aparece no outro. A resposta é o objeto de estado da verificação, enviado com Cache-Control: no-store; o número do documento e os contatos voltam mascarados.

POST

phone-lines

verification

Enviar a verificação do titular

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"
  }
}

Isto envia a verificação de identidade real do seu workspace. Envie só os dados e o documento verdadeiros do titular.

Autorizações

x-api-key

string

header

obrigatório

Sua chave de API ps_

Cabeçalhos

Idempotency-Key

string

obrigatório

Obrigatório. Qualquer string de até 255 caracteres, sem caracteres de controle — um UUID por envio. Ausente ou em branco → 400 IDEMPOTENCY_KEY_REQUIRED; mais longa, ou com um caractere de controle → 400 IDEMPOTENCY_KEY_INVALID. Lembrada por 24 horas por workspace: a mesma chave enviada por dois workspaces nunca colide.

Maximum string length: 255

Corpo

application/json

documentType

enum<string>

obrigatório

"CNPJ" ou "CPF".

Opções disponíveis:

CNPJ,

CPF

Exemplo:

"CNPJ"

documentNumber

string

obrigatório

O CNPJ ou CPF, com ou sem pontuação (11.222.333/0001-81 ou 11222333000181). CNPJs alfanuméricos são aceitos.

Exemplo:

"11.222.333/0001-81"

contactEmail

string<email>

obrigatório

O e-mail de contato do titular, com até 254 caracteres. Ele sempre recebe um código.

Maximum string length: 254

Exemplo:

"ana@example.com"

contactWhatsapp

string

obrigatório

O número de WhatsApp do titular no formato internacional — código do país, DDD e número, por exemplo +55 11 90000-0000; a pontuação é ignorada. Ele recebe um código quando WHATSAPP é exigido.

Exemplo:

"+55 11 90000-0000"

document

string

obrigatório

O arquivo do documento como data URI em base64: data:<tipo>;base64,<conteúdo>, codificado sem quebras de linha. Tipos: application/pdf, image/jpeg, image/png, image/webp; no máximo 10 MB de arquivo (cerca de 14 MB depois de codificado). Para CNPJ: cartão CNPJ, contrato social ou comprovante de inscrição. Para CPF: RG, CNH ou comprovante de inscrição no CPF, com o número legível.

Exemplo:

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

Resposta

Replay idempotente: a mesma Idempotency-Key com a mesma requisição já terminou. O estado atual do workspace; nada foi iniciado nem enviado de novo.

status

enum<string>

NONE (nunca iniciada), PENDING_CONTACT (esperando os códigos de contato e, se document.status indicar, um documento melhor), IN_REVIEW (concluída, esperando uma pessoa conferir — compra permitida), APPROVED (verificada — compra permitida), NEEDS_DOCUMENT (o revisor pediu outro documento) ou REJECTED (definitivo — fale com o suporte). O webhook phone_line.verification_updated usa os mesmos valores para os quatro últimos.

Opções disponíveis:

NONE,

PENDING_CONTACT,

IN_REVIEW,

APPROVED,

NEEDS_DOCUMENT,

REJECTED

canPurchase

boolean

Se POST /v1/phone-lines é permitido agora: true para APPROVED e IN_REVIEW.

verification

object | null

null para NONE.

Show child attributes

Enviar a verificação do titular

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

Enviar verificação do titular

Autorizações

Cabeçalhos

Corpo

Resposta