Inizia
Crea una chiave di prova in Chiavi API, conservala sul tuo server e imposta FAIRVALID_API_KEY e FAIRVALID_BASE_URL. Le chiavi di prova funzionano con gli indirizzi riservati @example.com. Non effettuano chiamate al provider e non consumano crediti.
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"]}'Per la produzione, crea una chiave Live con ambito submit e usa /api/v1/jobs o /api/v1/verifications. Aggiungi l'ambito read per leggere lo stato e i risultati delle attività.
Un nuovo job restituisce HTTP 202 e un UUID job_id. Un nuovo tentativo corrispondente restituisce HTTP 200 con lo stesso job. Le risposte includono version: v1, brand: FairValid e intestazioni no-store.
Chiavi e limiti di spesa
Passa Authorization: Bearer fv_live_… o Bearer fv_test_… da un server. I segreti completi vengono mostrati una sola volta. Le chiavi live possono avere gli ambiti submit, read e balance. Una chiave revocata blocca le nuove richieste. Le chiavi di test accedono solo alle proprie attività simulate.
Il limite complessivo di una chiave live conteggia i crediti già scalati più quelli riservati per le identità univoche accettate. Non può aggiungere crediti al workspace. Una nuova richiesta oltre il limite restituisce HTTP 402 key_cap_reached senza creare un job né una riserva. Abbassare il limite blocca il nuovo lavoro; il lavoro già accettato prosegue.
I job live utilizzano la coda di verifica e il saldo crediti del tuo workspace. Restano validi gli ambiti delle chiavi, i limiti delle chiavi, l'accesso al workspace e i limiti di elaborazione. I crediti del workspace vengono riservati man mano che le verifiche sono ammesse all'elaborazione; i risultati seguono le stesse regole di consumo e restituzione della dashboard.
Durante una pausa operativa, un nuovo invio live può restituire HTTP 503 live_verification_unavailable senza trattenere crediti. Riprova più tardi con lo stesso Idempotency-Key.
Job e risultati
| Metodo | Percorso | Finalità |
|---|---|---|
POST | /api/v1/jobs | Invia da 1 a 5.000 indirizzi in JSON, fino a 2 MiB. |
POST | /api/v1/verifications | Invia un indirizzo reale oppure usa il simulatore originale per indirizzo singolo. |
GET | /api/v1/jobs/{id} | Leggi lo stato attuale del job e il riepilogo. |
GET | /api/v1/jobs/{id}/results | Leggi fino a 50 risultati e un cursore successivo firmato. |
POST | /api/v1/jobs/{id}/cancel | Richiedi l'annullamento; le attività in corso potrebbero essere completate. |
GET | /api/v1/balance | Leggi in tempo reale i crediti disponibili e bloccati del workspace. |
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"Passa next_cursor come parametro di query cursor. Contiene il filtro e la ricerca originali. I filtri sono all, valid, invalid, catch_all, unknown, still_checking e not_checked. Gli stati live dei risultati e dei crediti corrispondono all'istantanea della dashboard. Lo stato dell'attività può essere queued, running, paused, canceling, canceled o completed. Le attività di test restituiscono stati deterministici completed, pending, failed o cancelled.
Errori e nuovi tentativi sicuri
Invia un Idempotency-Key composto da 8 a 128 caratteri consentiti (lettere, cifre, punti, due punti, trattini bassi o trattini) a ogni invio di job e a ogni invio live di un singolo indirizzo. In caso di risposta incerta, ripeti la richiesta con la stessa chiave API, la stessa chiave di idempotenza e lo stesso corpo normalizzato. Il replay è limitato alla chiave API: sostituendo quella credenziale e reinviando la richiesta si può creare un’altra esecuzione. Riutilizzare la chiave di idempotenza con un corpo modificato restituisce HTTP 409 idempotency_conflict. Usa una nuova chiave solo quando intendi avviare una nuova esecuzione, che potrebbe consumare crediti.
HTTP 401 indica che la chiave è mancante, revocata o priva dell'ambito necessario. HTTP 422 riguarda indirizzi non validi o limiti della lista. I job bulk di test restituiscono HTTP 429 dopo 20 nuovi job per workspace all'ora o 100 ogni 30 giorni; i tentativi identici restituiscono comunque il job originale. HTTP 503 indica che la richiesta è temporaneamente non disponibile; un 503 dopo un invio dall'esito incerto non dimostra che il job non esista, quindi riprova con la stessa chiave di idempotenza. Gli errori contengono un codice, un messaggio e un ID richiesta.
Sandbox gratuita
Le chiavi di test accettano solo questi indirizzi: deliverable@example.com, undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com e error@example.com. Simulano i risultati valido, non valido, catch-all, sconosciuto, in sospeso e non disponibile. I job di test in blocco supportano stato, risultati, annullamento e replay senza intervenire sulla verifica reale o sul registro dei crediti.
I job sandbox in blocco e i relativi record di ripetizione vengono conservati per 30 giorni. Trascorso tale periodo, usa una nuova chiave di idempotenza per un nuovo test.
Il simulatore originale /api/v1/verifications per le chiavi di test usa la precedente versione di risposta 2026-10-01 e campi in camelCase. Usa /api/v1/jobs per il simulatore bulk con versioni.
Webhook firmati
I ruoli Proprietario e Manager configurano gli endpoint HTTPS per job.completed e job.canceled. Un ping di prova usa test.ping. I payload delle attività contengono un ID evento stabile, l'ID dell'attività, lo stato, un riepilogo privo di indirizzi, i conteggi dei crediti scalati/restituiti e un URL dei risultati. Non includono mai indirizzi email né dati del provider.
Leggi FairValid-Webhook-Id, FairValid-Webhook-Timestamp e FairValid-Webhook-Signature. La firma è fv1= seguito dall'HMAC-SHA256 esadecimale in minuscolo calcolato sui byte grezzi di fv1\n{event ID}\n{Unix timestamp}\nseguiti immediatamente dal corpo JSON grezzo. Usa un confronto a tempo costante. Rifiuta i timestamp che si discostano di oltre cinque minuti dal tuo orologio e deduplica in base all'ID evento in un archivio persistente.
Restituisci un qualsiasi codice 2xx entro 10 secondi. Le consegne non riuscite o incerte vengono ritentate fino a otto volte con lo stesso ID evento; consulta la cronologia degli ultimi 30 giorni o ripeti manualmente la consegna. I reindirizzamenti e le destinazioni private vengono rifiutati. Dopo la rotazione, i nuovi tentativi usano il nuovo segreto. Conserva il segreto precedente per 24 ore per verificare le firme dei tentativi in corso.
Esempi eseguibili
Il repository include packages/contracts/examples/job.mjse packages/contracts/examples/webhook-receiver.mjs. Esegui l'esempio di job con Node 22 e una chiave di test. Il ricevitore verifica i byte esatti del body raw e, durante la rotazione, sia il secret attuale sia quello precedente. Mettilo dietro HTTPS e sostituisci il suo set di ID evento in memoria con uno storage persistente e atomico prima dell'uso in produzione.
FAIRVALID_API_KEY=... FAIRVALID_BASE_URL=https://YOUR_FAIRVALID_HOST \
node packages/contracts/examples/job.mjs