Integration testing

Use the API Reference examples to test your integration.

Integration checklist

• API errors: handle documented error codes without interpreting message text as an age result. Stop automatic retries for invalid input, credentials, missing verifications, and idempotency conflicts. Respect a supplied Retry-After for HTTP 429 and bound retries with backoff and jitter. After a creation timeout or HTTP 503, retry the same key and body; do not assume creation failed or issue a new key. Unknown codes do not establish an age result.
• Evaluation dates: cover explicit today, tomorrow, and a far-future date, using UTC civil-date boundaries. Omission resolves to the UTC date of original creation. Past dates, invalid calendar dates or formats, null, and wrong JSON types return HTTP 400.
• Creation retries: the same Idempotency-Key and body return the same verification without duplicate effects. Retry an omitted-date request across UTC midnight and require the original resolved evaluation_date. Reusing the key with a changed evaluation_date, or any other changed body field, returns HTTP 409.
• Results: handle yes, no, and unsure. Failed, cancelled, expired, and unsupported checks return unsure, never no. Pending checks have null results; initial current assessments are clear, even for unsure.
• Date consistency: creation, exact retries, lookup, completion and status-change events, and event-feed entries expose the same non-null evaluation_date. Test age boundaries against that date, while checking document validity at the actual verification time.
• Later concerns: a newer assessment updates current without changing original. Handle needs_review as a concern to assess, not proof that the person is under the age threshold.
• Repeated or reordered events: deliver both event types twice and out of order. Business actions run once; older revisions cannot replace newer state. Conflicting duplicates require reconciliation.
• Endpoint verification: configure an endpoint and respond to ZeroAge’s ownership challenge using the webhook verification secret. A correct response verifies the endpoint; an incorrect or missing response does not.
• Webhook receipt: validate the event envelope and durably save it before returning HTTP 200, 204, or another 2xx response. Confirm that the response marks receipt only and that asynchronous business processing can finish after it.
• Webhook retries: simulate persistence failures, a timeout, a non-2xx response, and a lost 2xx response. Verify that automatic retries use increasing delays, preserve the event ID and payload, and do not repeat business effects.
• Invalid payloads: reject missing fields, contradictory results, mismatched IDs/revisions, and conflicting original decisions before business processing. Unknown contract values need review.
• Recovery: restart the receiver and simulate network or downstream failures. Keep saved events, resume processing, and reconcile through verification lookup without losing or repeating business actions. If the integration uses the optional event feed, also retain its cursor and test page recovery.
• Customer isolation: keep credentials, data, and cursors separate. Another customer’s verification, events, and webhook configuration must remain inaccessible.
• Sensitive data: the handoff URL belongs only in creation responses and exact retries. Keep it out of lookup, events, and logs. Customer payloads must omit document identity fields and proof evidence. Keep personal data out of echoed customer references.

See Results and revisions and Webhooks and recovery for the handling rules behind this checklist.