> ## Documentation Index > Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt > Use this file to discover all available pages before exploring further. # 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. > [!WARNING] > > **This submits your workspace's real identity verification.** Send only the account holder's true data and document. ## OpenAPI ````yaml openapi.json POST /v1/phone-lines/verification openapi: 3.1.0 info: title: Pilot Status API version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- Public REST API for Pilot Status. Authenticate with the `x-api-key: ps_...` header (or `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/phone-lines/verification: post: tags: - Phone Lines summary: Submit holder verification description: >- ⚠️ **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. operationId: post_phone_lines_verification parameters: - name: Idempotency-Key in: header required: true description: >- **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. schema: type: string maxLength: 255 example: 5f0c6d2e-9a41-4d1b-8f7e-2b3c4d5e6f70 requestBody: required: true content: application/json: schema: type: object required: - documentType - documentNumber - contactEmail - contactWhatsapp - document additionalProperties: false properties: documentType: type: string enum: - CNPJ - CPF description: '`"CNPJ"` or `"CPF"`.' example: CNPJ documentNumber: type: string description: >- 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: type: string format: email maxLength: 254 description: >- The account holder's contact e-mail, up to 254 characters. It always receives a code. example: ana@example.com contactWhatsapp: type: string description: >- 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: type: string description: >- The document file as a **base64 data URI**: `data:;base64,`, 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== example: documentType: CNPJ documentNumber: 11.222.333/0001-81 contactEmail: ana@example.com contactWhatsapp: +55 11 90000-0000 document: data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCg== responses: '200': description: >- Idempotent replay: the same `Idempotency-Key` and the same request already finished. The workspace's **current** state; nothing was started or sent again. headers: Cache-Control: description: Always `no-store`. schema: type: string enum: - no-store Idempotent-Replayed: description: '`true` on a replay.' schema: type: string enum: - 'true' content: application/json: schema: type: object properties: status: type: string enum: - NONE - PENDING_CONTACT - IN_REVIEW - APPROVED - NEEDS_DOCUMENT - REJECTED description: >- `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. canPurchase: type: boolean description: >- Whether `POST /v1/phone-lines` is allowed now: `true` for `APPROVED` and `IN_REVIEW`. verification: type: object nullable: true description: '`null` for `NONE`.' properties: id: type: string description: >- Identifies the verification — the `verificationId` of the webhook event, and what support will ask for. documentType: type: string enum: - CNPJ - CPF documentNumber: type: string description: >- **Masked**: `**.***.333/0001-**` (CNPJ) or `***.456.789-**` (CPF). The full number is never returned. legalName: type: string nullable: true description: >- The company name from the public registry (CNPJ). `null` for a CPF, and when the registry could not be consulted. contact: type: object properties: email: type: string description: The contact e-mail, masked (`a***@example.com`). whatsapp: type: string nullable: true description: The contact WhatsApp, masked (`+5511****0000`). requiredChannels: type: array items: type: string enum: - WHATSAPP - EMAIL description: >- `WHATSAPP` and/or `EMAIL`: the codes this verification needs. Frozen when the verification starts. Through the API `EMAIL` is always required. confirmedChannels: type: array items: type: string enum: - WHATSAPP - EMAIL description: The required channels already confirmed. pendingChannels: type: array items: type: string enum: - WHATSAPP - EMAIL description: >- The required channels still waiting for their code. document: type: object properties: status: type: string enum: - RECEIVED - UNREADABLE - UNCLEAR - REQUESTED - MISSING description: >- `RECEIVED` (the document is in), `UNREADABLE` (we found no number in the file), `UNCLEAR` (we found numbers, but none we could trust), `REQUESTED` (the reviewer asked for another document) or `MISSING` (no document yet). For the last four, send a new document with `POST /v1/phone-lines/verification/document`. reviewReason: type: string nullable: true enum: - REGISTRY_UNAVAILABLE - DOCUMENT_CHECK - null description: >- Only while `IN_REVIEW`: `REGISTRY_UNAVAILABLE` (the CNPJ registry could not be consulted) or `DOCUMENT_CHECK` (the document needs a look). `null` otherwise. reviewNote: type: string nullable: true description: >- The reviewer's message, on `REJECTED` and `NEEDS_DOCUMENT` only. `null` otherwise, and it may be `null` there too. createdAt: type: string format: date-time description: ISO 8601 — when this verification was submitted. updatedAt: type: string format: date-time description: ISO 8601 — its last change. example: 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' '201': description: >- Verification started: the codes are on their way (`PENDING_CONTACT`). headers: Cache-Control: description: Always `no-store`. schema: type: string enum: - no-store content: application/json: schema: type: object properties: status: type: string enum: - NONE - PENDING_CONTACT - IN_REVIEW - APPROVED - NEEDS_DOCUMENT - REJECTED description: >- `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. canPurchase: type: boolean description: >- Whether `POST /v1/phone-lines` is allowed now: `true` for `APPROVED` and `IN_REVIEW`. verification: type: object nullable: true description: '`null` for `NONE`.' properties: id: type: string description: >- Identifies the verification — the `verificationId` of the webhook event, and what support will ask for. documentType: type: string enum: - CNPJ - CPF documentNumber: type: string description: >- **Masked**: `**.***.333/0001-**` (CNPJ) or `***.456.789-**` (CPF). The full number is never returned. legalName: type: string nullable: true description: >- The company name from the public registry (CNPJ). `null` for a CPF, and when the registry could not be consulted. contact: type: object properties: email: type: string description: The contact e-mail, masked (`a***@example.com`). whatsapp: type: string nullable: true description: The contact WhatsApp, masked (`+5511****0000`). requiredChannels: type: array items: type: string enum: - WHATSAPP - EMAIL description: >- `WHATSAPP` and/or `EMAIL`: the codes this verification needs. Frozen when the verification starts. Through the API `EMAIL` is always required. confirmedChannels: type: array items: type: string enum: - WHATSAPP - EMAIL description: The required channels already confirmed. pendingChannels: type: array items: type: string enum: - WHATSAPP - EMAIL description: >- The required channels still waiting for their code. document: type: object properties: status: type: string enum: - RECEIVED - UNREADABLE - UNCLEAR - REQUESTED - MISSING description: >- `RECEIVED` (the document is in), `UNREADABLE` (we found no number in the file), `UNCLEAR` (we found numbers, but none we could trust), `REQUESTED` (the reviewer asked for another document) or `MISSING` (no document yet). For the last four, send a new document with `POST /v1/phone-lines/verification/document`. reviewReason: type: string nullable: true enum: - REGISTRY_UNAVAILABLE - DOCUMENT_CHECK - null description: >- Only while `IN_REVIEW`: `REGISTRY_UNAVAILABLE` (the CNPJ registry could not be consulted) or `DOCUMENT_CHECK` (the document needs a look). `null` otherwise. reviewNote: type: string nullable: true description: >- The reviewer's message, on `REJECTED` and `NEEDS_DOCUMENT` only. `null` otherwise, and it may be `null` there too. createdAt: type: string format: date-time description: ISO 8601 — when this verification was submitted. updatedAt: type: string format: date-time description: ISO 8601 — its last change. example: 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: [] pendingChannels: - WHATSAPP - EMAIL document: status: RECEIVED reviewReason: null reviewNote: null createdAt: '2026-10-01T13:55:02.000Z' updatedAt: '2026-10-01T13:55:09.000Z' '400': description: >- Validation: missing/invalid `Idempotency-Key`, body not a JSON object (`INVALID_BODY`), unknown field (`UNKNOWN_FIELDS`, `details.unknownFields`), `INVALID_DOCUMENT_TYPE`, `INVALID_DOCUMENT_NUMBER` (missing, or wrong check digits), `INVALID_CONTACT_EMAIL`, `INVALID_CONTACT_WHATSAPP`, `INVALID_DOCUMENT` (not a base64 data URI), `DOCUMENT_TYPE_UNSUPPORTED` (not PDF/JPEG/PNG/WEBP), `REGISTRY_NOT_FOUND` (CNPJ not in the public registry) or `REGISTRY_INACTIVE` (CNPJ not active: lines cannot be sold to it). content: application/json: schema: type: object properties: error: type: string description: >- English sentence and Portuguese sentence separated by ` | `. code: type: string description: Stable error code — branch on it, never on the text. details: type: object description: >- Validation errors only: `unknownFields` (array) or `maxLength` (number). additionalProperties: true examples: idempotencyKeyRequired: summary: No Idempotency-Key value: error: >- Send an Idempotency-Key header (for example a UUID) so a retry cannot start the verification twice. | Envie o header Idempotency-Key (por exemplo um UUID) para que uma nova tentativa não inicie a verificação duas vezes. code: IDEMPOTENCY_KEY_REQUIRED idempotencyKeyInvalid: summary: Key too long or with control characters value: error: >- Idempotency-Key must have at most 255 characters and no control characters. | Idempotency-Key deve ter no máximo 255 caracteres e nenhum caractere de controle. code: IDEMPOTENCY_KEY_INVALID details: maxLength: 255 unknownFields: summary: Field this endpoint does not take value: error: >- Unknown field(s): whatsapp. Accepted: documentType, documentNumber, contactEmail, contactWhatsapp, document. | Campo(s) desconhecido(s): whatsapp. Aceitos: documentType, documentNumber, contactEmail, contactWhatsapp, document. code: UNKNOWN_FIELDS details: unknownFields: - whatsapp invalidDocumentType: summary: documentType not CNPJ/CPF value: error: >- documentType must be "CPF" or "CNPJ". | documentType deve ser "CPF" ou "CNPJ". code: INVALID_DOCUMENT_TYPE invalidDocumentNumber: summary: Wrong check digits value: error: >- The document number is not valid. | O número do documento não é válido. code: INVALID_DOCUMENT_NUMBER invalidContactEmail: summary: Invalid e-mail value: error: >- contactEmail must be a valid e-mail address: the verification code is sent to it. | contactEmail deve ser um e-mail válido: o código de verificação é enviado para ele. code: INVALID_CONTACT_EMAIL invalidContactWhatsapp: summary: Invalid WhatsApp number value: error: >- contactWhatsapp must be a WhatsApp number with country and area code, e.g. +55 11 99999-8888. | contactWhatsapp deve ser um número de WhatsApp com país e DDD, ex.: +55 11 99999-8888. code: INVALID_CONTACT_WHATSAPP invalidDocument: summary: document is not a data URI value: error: >- document must be the file as a base64 data URI, e.g. data:application/pdf;base64,JVBERi0x… | document deve ser o arquivo como data URI em base64, ex.: data:application/pdf;base64,JVBERi0x… code: INVALID_DOCUMENT documentTypeUnsupported: summary: Unsupported file type value: error: >- Send a PDF, JPG, PNG or WEBP file. | Envie um arquivo PDF, JPG, PNG ou WEBP. code: DOCUMENT_TYPE_UNSUPPORTED registryNotFound: summary: CNPJ not in the registry value: error: >- This CNPJ was not found in the public registry. | Este CNPJ não foi encontrado na Receita. code: REGISTRY_NOT_FOUND registryInactive: summary: CNPJ not active value: error: >- This CNPJ is not active in the public registry, so lines cannot be sold to it. | Este CNPJ não está ativo na Receita, então não é possível vender linhas para ele. code: REGISTRY_INACTIVE '401': description: >- Missing or invalid `x-api-key` / `x-api-key-id` header (or OAuth Bearer token). No `code` in this body. content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Invalid API key '403': description: >- `VERIFICATION_REJECTED`: the verification was rejected — final, talk to support. Also: number-scoped key or per-number OAuth grant (`NUMBER_SCOPE_NOT_ALLOWED` — use the tenant-scoped key); OAuth/MCP token whose user is not the workspace OWNER (`PERMISSION_DENIED`) or no longer an active member (`WORKSPACE_MEMBERSHIP_REQUIRED`); archived workspace (`WORKSPACE_ARCHIVED`). The scope and role errors carry an English-only `error`.. `TENANT_REQUIRED`: credential not bound to any workspace content: application/json: schema: type: object properties: error: type: string code: type: string examples: rejected: summary: Verification rejected value: error: >- The account holder verification was rejected. | A verificação do titular foi recusada. code: VERIFICATION_REJECTED numberScope: summary: Number-scoped key value: error: This endpoint requires a tenant-scoped API key code: NUMBER_SCOPE_NOT_ALLOWED permission: summary: OAuth/MCP user is not the OWNER value: error: >- Your workspace role does not allow this action (phone_lines:purchase). code: PERMISSION_DENIED membership: summary: OAuth/MCP user no longer an active member value: error: >- The user behind this token is not an active member of this workspace. code: WORKSPACE_MEMBERSHIP_REQUIRED archived: summary: Archived workspace value: error: >- This workspace has been archived and its API is closed. | Este workspace foi arquivado e sua API está encerrada. code: WORKSPACE_ARCHIVED tenantRequired: summary: Credential not bound to a workspace value: error: This credential is not bound to a workspace. code: TENANT_REQUIRED '409': description: >- `VERIFICATION_WRONG_STATE`: the current verification is `IN_REVIEW`, `APPROVED` (you can already buy) or `NEEDS_DOCUMENT` (send the document to `…/verification/document`). `IDEMPOTENCY_KEY_IN_USE`: a request with this key is still running — wait, then send it again to get its result. `IDEMPOTENCY_KEY_REUSED`: this key was used for a different request — use a new key. content: application/json: schema: type: object properties: error: type: string code: type: string examples: wrongState: summary: Verification already past its data step value: error: >- The verification is not in a state that allows this. | A verificação não está em um estado que permita isso. code: VERIFICATION_WRONG_STATE inUse: summary: Key still in use value: error: >- A request with this Idempotency-Key is still running. Wait for it, then send it again to get its result. | Um pedido com esta Idempotency-Key ainda está em andamento. Aguarde e envie de novo para receber o resultado. code: IDEMPOTENCY_KEY_IN_USE reused: summary: Key reused for a different request value: error: >- This Idempotency-Key was already used for a different request. Use a new key for new data. | Esta Idempotency-Key já foi usada em outro pedido. Use uma nova chave para dados novos. code: IDEMPOTENCY_KEY_REUSED '413': description: The file is over 10 MB. content: application/json: schema: type: object properties: error: type: string code: type: string example: error: The file is larger than 10 MB. | O arquivo tem mais de 10 MB. code: DOCUMENT_TOO_LARGE '429': description: >- `RATE_LIMITED`: over 10 submissions in the hour for this workspace (this endpoint and `…/verification/document` together). Wait `Retry-After` seconds. headers: Retry-After: description: Seconds to wait before the next submission. schema: type: integer content: application/json: schema: type: object properties: error: type: string code: type: string retryAfterSeconds: type: integer description: Seconds until a new submission is accepted. example: error: >- Too many verification submissions: at most 10 per hour per workspace. Try again later. | Envios de verificação demais: no máximo 10 por hora por workspace. Tente de novo mais tarde. code: RATE_LIMITED retryAfterSeconds: 1820 '500': description: Unexpected failure. Retry. content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unexpected error. | Erro inesperado. code: INTERNAL_ERROR '503': description: >- `SUPPLIER_UNAVAILABLE`: a contact code could not be queued for sending. The key is freed — try again in a few minutes. content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- Phone lines are temporarily unavailable. Try again in a few minutes. | As linhas estão temporariamente indisponíveis. Tente de novo em alguns minutos. code: SUPPLIER_UNAVAILABLE components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your ps_ API key apiKeyId: type: apiKey in: header name: x-api-key-id description: API key id (alternative to x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.