Verificação de Telefone

A Verificação de Telefone confirma que um número de telefone realmente pertence à pessoa que o declara, usando uma consulta de identity-match da operadora. Ela compara o nome, o endereço e a data de nascimento do remetente com os dados que a operadora móvel possui para aquele número e retorna uma pontuação de correspondência. Use-a como sinal antifraude durante o onboarding ou antes de uma primeira transação.

Esta verificação é diagnóstica e explícita — nunca é executada automaticamente a partir do fluxo de transação e nunca reescreve o número de telefone armazenado do remetente. Chame-a quando quiser fazer uma verificação.

Verificar um Número de Telefone

Endpoint: POST /organizations/{tenant}/v2/people/verifyPhone
Autenticação: Nível de agente (x-api-key + x-agent-id + x-agent-api-key)

Há dois modos de chamada mutuamente exclusivos:

⚠️ Os modos não podem ser combinados. Se você enviar personId, não deve enviar nenhum campo de identidade inline, ou a requisição retorna 422.

Modo Pessoa

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/people/verifyPhone \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "personId": "48066496-9445-41b7-acbe-85e069a77cb7"
}'

O phoneNumber armazenado do remetente já deve estar no formato E.164; caso contrário, a requisição retorna 422.

Modo Inline

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/people/verifyPhone \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "phoneNumber": "+14145447770",
  "firstName": "John",
  "lastName": "Doe",
  "addressLine1": "123 Market St",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94105",
  "addressCountryCode": "US",
  "dateOfBirth": "1990-01-15"
}'

Campos da Requisição

Quanto mais campos de identidade você fornecer, mais completo será o resultado de correspondência.

Resposta

{
  "verificationId": 42,
  "phoneNumber": "+14145447770",
  "status": "MATCH",
  "summaryScore": 100,
  "callerType": "CONSUMER",
  "valid": true,
  "nationalFormat": "(414) 544-7770",
  "countryCode": "US",
  "identityMatch": {
    "first_name_match": "exact_match",
    "last_name_match": "exact_match",
    "address_lines_match": "exact_match",
    "date_of_birth_match": "exact_match",
    "summary_score": 100
  },
  "verifiedAt": "2026-09-09T14:22:11+00:00",
  "cached": false
}

Limiares de Status

status é derivado de summaryScore usando limiares por tenant (padrões: MATCH ≥ 80, PARTIAL ≥ 40, abaixo → NO_MATCH). O status é capturado no momento da verificação — mudanças de limiar posteriores não reclassificam resultados históricos. Contate a Inyo para ajustar seus limiares.

Cache

Requisições idênticas são armazenadas em cache por tenant durante 90 dias, com chave na tupla completa de entrada (número de telefone, nome, endereço, data de nascimento). Um acerto de cache retorna o resultado armazenado com "cached": true e não cobra novamente o provedor de verificação. Varie qualquer campo de entrada para forçar uma consulta nova.

Respostas de Erro

Testes no Sandbox

No sandbox, a verificação de telefone não chama o provedor real — sem cobrança, sem consultas ao vivo. Em vez disso, o resultado é determinado inteiramente pelo último dígito do número de telefone, então você pode exercitar cada ramo escolhendo o número que envia:

Por exemplo, +14145550002 retorna MATCH e +14145550009 retorna 502.

Como a chave de cache inclui o número de telefone, reexecutar o mesmo número de sandbox retorna "cached": true na segunda chamada. Altere o número (ou qualquer outro campo) para forçar uma consulta simulada nova.

Todos os Endpoints