Getting started

• Portal access to create templates, API keys, and webhooks.
• An HTTPS endpoint that can accept Zippy webhook POSTs.
• Backend ability to store secrets securely (API key + webhook signing secret).

1. Create a portal account / tenant and invite operators as needed.
2. Create and publish an inquiry template. Set verification steps and definition.webhooks.subscribe for live events.
3. Create an API key under Developer → API Keys. Plaintext is shown once as zk_live_....
4. Register an HTTPS webhook endpoint. Store the one-time whsec_... signing secret.

curl -X POST "https://api.kyc.getzippy.app/api/v1/customer/inquiries" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: zk_live_REDACTED" \
  -H "Idempotency-Key: 83596f5e-2134-4e66-8304-20d61f290cf0" \
  -H "X-Correlation-Id: merchant-request-123" \
  -d '{
    "inquiryTemplateId": "bf3746ab-4bec-4b99-b0d7-5eb05769ab1e",
    "templateRevisionId": "4d1ba7b9-368f-448f-a788-c5ca033db248",
    "referenceId": "customer-84721",
    "note": "Verify before enabling withdrawals.",
    "expiresAt": "2026-07-19T14:30:00.000Z"
  }'

{
  "inquiryId": "96b1f81d-87cd-4a71-8bc4-e2718bcd6097"
}

Store the returned inquiryId with your merchant reference. Pass it to @zippykyc/web-sdk to open the hosted verification experience in your application.

The customer completes the configured identity checks in the hosted Zippy flow. Your backend does not submit verification steps through the API-key surface.

Prefer webhooks (inquiry.approved, inquiry.review_in_progress, inquiry.declined) and poll GET /api/v1/customer/inquiries/:inquiryId as a backup. When status is APPROVED, NEEDS_REVIEW, or FAILED, that response may include an optional identity snapshot. Fetch document image URLs when status is APPROVED or NEEDS_REVIEW.

• Sending the API key under a header other than X-Api-Key.
• Webhook URL not HTTPS, or template missing event subscribe list.
• Verifying a re-serialized JSON body instead of the exact raw bytes.
• Calling documents when status is not APPROVED or NEEDS_REVIEW → INQUIRY_NOT_APPROVED.