API Reference

Get an inquiry

Read the current status, metadata, and optional identity snapshot for an inquiry.

Request

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

Returns the current lifecycle status and merchant-facing metadata for an inquiry belonging to your tenant. When the status is APPROVED, NEEDS_REVIEW, or FAILED, the response also includes an optional identity snapshot (personal information and extracted ID document data).

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 returned when the inquiry was opened.

Path validation

inquiryId must match the canonical hyphenated UUID shape. UUID version is not restricted. A malformed value such as inquiry-123 returns 400 HTTP_400.

A valid UUID that does not belong to the API key's tenant returns 404 INQUIRY_NOT_FOUND. This prevents cross-tenant inquiry discovery.

Response

Use this endpoint for inquiry-level state and metadata. Prefer webhooks for decisions and poll this endpoint only as a recovery path. Treat identity as optional: check whether the key is present, then handle nested branches that may still be null.

When identity is present

Name	Type	Description
`APPROVED`	identity present	Top-level identity object is included. personalInfo or document may still each be null.
`NEEDS_REVIEW`	identity present	Top-level identity object is included with the same branch rules as APPROVED.
`FAILED`	identity present	Top-level identity object is included with the same branch rules as APPROVED.
`Other statuses`	identity omitted	CREATED, PENDING, COMPLETED, EXPIRED, DECLINED, PURGED, and other values omit the identity key entirely (not returned as null).

200 — mid-flow (no identity)

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

200 — NEEDS_REVIEW (with identity and addressDetails)

json

{
  "inquiryId": "96b1f81d-87cd-4a71-8bc4-e2718bcd6097",
  "status": "NEEDS_REVIEW",
  "reviewReasons": [
    "Face match confidence is below the automatic approval threshold"
  ],
  "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",
  "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"
      }
    }
  }
}

200 — 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"
      }
    }
  }
}

Top-level response fields

Name	Type	Description
`inquiryId`	uuid	Identifier used by subsequent inquiry requests.
`status`	enum	Current inquiry lifecycle status.
`reviewReasons`	string[]	Why the inquiry needed manual review. Retained after a later portal approve or decline. Empty array or missing means none stored.
`portalDecisionNote`	string \| null	Note from the latest portal approve or decline.
`portalDecidedAt`	date-time \| null	UTC timestamp of the latest portal decision.
`referenceId`	string \| null	Merchant-provided reference.
`note`	string \| null	Merchant-provided internal note.
`openedAt`	date-time	Inquiry creation timestamp.
`expiresAt`	date-time	Inquiry lifetime expiry.
`inquiryTemplateId`	uuid	Template pinned to this inquiry.
`identity`	object	Personal info and extracted document data. Present only when status is APPROVED, NEEDS_REVIEW, or FAILED. Omitted for all other statuses.

Identity snapshot

When present, identity has two branches. Each may be null if that step never completed successfully.

identity

Name	Type	Description
`personalInfo`	object \| null	Latest successful personal-information step. Null when personal info was never completed successfully.
`document`	object \| null	Extracted fields from the latest successful ID scan (passport, national ID, or driving licence). Null when no successful ID scan exists.

identity.personalInfo

Name	Type	Description
`fullName`	string	Customer-submitted full name.
`country`	string	ISO 3166-1 alpha-2 country code (for example "US" or "IN").
`email`	string \| null	When collected by the template; otherwise null.
`phone`	string \| null	E.164 phone number when collected; otherwise null.

identity.document

Name	Type	Description
`documentType`	enum	PASSPORT, NATIONAL_ID, or DRIVING_LICENSE.
`fullName`	string \| null	Name read from the document. Field name is fullName (not name).
`dateOfIssue`	string \| null	Issue date. Prefer DD-MM-YYYY when parseable; may not be ISO-8601.
`dateOfBirth`	string \| null	Date of birth. Prefer DD-MM-YYYY when parseable; may not be ISO-8601.
`dateOfExpiry`	string \| null	Expiry date. Prefer DD-MM-YYYY when parseable; may not be ISO-8601.
`documentNumber`	string \| null	Document, passport, or licence number.
`sex`	string \| null	Sex or gender marker when present (for example "M" or "F").
`address`	string \| null	Display address line built by Zippy (see address rules below).
`addressDetails`	object \| null	Structured address from the document when components are available.

identity.document.addressDetails

Name	Type	Description
`street`	string \| null	Street line from the document.
`city`	string \| null	City from the document.
`state`	string \| null	State or region from the document.
`postalCode`	string \| null	Postal or ZIP code from the document.
`country`	string \| null	Country text or code from the document (not necessarily the same as personalInfo.country).

document.address is a response-only helper and does not change stored document data:

Prefer free-text document address when non-empty.
Otherwise join non-empty addressDetails parts with ", ": street, city, state, postalCode, country.
If nothing usable is available, address is null.

200 — 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"
      }
    }
  }
}

Status values

Name	Type	Description
`CREATED`	active	Inquiry is open, but verification has not started.
`PENDING`	active	Customer verification is in progress.
`COMPLETED`	transitional	Configured checks finished and the decision policy is being applied.
`NEEDS_REVIEW`	review	An operator must complete manual review. identity is included when available; document image URLs can be retrieved.
`APPROVED`	terminal	Inquiry was approved. identity is included when available; documents can be retrieved.
`DECLINED`	terminal	Inquiry was declined. identity is not included.
`FAILED`	terminal	Verification reached a hard failure or attempt limit. identity is included when available.
`EXPIRED`	terminal	Inquiry lifetime elapsed before approval.
`PURGED`	terminal	Inquiry data was removed through a purge action.

Errors

Name	Type	Description
`400`	Bad Request	inquiryId is not a canonical UUID.
`401`	Unauthorized	Missing, invalid, expired, or revoked API key.
`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

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

Get Inquiry Response

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

Open an inquiry

Get inquiry documents