Developer Guide
Best practices for verification, authorization, grounding, and job handling.
What this guide covers
Requests and patterns for verification and authorization endpoints, error handling, polling jobs, batch verification, and operational best practices.
1. Request patterns
Verification APIs may return either synchronous results or a job identifier for asynchronous processing. Choose the pattern that matches your latency and throughput requirements.
Synchronous
Client sends a request and receives a 200 response containing result fields. Still check the errors array for domain-level issues.
Asynchronous (job-returning)
Client receives an HTTP 200 with a job_id. Poll GET /v2/jobs/{job_id} to obtain status and results.
2. Error model
The API uses HTTP status codes for transport/auth/validation issues and a structured errors array for domain/processing problems. Always check both.
HTTP codes (e.g. 4xx/5xx) indicate transport, authentication, or validation failures. Handle them as unretriable or retriable depending on the code.
Domain errors are returned in the errors array even on HTTP 200. Inspect the array for partial failures or item-level errors.
Handling partial failures
For batch or multi-item requests, treat the errors array as authoritative for item-level failures. Implement idempotency or compensating logic for retries.
3. Polling jobs
Use GET /v2/jobs/{job_id} to check status, progress, results, and errors for asynchronous tasks.
Status: expected values include queued, processing, completed, and failed.
Progress & results: job responses may include progress metadata and a result field when complete. Always verify errors before trusting result contents.
Error handling: if a job is failed, read the job-level errors and decide whether to retry, fail, or surface to operators.
Polling guidance
- Use exponential backoff when polling to reduce load.
- Set an overall timeout to avoid infinite polling loops.
- Cache completed results to avoid repeated polls.
4. Batch verification
For high-throughput verification, use a batch endpoint such as POST /v1/verify-claims-batch. Batches typically return a single job_id to poll for results.
The batch response includes counts and may include item-level errors in the job result. Treat batch submission as best-effort and use idempotency keys when available.
Limits & billing
Limits and billing vary by plan. See pricing or contact support for details.
5. Operational best practices
Idempotency
Use idempotency keys for requests that may be retried to avoid duplicate processing when supported.
Retries and backoff
Retry transient failures with exponential backoff and capped retries. Avoid retrying permanent errors.
Rate limits
Respect rate limits returned by the API and implement client-side throttling when needed.
Observability
Log request IDs, job IDs, errors, and key metadata. Track success/failure rates and latency for verification flows.