Build

Merchant Inquiry API

Open inquiries, read status, and retrieve documents for approved or needs-review inquiries.

Merchant routes use X-Api-Key under /api/v1/customer/inquiries.

Open an inquiry

POST/api/v1/customer/inquiries

Name	Type	Required	Description
`inquiryTemplateId`	uuid	Required	Published template.
`templateRevisionId`	uuid	Optional	Optional published+enabled revision pin.
`referenceId`	string<=256	Optional	Merchant reference. Letters, numbers, and . _ : @ / - only.
`note`	string<=500	Optional	Internal note. Letters, numbers, spaces, newlines, and . , ! ? ' " ( ) : ; - only.
`expiresAt`	ISO-8601	Optional	Future hosted verification expiry, capped by inquiry expiry.
`Idempotency-Key`	header	Optional	UUID v4 recommended for safe retries.
`X-Correlation-Id`	header	Optional	Optional request trace identifier.

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"
  }'

Response excerpt

json

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

Get status

GET/api/v1/customer/inquiries/:inquiryId

Returns lifecycle status and merchant metadata. When status is APPROVED, NEEDS_REVIEW, or FAILED, the body may include an optional identity object (personal info and extracted ID document data). Full field reference is under Get an inquiry.

curl "https://api.kyc.getzippy.app/api/v1/customer/inquiries/96b1f81d-87cd-4a71-8bc4-e2718bcd6097" \
  -H "X-Api-Key: zk_live_REDACTED" \
  -H "X-Correlation-Id: merchant-request-123"

Response — mid-flow

json

{
  "inquiryId": "96b1f81d-87cd-4a71-8bc4-e2718bcd6097",
  "status": "PENDING",
  "reviewReasons": [],
  "portalDecisionNote": null,
  "portalDecidedAt": null,
  "referenceId": "customer-84721",
  "note": "Verify before enabling withdrawals.",
  "openedAt": "2026-07-18T08:15:30.000Z",
  "expiresAt": "2026-07-19T08:15:30.000Z",
  "inquiryTemplateId": "bf3746ab-4bec-4b99-b0d7-5eb05769ab1e"
}

Response — APPROVED with identity and addressDetails

json

{
  "inquiryId": "96b1f81d-87cd-4a71-8bc4-e2718bcd6097",
  "status": "APPROVED",
  "reviewReasons": [
    "Manual review required: the name on the identity document does not match the name entered in personal info."
  ],
  "portalDecisionNote": "Looks good",
  "portalDecidedAt": "2026-07-18T09:00:00.000Z",
  "referenceId": "customer-84721",
  "note": "Verify before enabling withdrawals.",
  "openedAt": "2026-07-18T08:15:30.000Z",
  "expiresAt": "2026-07-19T08:15:30.000Z",
  "inquiryTemplateId": "bf3746ab-4bec-4b99-b0d7-5eb05769ab1e",
  "identity": {
    "personalInfo": {
      "fullName": "Jane Marie Doe",
      "country": "US",
      "email": "jane@example.com",
      "phone": "+14155552671"
    },
    "document": {
      "documentType": "DRIVING_LICENSE",
      "fullName": "Jane Marie Doe",
      "dateOfIssue": "12-01-2020",
      "dateOfBirth": "15-03-1990",
      "dateOfExpiry": "11-01-2030",
      "documentNumber": "D12345678",
      "sex": "F",
      "address": "96 Henry St Fl 1, Hartford, CT, 06114-1736, US",
      "addressDetails": {
        "street": "96 Henry St Fl 1",
        "city": "Hartford",
        "state": "CT",
        "postalCode": "06114-1736",
        "country": "US"
      }
    }
  }
}

Retrieve documents

GET/api/v1/customer/inquiries/:inquiryId/documents

cURL

bash

curl "https://api.kyc.getzippy.app/api/v1/customer/inquiries/96b1f81d-87cd-4a71-8bc4-e2718bcd6097/documents" \
  -H "X-Api-Key: zk_live_REDACTED" \
  -H "X-Correlation-Id: merchant-request-123"

Response

json

{
  "inquiryId": "96b1f81d-87cd-4a71-8bc4-e2718bcd6097",
  "status": "NEEDS_REVIEW",
  "urlExpiresAt": "2026-07-18T09:05:00.000Z",
  "documents": [
    {
      "type": "passport",
      "supportedPageTypes": ["frontPage"],
      "frontPage": "https://storage.example.com/kyc/passport.jpg?sv=...&sig=..."
    },
    {
      "type": "selfie",
      "frontPage": "https://storage.example.com/kyc/selfie.jpg?sv=...&sig=..."
    },
    {
      "type": "signature",
      "frontPage": "https://storage.example.com/kyc/signature.jpg?sv=...&sig=..."
    }
  ]
}

Common failures

Opening with a draft/unpublished template revision.
Fetching documents when status is not APPROVED or NEEDS_REVIEW.
Using an inquiry identifier that belongs to another tenant.

Inquiry lifecycle

Web SDK overview