Kom igång
Skapa en testnyckel under API-nycklar, förvara den på din server och ange FAIRVALID_API_KEY och FAIRVALID_BASE_URL. Testnycklar fungerar med reserverade @example.com-adresser. De gör inga anrop till leverantören och använder inga krediter.
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"]}'För produktion skapar du en live-nyckel med behörigheten submit och använder /api/v1/jobs eller /api/v1/verifications. Lägg till behörigheten read för att läsa jobbstatus och resultat.
Ett nytt jobb returnerar HTTP 202 och ett UUID job_id. Ett matchande nytt försök returnerar HTTP 200 med samma jobb. Svaren innehåller version: v1, brand: FairValid och no-store-headers.
Nycklar och utgiftstak
Skicka Authorization: Bearer fv_live_… eller Bearer fv_test_… från en server. Fullständiga hemligheter visas bara en gång. Live-nycklar kan ha behörigheterna submit, read och balance. En återkallad nyckel stoppar nya förfrågningar. Testnycklar har åtkomst till sina egna simulerade jobb.
En livenyckels totala tak räknar krediter som redan debiterats plus krediter som reserverats för godkända unika identiteter. Det kan inte lägga till krediter i arbetsytan. En ny begäran över taket returnerar HTTP 402 key_cap_reached utan att skapa ett jobb eller en reservation. Att sänka taket blockerar nytt arbete; godkänt arbete fortsätter.
Livejobb använder arbetsytans verifieringskö och kreditsaldo. Nyckelbehörigheter, nyckeltak, åtkomst till arbetsytan och bearbetningsgränser gäller fortfarande. Arbetsytans krediter reserveras när kontroller tas in för bearbetning; resultaten följer samma regler för debitering och återföring som i instrumentpanelen.
Under ett driftuppehåll kan en ny liveförfrågan returnera HTTP 503 live_verification_unavailable utan att krediter reserveras. Försök igen senare med samma Idempotency-Key.
Jobb och resultat
| Metod | Sökväg | Syfte |
|---|---|---|
POST | /api/v1/jobs | Skicka 1 till 5 000 adresser i JSON, upp till 2 MiB. |
POST | /api/v1/verifications | Skicka en riktig adress eller använd den ursprungliga simulatorn för enskilda adresser. |
GET | /api/v1/jobs/{id} | Läs jobbets aktuella status och sammanfattning. |
GET | /api/v1/jobs/{id}/results | Läs upp till 50 resultat och en signerad nästa-markör. |
POST | /api/v1/jobs/{id}/cancel | Begär avbrytande; pågående arbete kan slutföras. |
GET | /api/v1/balance | Läs arbetsytans aktuella tillgängliga och reserverade krediter. |
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"Skicka next_cursor som frågeparametern cursor. Den bär med sig det ursprungliga filtret och sökningen. Filtren är all, valid, invalid, catch_all, unknown, still_checking och not_checked. Live-status för resultat och krediter motsvarar ögonblicksbilden i instrumentpanelen. Jobbstatus kan vara queued, running, paused, canceling, canceled eller completed. Testjobb returnerar deterministiska statusar: completed, pending, failed eller cancelled.
Fel och säkra nya försök
Skicka en Idempotency-Key på 8 till 128 tillåtna bokstäver, siffror, punkter, kolon, understreck eller bindestreck med varje jobbinskick och varje live-inskick av en enskild adress. Skicka om begäran vid ett osäkert svar med samma API-nyckel, idempotensnyckel och normaliserade body. Återspelning är avgränsad till API-nyckeln; om du byter ut den inloggningsuppgiften och skickar in igen kan en ny körning skapas. Om idempotensnyckeln återanvänds med en ändrad body returneras HTTP 409 idempotency_conflict. Använd en ny nyckel endast när du avser en ny körning som kan förbruka krediter.
HTTP 401 betyder att nyckeln saknas, har återkallats eller saknar behörighet. HTTP 422 gäller ogiltiga adresser eller listgränser. Massjobb i testläge returnerar HTTP 429 efter 20 nya jobb per arbetsyta per timme eller 100 per 30 dagar; identiska nya försök returnerar fortfarande det ursprungliga jobbet. HTTP 503 betyder att begäran tillfälligt inte är tillgänglig; ett 503-svar efter en osäker inskickning visar inte att jobbet saknas, så försök igen med samma idempotensnyckel. Fel innehåller en kod, ett meddelande och ett förfrågnings-ID.
Gratis sandlåda
Testnycklar accepterar endast dessa adresser: deliverable@example.com, undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com och error@example.com. De simulerar utfallen giltig, ogiltig, catch-all, okänd, väntande och otillgänglig. Massjobb i testläge stöder status, resultat, avbrytning och omspelning utan att påverka den skarpa verifieringen eller kreditreskontran.
Sandlådejobb i bulk och deras återuppspelningsposter sparas i 30 dagar. Använd därefter en ny idempotensnyckel för ett nytt test.
Den ursprungliga /api/v1/verifications-simulatorn för testnycklar använder sin tidigare svarsversion 2026-10-01 och fält i camelCase. Använd /api/v1/jobs för den versionerade massimulatorn.
Signerade webhooks
Rollerna Ägare och Chef konfigurerar HTTPS-slutpunkter för job.completed och job.canceled. En testping använder test.ping. Jobbets nyttolast innehåller ett stabilt händelse-ID, jobb-ID, status, en sammanfattning utan adresser, antal debiterade/återförda krediter och en resultat-URL. De innehåller aldrig e-postadresser eller leverantörsdata.
Läs FairValid-Webhook-Id, FairValid-Webhook-Timestamp och FairValid-Webhook-Signature. Signaturen är fv1= följt av HMAC-SHA256 i hexadecimal form med gemener, beräknad över de råa byten i fv1\n{event ID}\n{Unix timestamp}\ndirekt följt av den råa JSON-brödtexten. Använd en jämförelse i konstant tid. Avvisa tidsstämplar som avviker mer än fem minuter från din klocka och deduplicera efter händelse-ID i beständig lagring.
Returnera valfri 2xx inom 10 sekunder. Misslyckade eller osäkra leveranser görs om upp till åtta gånger med samma händelse-ID; granska 30 dagars historik eller leverera om manuellt. Omdirigeringar och privata destinationer nekas. Efter rotering använder nya försök den nya hemligheten. Behåll den tidigare hemligheten i 24 timmar för att verifiera signaturer från pågående försök.
Körbara exempel
Kodförrådet innehåller packages/contracts/examples/job.mjsoch packages/contracts/examples/webhook-receiver.mjs. Kör jobbexemplet med Node 22 och en testnyckel. Mottagaren verifierar exakta råa byte i brödtexten samt både nuvarande och tidigare hemlighet under rotation. Placera HTTPS framför den och ersätt dess minnesbaserade mängd av händelse-ID:n med ett beständigt, atomärt lager innan den används i produktion.
FAIRVALID_API_KEY=... FAIRVALID_BASE_URL=https://YOUR_FAIRVALID_HOST \
node packages/contracts/examples/job.mjs