Referencia de la API de verificación de correo

Empezar

Crea una clave de prueba en Claves de API, guárdala en tu servidor y configura FAIRVALID_API_KEY y FAIRVALID_BASE_URL. Las claves de prueba funcionan con direcciones reservadas de @example.com. No realizan llamadas al proveedor ni consumen créditos.

curl -X POST "$FAIRVALID_BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY" \
  -H "Idempotency-Key: my-import-2026-10-05" \
  -H "Content-Type: application/json" \
  -d '{"emails":["deliverable@example.com","pending@example.com"]}'

Para producción, crea una clave Live con el ámbito submit y usa /api/v1/jobs o /api/v1/verifications. Añade el ámbito read para leer el estado y los resultados de los trabajos.

Un trabajo nuevo devuelve HTTP 202 y un UUID job_id. Un reintento coincidente devuelve HTTP 200 con el mismo trabajo. Las respuestas incluyen version: v1, brand: FairValid y encabezados no-store.

Claves y límites de gasto

Pasa Authorization: Bearer fv_live_… o Bearer fv_test_… desde un servidor. Los secretos completos solo se muestran una vez. Las claves en vivo pueden tener los ámbitos submit, read y balance. Una clave revocada deja de aceptar nuevas solicitudes. Las claves de prueba acceden a sus propios trabajos simulados.

El límite total de una clave en vivo cuenta los créditos ya descontados más los créditos reservados para identidades únicas aceptadas. No puede añadir créditos al espacio de trabajo. Una nueva solicitud que supere el límite devuelve HTTP 402 key_cap_reached sin crear un trabajo ni una retención. Reducir el límite bloquea trabajo nuevo; el trabajo aceptado continúa.

Los trabajos en vivo usan la cola de verificación y el saldo de créditos de tu espacio de trabajo. Siguen aplicándose los alcances y límites de las claves, el acceso al espacio de trabajo y los límites de procesamiento. Los créditos del espacio de trabajo se reservan a medida que se admiten comprobaciones para su procesamiento; los resultados siguen las mismas reglas de consumo y devolución que el panel.

Durante una pausa operativa, un nuevo envío en vivo puede devolver HTTP 503 live_verification_unavailable sin retener créditos. Vuelve a intentarlo más tarde con el mismo Idempotency-Key.

Trabajos y resultados

Método	Ruta	Finalidad
`POST`	`/api/v1/jobs`	Envía de 1 a 5,000 direcciones en JSON, hasta 2 MiB.
`POST`	`/api/v1/verifications`	Envía una dirección real o usa el simulador original de dirección individual.
`GET`	`/api/v1/jobs/{id}`	Consulta el estado actual del trabajo y su resumen.
`GET`	`/api/v1/jobs/{id}/results`	Obtén hasta 50 resultados y un cursor siguiente firmado.
`POST`	`/api/v1/jobs/{id}/cancel`	Solicita la cancelación; las tareas en curso pueden completarse.
`GET`	`/api/v1/balance`	Consulta en tiempo real los créditos disponibles y retenidos del espacio de trabajo.

curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"
curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID/results" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"

Pasa next_cursor como parámetro de consulta cursor. Conserva el filtro y la búsqueda originales. Los filtros son all, valid, invalid, catch_all, unknown, still_checking y not_checked. Los estados de resultados y créditos en vivo coinciden con la instantánea del panel. El estado del trabajo puede ser queued, running, paused, canceling, canceled o completed. Los trabajos de prueba devuelven estados deterministas completed, pending, failed o cancelled.

Errores y reintentos seguros

Envía una Idempotency-Key de 8 a 128 caracteres permitidos (letras, dígitos, puntos, dos puntos, guiones bajos o guiones) en cada envío de trabajo y en cada envío de una sola dirección en vivo. Reintenta una respuesta incierta con la misma clave de API, la misma clave de idempotencia y el mismo cuerpo normalizado. La repetición está limitada a la clave de API; si sustituyes esa credencial y vuelves a enviar, puede crearse otra ejecución. Reutilizar la clave de idempotencia con un cuerpo modificado devuelve HTTP 409 idempotency_conflict. Usa una clave nueva solo cuando quieras una ejecución nueva que puede consumir créditos.

HTTP 401 significa que falta la clave, que se ha revocado o que no tiene el alcance necesario. HTTP 422 corresponde a direcciones no válidas o a límites de lista. Los trabajos masivos de prueba devuelven HTTP 429 después de 20 trabajos nuevos por espacio de trabajo por hora o 100 cada 30 días; los reintentos idénticos siguen devolviendo el trabajo original. HTTP 503 significa que la solicitud no está disponible temporalmente; un 503 tras un envío incierto no demuestra que el trabajo no exista, así que vuelve a intentarlo con la misma clave de idempotencia. Los errores incluyen un código, un mensaje y un ID de solicitud.

Sandbox gratuito

Las claves de prueba solo aceptan estas direcciones: deliverable@example.com, undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com y error@example.com. Simulan resultados válidos, no válidos, catch-all, desconocidos, pendientes y no disponibles. Los trabajos masivos de prueba admiten estado, resultados, cancelación y repetición sin afectar a la verificación real ni al registro de créditos.

Los trabajos masivos de sandbox y sus registros de repetición se conservan durante 30 días. Pasado ese plazo, usa una nueva clave de idempotencia para una nueva prueba.

El simulador original de claves de prueba /api/v1/verifications utiliza su versión de respuesta anterior 2026-10-01 y campos en camelCase. Usa /api/v1/jobs para el simulador masivo con versiones.

Webhooks firmados

Los roles de propietario y gestor configuran endpoints HTTPS para job.completed y job.canceled. Un ping de prueba usa test.ping. Las cargas útiles de los trabajos contienen un ID de evento estable, el ID del trabajo, el estado, un resumen sin direcciones, los recuentos de créditos descontados/devueltos y una URL de resultados. Nunca incluyen direcciones de correo electrónico ni datos del proveedor.

Lee FairValid-Webhook-Id, FairValid-Webhook-Timestamp y FairValid-Webhook-Signature. La firma es fv1= seguido del hexadecimal HMAC-SHA256 en minúsculas calculado sobre los bytes sin procesar de fv1\n{event ID}\n{Unix timestamp}\nseguidos inmediatamente del cuerpo JSON sin procesar. Usa una comparación de tiempo constante. Rechaza las marcas de tiempo que difieran más de cinco minutos de tu reloj y elimina duplicados por ID de evento en un almacenamiento persistente.

Devuelve cualquier código 2xx en un plazo de 10 segundos. Los envíos fallidos o inciertos se reintentan hasta ocho veces con el mismo ID de evento; consulta el historial de 30 días o reenvíalos manualmente. Se rechazan las redirecciones y los destinos privados. Tras la rotación, los nuevos intentos usan el nuevo secreto. Conserva el secreto anterior durante 24 horas para verificar las firmas de los intentos en curso.

Ejemplos ejecutables

El repositorio incluye packages/contracts/examples/job.mjsy packages/contracts/examples/webhook-receiver.mjs. Ejecuta el ejemplo de trabajo con Node 22 y una clave de prueba. El receptor verifica los bytes exactos del cuerpo sin procesar y tanto el secreto actual como el anterior durante la rotación. Colócalo detrás de HTTPS y sustituye su conjunto de ID de eventos en memoria por un almacenamiento atómico persistente antes de usarlo en producción.

FAIRVALID_API_KEY=... FAIRVALID_BASE_URL=https://YOUR_FAIRVALID_HOST \
  node packages/contracts/examples/job.mjs