Verificación de Teléfono

La Verificación de Teléfono comprueba que un número de teléfono realmente pertenece a la persona que lo declara, usando una consulta de identity-match del operador. Compara el nombre, la dirección y la fecha de nacimiento del remitente con los datos que el operador móvil tiene para ese número y devuelve una puntuación de coincidencia. Úsala como señal antifraude durante el onboarding o antes de una primera transacción.

Esta comprobación es diagnóstica y explícita — nunca se ejecuta automáticamente desde el flujo de transacción y nunca reescribe el número de teléfono almacenado del remitente. Llámala cuando quieras hacer una comprobación.

Verificar un Número de Teléfono

Endpoint: POST /organizations/{tenant}/v2/people/verifyPhone
Autenticación: A nivel de agente (x-api-key + x-agent-id + x-agent-api-key)

Hay dos modos de llamada mutuamente excluyentes:

⚠️ Los modos no pueden combinarse. Si envías personId, no debes enviar ningún campo de identidad inline, o la solicitud devuelve 422.

Modo Persona

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

El phoneNumber almacenado del remitente ya debe estar en formato E.164; de lo contrario, la solicitud devuelve 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 de la Solicitud

Cuantos más campos de identidad proporciones, más completo será el resultado de coincidencia.

Respuesta

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

Umbrales de Estado

status se deriva de summaryScore usando umbrales por tenant (predeterminados: MATCH ≥ 80, PARTIAL ≥ 40, por debajo → NO_MATCH). El estado se captura en el momento de la verificación — los cambios de umbral posteriores no reclasifican los resultados históricos. Contacta a Inyo para ajustar tus umbrales.

Caché

Las solicitudes idénticas se almacenan en caché por tenant durante 90 días, con clave en la tupla completa de entrada (número de teléfono, nombre, dirección, fecha de nacimiento). Un acierto de caché devuelve el resultado almacenado con "cached": true y no vuelve a facturar al proveedor de verificación. Varía cualquier campo de entrada para forzar una consulta nueva.

Respuestas de Error

Pruebas en Sandbox

En el sandbox, la verificación de teléfono no llama al proveedor real — sin facturación, sin consultas en vivo. En su lugar, el resultado se determina completamente por el último dígito del número de teléfono, de modo que puedes ejercitar cada rama eligiendo el número que envías:

Por ejemplo, +14145550002 devuelve MATCH y +14145550009 devuelve 502.

Como la clave de caché incluye el número de teléfono, reejecutar el mismo número de sandbox devuelve "cached": true en la segunda llamada. Cambia el número (o cualquier otro campo) para forzar una consulta simulada nueva.

Todos los Endpoints