API Reference

Open an inquiry

Create an inquiry from a published template.

Request

POST/api/v1/customer/inquiries

Opens an inquiry using a published template. Send the request from trusted backend infrastructure with your API key.

Headers

Name	Type	Required	Description
`X-Api-Key`	string	Required	Tenant-scoped key with a zk_live_ prefix and 32-character Base64URL secret.
`Idempotency-Key`	string	Optional	Optional non-empty string. A UUID v4 is strongly recommended.
`X-Correlation-Id`	string	Optional	Optional trace identifier. Zippy generates a UUID when omitted.

JSON body

Name	Type	Required	Description
`inquiryTemplateId`	uuid	Required	Canonical hyphenated UUID for a template owned by your tenant.
`templateRevisionId`	uuid	Optional	Published, enabled revision belonging to inquiryTemplateId. May be null.
`referenceId`	string	Optional	Optional merchant reference, up to 256 characters. Letters, numbers, and . _ : @ / - only. Empty or whitespace-only is treated as omitted.
`note`	string	Optional	Optional internal note, up to 500 characters. Letters, numbers, spaces, newlines, and . , ! ? ' " ( ) : ; - only. Empty or whitespace-only is treated as omitted.
`expiresAt`	date-time	Optional	Future ISO-8601 timestamp for the initial hosted verification expiry. May be null.

Field validation

Template identifiers

Both template identifiers must use canonical hyphenated UUID syntax. UUID version is not restricted, and uppercase or lowercase hexadecimal characters are accepted. A syntactically valid template outside your tenant is treated as not found.

When templateRevisionId is omitted, Zippy selects the enabled, published default revision. If none is configured, it uses the latest enabled, published revision. A supplied revision must belong to the selected template.

Merchant metadata

referenceId is optional (max 256). Allowed characters are letters, numbers, and these separators only: . _ : @ / -. Spaces, %, other punctuation, HTML/markup, and control characters are rejected. Empty or whitespace-only values are treated as omitted. Examples: ORD-12345, acme:ref_9, partner/abc-001 are accepted; order 123, ref%1, and id<script> are rejected.

note is optional (max 500). Allowed characters are letters, numbers, spaces, newlines, and . , ! ? ' " ( ) : ; -. Other symbols (for example %, _, #, &, <, >, @, /), tabs, carriage returns, HTML, and control characters are rejected. Empty or whitespace-only values are treated as omitted. Example accepted: Follow up with compliance.\nPriority: high. Rejected: Check cost < $5, note with % wildcard, or markdown/HTML tags.

Expiry

expiresAt must resolve to a future instant. If it is later than the inquiry expiry, Zippy reduces it to the inquiry expiry. When omitted, the template's configured verification TTL is used.

Idempotency

Generate one UUID v4 for each logical create operation and reuse it only when retrying the same request. The current server accepts any non-empty string, but it does not trim the value or enforce a maximum length or character allowlist.

Recommended header

http

Idempotency-Key: 83596f5e-2134-4e66-8304-20d61f290cf0

Same tenant, route, key, and payload: returns the existing inquiry.
Same key with a different payload: 409 IDEMPOTENCY_CONFLICT.
Reuse after the associated inquiry becomes terminal: 409 IDEMPOTENCY_CONFLICT.
Omitted and null optional values compare equally; empty strings differ from omitted values.
Textually different timestamps may produce different payload hashes even when they describe the same instant.

Response

201 response excerpt

json

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

Errors

Name	Type	Description
`400`	Bad Request	Malformed UUID, date-time, unknown property, or another validation failure.
`401`	Unauthorized	Missing, invalid, expired, or revoked API key.
`404`	Not Found	Template or revision was not found for this tenant.
`409`	Conflict	Revision conflict or idempotency key reused incompatibly.
`410`	Gone	expiresAt resolves to the current time or a past time.
`429`	Too Many Requests	Rate limit exceeded. Retry after the Retry-After duration.

Open Inquiry

curl -X POST "https://api.kyc.getzippy.app/api/v1/customer/inquiries" \
  -H "X-Api-Key: zk_live_REDACTED" \
  -H "X-Correlation-Id: merchant-request-123" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 83596f5e-2134-4e66-8304-20d61f290cf0" \
  --data '{
  "inquiryTemplateId": "bf3746ab-4bec-4b99-b0d7-5eb05769ab1e"
}'

Open Inquiry Response

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

Overview

Get an inquiry