Export API
Use the Export API when your backend needs full result details and media after a verification completes, or a KYC report PDF of a document verification. Webhooks carry statuses, scores, identifiers, and optional structured fields. They do not include identity-document images or proof-of-address files.
Typical sequence:
- The user completes a hosted or SDK verification.
- Your backend receives a signed webhook and stores
resultId, the step resultid, and yourcustomdata. - Return
200 OKimmediately. Do not wait on an export before acknowledging the webhook. - If you need images or the full result, call the matching Export API endpoint asynchronously.
See Receiving Webhooks and Webhook payload.
Requirements
Every Export API call needs all of the following:
| Requirement | Detail |
|---|---|
| Secret API key | Send a zyphe_sk_ key in the x-api-key header. Publishable keys (zyphe_pk_) are rejected. |
| Export API product | The organization must have the Export API product (EXPORT_API) enabled. This is a billable entitlement, not enabled for every organization by default. |
sandbox query parameter | Required. true for sandbox data, false for production. |
| Path identifiers | organization_id, flow_result_id, flow_slug, and the step result id for step-level endpoints. |
If Export API is not enabled, the API returns HTTP 403 with tag product_not_active (code 5031). Treat that as a configuration issue: contact your Zyphe account manager or support@zyphe.com to enable the product.
Keep secret keys on the server. Never call Export API from a browser or mobile app.
Endpoints
All paths are relative to https://api.zyphe.com. Schemas live in the API reference.
| Operation | Method | Path | Success content type |
|---|---|---|---|
| Flow result details | GET | /sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/details | application/json |
| Document verification details | GET | /sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/dv/{dv_result_id}/details | application/x-protobuf-stream |
| KYC report (PDF) | GET | /sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/dv/{dv_result_id}/report | application/pdf |
| Proof of address details | GET | /sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/poa/{poa_result_id}/details | application/x-protobuf-stream |
| Wallet result details | GET | /sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/wallet/{wallet_result_id}/details | application/json |
| Phone result details | GET | /sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/phone/{phone_result_id}/details | application/json |
| Form result details | GET | /sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/form/{form_result_id}/details | application/json |
flow_slug is the slug from the flow configuration (the same value used in hosted URLs and in listFlowResults).
Map webhook fields to path parameters:
| Path parameter | Source |
|---|---|
flow_result_id | Webhook resultId |
dv_result_id / poa_result_id / wallet_result_id / phone_result_id / form_result_id | Nested data.<type>.id |
flow_slug | The flow's slug from your configuration |
Optional query parameter: locale.
KYC Passport results shared with you
The same endpoints also open a flow result that belongs to another organization, when it is a KYC Passport result shared with yours: your organization accepted the owner's invite and the person consented to share their result with you. That is the result a kyc_passport.verification.updated webhook points at. Call the endpoints with your organization_id, the shared flow_result_id from the webhook's source.flowResultId, and your own secret key. The Export API product must be enabled on your organization. A result that is not shared with you answers as if it did not exist.
Document verification and proof of address return a length-delimited protobuf stream (application/x-protobuf-stream). Flow, wallet, phone, and form details return JSON (application/json).
JSON endpoints
Flow, wallet, phone, and form details respond with application/json.
The flow-result payload is a FlowResult: identifiers, status, flowSlug, customData, and arrays such as dvResults, poaResults, formResults, phoneResults, walletResults, amlResults, and kybResults. Step-level JSON endpoints return the matching result object (WalletResult, PhoneResult, FormResult).
Each entry of dvResults carries documentType, a numeric id, and documentClass, the class of the document: IdentificationCard, DriversLicense, Passport, and so on, the same whichever provider read it. Branch on documentClass; the list of values is in the reference.
curl -X GET \
"https://api.zyphe.com/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/details?sandbox=true" \
-H "x-api-key: zyphe_sk_..."
@zyphe-sdk/node exposes getFlowResult for the flow-result payload. It requires a secret key and an organization with Export API enabled. See Node SDK.
Protobuf endpoints (DV and PoA)
Document verification and proof of address streams are length-delimited protobuf: each message is a varint length prefix followed by a serialized Message. The stream can contain several messages (metadata, then one or more images).
Proto files:
curl -X GET \
"https://api.zyphe.com/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/dv/{dv_result_id}/details?sandbox=true" \
-H "x-api-key: zyphe_sk_..." \
-H "Accept: application/x-protobuf-stream" \
--output dv-result.bin
@zyphe-sdk/node exposes getDvResult, which downloads the DV stream and decodes it into document fields plus frontImage / backImage / otherImages. It requires a secret key and Export API.
Document verification (dv_result_proto.Message)
Each message is one of:
| Part | Contents |
|---|---|
document | Extracted personal_data, document_data, and address_data |
front_image / back_image / other_image | content_type, image data bytes, and provenance (front, back, selfie, portrait, signature, and related captures) |
details | Result status and processor logs |
liveness | Time-limited video URL when a liveness capture exists |
In the document part, document_data.document_class_code is the document's class, the value documentClass has in the flow result. A document of a kind the class list does not cover keeps the code it was read with, while documentClass reads Unknown.
Proof of address (poa_result_proto.Message)
Each message is one of:
| Part | Contents |
|---|---|
details | Result status and document type (utility bill, bank document, and other supported types) |
document | content_type and file data bytes |
document_info | Extracted name, postal address, and emission date when available |
KYC report (PDF)
The report endpoint returns one document verification as a PDF, ready to file as evidence of a KYC check. It contains:
- the outcome and every check the verification was held against;
- the data read from the document;
- the document images;
- the device and session the verification was made from;
- the person's AML screenings;
- an audit trail;
- the verification data, attached to the PDF as a JSON file.
Pick the language with locale: en, it, de, es, fr, or pt. Any other value prints in English. The report is generated on each request and states when it was generated, so download it again if you need the result as it stands later. The file name is in the Content-Disposition header.
curl -X GET \
"https://api.zyphe.com/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/dv/{dv_result_id}/report?sandbox=false&locale=en" \
-H "x-api-key: zyphe_sk_..." \
-H "Accept: application/pdf" \
--output kyc-report.pdf
With @zyphe-sdk/node, getDvResultReport returns the PDF as a Uint8Array and its file name:
import { writeFile } from 'node:fs/promises'
import { getDvResultReport, type SDKOptions } from '@zyphe-sdk/node'
const opts: SDKOptions = { apiKey: process.env.ZYPHE_SECRET_API_KEY!, environment: 'production' }
const {
data: pdf,
fileName,
error,
} = await getDvResultReport(
{
organizationId: '<organization-id>',
flowResultId: '<flow-result-id>',
flowSlug: '<flow-slug>',
dvResultId: '<dv-result-id>',
isSandbox: false,
locale: 'en',
},
opts,
)
if (pdf) await writeFile(fileName ?? 'kyc-report.pdf', pdf)
Like the other Export API endpoints, the report requires a secret key and the Export API product: without the product the request fails with 403 (product_not_active).
Download media promptly and store it under your own access controls. Apply the same privacy and retention rules as for other identity data: PII access control and data deletion.
Errors
| Status | When |
|---|---|
401 | Missing or invalid API key |
403 | Publishable key used, Export API not enabled (product_not_active), or the key is not allowed to read this organization |
404 | Unknown flow result or step result, or a result that is neither yours nor shared with you |
400 | Invalid request, for example a missing sandbox query parameter |