Production checklist

Go through this checklist before your integration goes to production.

Before go-live

• Store API keys server-side or in a secure secrets manager. See Authentication.
• Log metadata.requestId for every request so support can trace issues quickly.
• Monitor quotas.workspace.credits.left and quotas.workspace.minuteRateLimit.left from the Usage endpoint.
• Route async workflows through a durable webhook receiver, not a manual test endpoint.
• Make webhook processing idempotent by deduplicating on webhookId. See Webhooks.

Request safety

• Use timeouts on every outbound request. On a long poll (GET /v2/webhooks/:webhookId?wait=20), keep the timeout above the wait value, for example 30 seconds. See Polling.
• Retry only 429 and 5xx with exponential backoff. See Error handling.
• Send an Idempotency-Key header on Find Email and Find Phone, and send the same key when you retry, so a lost response never starts and bills a second lookup.
• On a 429, wait the number of seconds in error.details.retryAfter before retrying.
• Treat 4xx validation or auth failures as permanent until you change the input or credentials.

Webhook safety

• Use HTTPS for every production webhook URL.
• Return 200 quickly, then process heavy work asynchronously.
• Validate that each callback contains webhookId + data or webhookId + errorCode. See Webhook payload.
• Deduplicate on webhookId to handle rare duplicate deliveries.

Monitoring & alerts

• Alert on repeated 401, 402, 429, and 5xx responses.
• Surface credit exhaustion before it blocks critical workflows. See Credits.
• Keep one smoke test for a sync endpoint and one for an async endpoint (see below).
• Document which team owns API key rotation, webhook incidents, and quota alerts.

Recommended smoke tests

1. GET /v2/usage returns 200 and a valid quotas object.
2. POST /v2/fetch/persons/check returns 200 with creditsConsumed: 0.
3. One async endpoint returns an immediate response and the result is delivered to your webhook URL.
4. Your application logs both the outbound request and the webhook completion using the same requestId or webhookId.

You're ready to go live

When every item above is in place, the integration is ready for production traffic.