> ## Documentation Index > Fetch the complete documentation index at: https://docs.id.zapsign.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Criar validação de vínculo entre CPF e telefone > Verifica se o telefone pertence ao titular do CPF. ## OpenAPI ````yaml POST /validations/cpf-phone-match openapi: 3.1.0 info: title: ID ZapSign version: 1.0.0 description: >- API de validações de identidade da ID ZapSign. Crie validações, consulte o resultado e gerencie suas chaves de API. contact: name: Suporte ID ZapSign url: https://id.zapsign.com.br email: support@zapsign.com.br servers: - url: https://api.id.zapsign.com.br/v1 description: Produção security: - bearerAuth: [] tags: - name: Validações description: Criação e consulta de validações. - name: Chaves de API description: Criação, listagem e revogação de chaves de API. paths: /validations/cpf-phone-match: post: tags: - Validações summary: Cria uma validação de vínculo entre CPF e telefone. description: >- Verifica se o telefone pertence ao titular do CPF. É síncrona: a resposta já traz o resultado, com `status` igual a `completed`. operationId: createCpfPhoneMatchValidation parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CpfPhoneMatchValidationInput' examples: minimo: summary: Mínimo obrigatório value: cpf: '12345678909' phone: '+5511999998888' consent: true com_external_id: summary: Com referência de correlação value: cpf: '12345678909' phone: '+5511999998888' consent: true external_id: pedido_12345 responses: '200': description: Validação concluída. headers: Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/Validation' examples: match: summary: O telefone pertence ao titular value: object: validation id: val_0NQW3MVYJYQ453E95V3V1T76AV type: cpf_phone_match status: completed result: match reason_code: null external_id: pedido_12345 created_at: '2026-08-07T14:03:11Z' resolved_at: '2026-08-07T14:03:12Z' validation_url: null expires_at: null details: null no_match: summary: O telefone não pertence ao titular value: object: validation id: val_2NX7D5C8EBN0A41V05PHETTG9K type: cpf_phone_match status: completed result: no_match reason_code: null external_id: null created_at: '2026-08-07T14:05:40Z' resolved_at: '2026-08-07T14:05:41Z' validation_url: null expires_at: null details: null unknown: summary: A fonte não respondeu com dados value: object: validation id: val_7XQH9CD43E8XH64CHYBT99WD9W type: cpf_phone_match status: completed result: unknown reason_code: data_unavailable external_id: null created_at: '2026-08-07T14:07:02Z' resolved_at: '2026-08-07T14:07:04Z' validation_url: null expires_at: null details: null '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '409': $ref: '#/components/responses/IdempotencyConflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Torna a criação segura para retentativa. Reenviar a mesma chave repete a resposta original em vez de criar (e cobrar) uma validação nova. schema: type: string pattern: ^[A-Za-z0-9_-]{1,256}$ minLength: 1 maxLength: 256 example: a3f1c9e2-7b64-4d18-9a02-5c6e8f0b1d34 schemas: CpfPhoneMatchValidationInput: type: object description: Dados para criar uma validação de vínculo entre CPF e telefone. required: - cpf - phone - consent properties: cpf: type: string description: CPF do titular, só dígitos. example: '12345678909' phone: type: string description: Telefone celular brasileiro do titular, em formato E.164. example: '+5511999998888' consent: type: boolean const: true description: Confirma que o titular consentiu com a consulta. Precisa ser `true`. external_id: type: string pattern: ^[A-Za-z0-9_-]{1,256}$ minLength: 1 maxLength: 256 description: >- Sua referência de correlação. Volta em todas as respostas desta validação. example: pedido_12345 Validation: type: object description: Resultado de uma validação. required: - object - id - type - status - result - reason_code - external_id - created_at - resolved_at - validation_url - expires_at - details properties: object: type: string enum: - validation description: Sempre `validation`. id: type: string description: Identificador único da validação. example: val_0NQW3MVYJYQ453E95V3V1T76AV type: type: string enum: - liveness_document_match - liveness_cpf_match - cpf_phone_match - sim_swap - telco_financial_capacity description: >- Tipo da validação. | Valor | O que é | | --- | --- | | `cpf_phone_match` | Vínculo entre CPF e telefone | | `sim_swap` | Troca de chip | | `liveness_document_match` | Prova de vida + documento | | `liveness_cpf_match` | Prova de vida + CPF | | `telco_financial_capacity` | Capacidade financeira via operadora | Os três primeiros têm endpoint de criação. Os outros dois podem aparecer em consultas e listagens de contas que os usam por outros canais. status: type: string enum: - pending - completed - failed - expired description: >- Estado atual. | Valor | O que é | | --- | --- | | `pending` | Criada, aguardando o titular concluir o fluxo hospedado | | `completed` | Resolvida; veja `result` | | `failed` | Não foi possível concluir | | `expired` | A sessão hospedada venceu sem conclusão | result: description: >- Resultado de negócio. É `null` enquanto `status` for `pending`. | Valor | Aparece em | | --- | --- | | `match` / `no_match` | `cpf_phone_match` | | `recent_swap` / `no_recent_swap` | `sim_swap` | | `passed` / `not_passed` | `liveness_document_match`, `liveness_cpf_match` | | `high_capacity` / `moderate_capacity` / `low_capacity` | `telco_financial_capacity` | | `unknown` | Qualquer tipo, quando a fonte não deu uma resposta conclusiva. O motivo vem em `reason_code`. | anyOf: - type: string enum: - passed - not_passed - match - no_match - recent_swap - no_recent_swap - high_capacity - moderate_capacity - low_capacity - unknown - type: 'null' reason_code: description: >- Por que o resultado foi `unknown`. É `null` em qualquer outro caso. | Valor | O que é | | --- | --- | | `liveness_failed` | Prova de vida não confirmada | | `face_mismatch` | O rosto não corresponde ao documento | | `spoof_detected` | Suspeita de fraude na captura | | `document_tampered` | Indícios de adulteração no documento | | `document_invalid` | Documento inválido ou não aceito | | `document_unreadable` | O documento não pôde ser lido | | `cpf_reference_not_found` | CPF não encontrado na base de referência | | `data_unavailable` | Dados indisponíveis na fonte consultada | | `phone_not_covered` | Telefone sem cobertura para a consulta | anyOf: - type: string enum: - liveness_failed - face_mismatch - spoof_detected - document_tampered - document_invalid - document_unreadable - cpf_reference_not_found - data_unavailable - phone_not_covered - type: 'null' external_id: type: - string - 'null' description: A referência de correlação que você enviou na criação. created_at: type: string format: date-time description: Data de criação em ISO-8601. resolved_at: type: - string - 'null' format: date-time description: Data de resolução em ISO-8601. É `null` enquanto não resolvida. validation_url: type: - string - 'null' description: >- URL para onde redirecionar o titular. Preenchida nas validações hospedadas; `null` nas síncronas. expires_at: type: - string - 'null' format: date-time description: >- Quando a sessão hospedada vence, em ISO-8601. Preenchida nas validações hospedadas; `null` nas síncronas. details: description: >- Dados extraídos, agrupados pela chave do `type`. Hoje só `liveness_document_match` produz detalhes, e só com `status` igual a `completed`. Nos demais casos é `null`. anyOf: - $ref: '#/components/schemas/ValidationDetails' - type: 'null' ValidationDetails: type: object description: >- Detalhes por tipo. Contém no máximo uma propriedade, cuja chave é o `type` do recurso. additionalProperties: false properties: liveness_document_match: $ref: '#/components/schemas/LivenessDocumentMatchDetails' ErrorEnvelope: type: object description: >- Formato único de erro. Toda falha da API responde neste formato. A lista completa de `code` está em [Erros](/erros). required: - error properties: error: type: object required: - type - code - message - doc_url - request_id properties: type: type: string enum: - invalid_request - authentication_error - not_found - api_error - idempotency_error - payment_error - rate_limit_error description: >- Categoria do erro. Serve para tratar famílias inteiras sem enumerar cada `code`. code: type: string description: >- Código estável do erro. É o que você deve usar para ramificar no seu código. example: missing_required_param message: type: string description: >- Descrição legível, em inglês. É para diagnóstico, não para mostrar ao usuário final. param: type: string description: O campo que causou o erro, quando aplicável. example: cpf doc_url: type: string description: Link direto para este código nesta documentação. example: https://docs.id.zapsign.com.br/missing_required_param request_id: type: string description: Identificador da requisição. Inclua no contato com o suporte. example: req_3PK3TA2H0MEMTDSAPREHSY4QC4 LivenessDocumentMatchDetails: type: object description: >- Dados lidos do documento e da pessoa. Os dez campos vêm sempre, e cada um é `null` quando o provedor não conseguiu extraí-lo. additionalProperties: false required: - full_name - sex - cpf - date_of_birth - document_type - document_number - document_country - document_version - document_issued_at - document_expires_at properties: full_name: type: - string - 'null' description: Nome completo como consta no documento. sex: description: >- Sexo como consta no documento. Valores fora de `M` e `F` viram `null`. anyOf: - type: string enum: - M - F - type: 'null' cpf: type: - string - 'null' pattern: ^\d{11}$ description: CPF lido do documento, só dígitos. date_of_birth: type: - string - 'null' format: date description: Data de nascimento no formato `YYYY-MM-DD`. document_type: description: >- Categoria do documento, independente do país emissor. Tipos que não caem no mapa viram `other`. | Valor | O que é | | --- | --- | | `id_card` | Documento de identidade | | `drivers_license` | Carteira de motorista | | `passport` | Passaporte | | `other` | Outro tipo reconhecido pelo provedor | anyOf: - type: string enum: - id_card - drivers_license - passport - other - type: 'null' document_number: type: - string - 'null' description: Número como consta no documento. document_country: type: - string - 'null' description: País emissor em ISO 3166-1 alpha-2, por exemplo `BR`. document_version: type: - string - 'null' description: Versão ou modelo do documento, segundo o provedor. document_issued_at: type: - string - 'null' format: date description: Data de emissão no formato `YYYY-MM-DD`. document_expires_at: type: - string - 'null' format: date description: >- Vencimento do documento no formato `YYYY-MM-DD`, ou `null` se não expira. Não confundir com o `expires_at` da raiz, que é o prazo da sessão hospedada. headers: IdempotentReplayed: description: >- Vem com o valor `true` quando a resposta é a repetição de uma requisição idempotente anterior, e não uma criação nova. schema: type: string enum: - 'true' responses: InvalidRequest: description: Requisição inválida (corpo, parâmetro ou chave de idempotência). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: missing_required_param message: A required parameter is missing. param: cpf doc_url: https://docs.id.zapsign.com.br/missing_required_param request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4 Unauthorized: description: Chave de API ausente ou inválida. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: authentication_error code: invalid_api_key message: The API key provided is invalid. doc_url: https://docs.id.zapsign.com.br/invalid_api_key request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4 PaymentRequired: description: Saldo insuficiente para executar a validação. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: payment_error code: insufficient_balance message: Insufficient balance for this validation. doc_url: https://docs.id.zapsign.com.br/insufficient_balance request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4 IdempotencyConflict: description: >- Outra requisição com a mesma chave de idempotência ainda está em andamento. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: idempotency_error code: idempotency_in_progress message: A request with the same Idempotency-Key is still in progress. doc_url: https://docs.id.zapsign.com.br/idempotency_in_progress request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4 PayloadTooLarge: description: Corpo da requisição maior que o limite permitido. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: request_too_large message: The request body is too large. doc_url: https://docs.id.zapsign.com.br/request_too_large request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4 UnprocessableEntity: description: Valor semanticamente inválido (regra de negócio). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: invalid_request code: invalid_cpf message: The value provided is invalid. param: cpf doc_url: https://docs.id.zapsign.com.br/invalid_cpf request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4 TooManyRequests: description: Limite de requisições excedido. Veja [Limites de uso](/limites-de-uso). headers: Retry-After: description: Segundos a aguardar antes de tentar de novo. Presente em todo 429. schema: type: integer minimum: 1 RateLimit-Limit: description: Teto de requisições da classe para a conta. Só no 429 de taxa. schema: type: integer minimum: 1 RateLimit-Remaining: description: Requisições restantes na janela atual. Só no 429 de taxa. schema: type: integer minimum: 0 RateLimit-Reset: description: >- Segundos até o limite se restabelecer por completo. Só no 429 de taxa. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Please retry after the indicated delay. doc_url: https://docs.id.zapsign.com.br/rate_limit_exceeded request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4 InternalError: description: Erro interno inesperado. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: type: api_error code: api_error message: An internal error occurred. doc_url: https://docs.id.zapsign.com.br/api_error request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4 securitySchemes: bearerAuth: type: http scheme: bearer description: >- Sua chave de API no cabeçalho `Authorization: Bearer sk_...`. Crie e revogue chaves no painel ou pelos endpoints de Chaves de API. ````