API Reference

Get inquiry documents

Retrieve short-lived document URLs for APPROVED or NEEDS_REVIEW inquiries.

Request

GET/api/v1/customer/inquiries/{inquiryId}/documents

Returns short-lived document URLs for an inquiry in APPROVED or NEEDS_REVIEW.

Headers and path

Name	Type	Required	Description
`X-Api-Key`	header	Required	Tenant-scoped key with a zk_live_ prefix and 32-character Base64URL secret.
`X-Correlation-Id`	header	Optional	Optional trace identifier. Zippy generates a UUID when omitted.
`inquiryId`	uuid	Required	Canonical hyphenated UUID for an inquiry in APPROVED or NEEDS_REVIEW.

Validation and access

inquiryId must be a canonical hyphenated UUID; UUID version is not restricted.
The inquiry must belong to the API key's tenant.
Status must be APPROVED or NEEDS_REVIEW. Every other status, including COMPLETED, FAILED, and DECLINED, is rejected with INQUIRY_NOT_APPROVED.
Generated document URLs remain valid for five minutes.

Response

200 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=..."
    }
  ]
}

Response fields

Name	Type	Description
`inquiryId`	uuid	Inquiry identifier.
`status`	APPROVED \| NEEDS_REVIEW	Inquiry status at retrieval time.
`urlExpiresAt`	date-time	Expiry shared by the returned temporary URLs.
`documents`	array	Newest successful artifact for each eligible verification capability.
`documents[].type`	enum	passport, national_id, driving_license, selfie, or signature.
`supportedPageTypes`	string[]	Available page names for document types that support pages.
`frontPage`	URL	Temporary URL for the front or primary artifact.
`backPage`	URL	Temporary URL for the back image; omitted when unavailable.

Document types

Name	Type	Description
`passport`	document	supportedPageTypes: ["frontPage"]
`national_id`	document	supportedPageTypes: ["frontPage", "backPage"]
`driving_license`	document	supportedPageTypes: ["frontPage", "backPage"]
`selfie`	image	No supportedPageTypes field.
`signature`	image	No supportedPageTypes field.

Types without a successful scanned artifact are omitted. The documents array can therefore be empty even for an eligible inquiry when no artifact URL can be generated.

Errors

Name	Type	Description
`400`	Bad Request	inquiryId is not a canonical UUID.
`401`	Unauthorized	Missing, invalid, expired, or revoked API key.
`403`	Forbidden	Documents are not available for this status (code: INQUIRY_NOT_APPROVED).
`404`	Not Found	Inquiry does not exist or is outside the key's tenant.
`429`	Too Many Requests	Rate limit exceeded. Retry after the Retry-After duration.

Get Inquiry Documents

curl -X GET "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"

Get Inquiry Documents Response

{
  "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=..."
    }
  ]
}

Get an inquiry

Webhooks overview