Concepts
Core concepts
Understand tenants, templates, inquiries, and idempotency.
Tenant
A tenant is your organization in Zippy. API keys, templates, inquiries, webhooks, and portal users are scoped to the tenant.
Templates and revisions
An inquiry template defines verification steps, review policy, expiry, and webhook subscriptions. Revisions are versioned as DRAFT, PUBLISHED, or ARCHIVED. Opening an inquiry pins a published (and enabled) revision.
Inquiries
An inquiry is the durable verification case. Use its identifier to read status and retrieve approved documents.
| Name | Type | Description |
|---|---|---|
openedSource | enum | API_KEY or PORTAL_LINK. |
referenceId | string | Merchant reference (not legacy customer_ref). |
inquiryTemplateId | uuid | Published template used to open the inquiry. |
templateRevisionId | uuid | Optional pin; otherwise default/latest enabled published revision. |
Idempotency
You may send Idempotency-Key when opening an inquiry. Use one UUID v4 for a logical operation and keep it unchanged when retrying the same payload.
Hosted inquiry URL
Pattern: {INQUIRY_HOSTED_BASE_URL}/i/{inquiryId}. Configure the hosted base URL in backend environment; it is not a marketing vanity domain unless your deployment sets it that way. Effective inquiry expiry comes from the pinned template revision.