Skip to main content

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:

  1. The user completes a hosted or SDK verification.
  2. Your backend receives a signed webhook and stores resultId, the step result id, and your custom data.
  3. Return 200 OK immediately. Do not wait on an export before acknowledging the webhook.
  4. 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:

RequirementDetail
Secret API keySend a zyphe_sk_ key in the x-api-key header. Publishable keys (zyphe_pk_) are rejected.
Export API productThe organization must have the Export API product (EXPORT_API) enabled. This is a billable entitlement, not enabled for every organization by default.
sandbox query parameterRequired. true for sandbox data, false for production.
Path identifiersorganization_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.

OperationMethodPathSuccess content type
Flow result detailsGET/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/detailsapplication/json
Document verification detailsGET/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/dv/{dv_result_id}/detailsapplication/x-protobuf-stream
KYC report (PDF)GET/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/dv/{dv_result_id}/reportapplication/pdf
Proof of address detailsGET/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/poa/{poa_result_id}/detailsapplication/x-protobuf-stream
Wallet result detailsGET/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/wallet/{wallet_result_id}/detailsapplication/json
Phone result detailsGET/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/phone/{phone_result_id}/detailsapplication/json
Form result detailsGET/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/form/{form_result_id}/detailsapplication/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 parameterSource
flow_result_idWebhook resultId
dv_result_id / poa_result_id / wallet_result_id / phone_result_id / form_result_idNested data.<type>.id
flow_slugThe 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.

JSON vs protobuf

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:

PartContents
documentExtracted personal_data, document_data, and address_data
front_image / back_image / other_imagecontent_type, image data bytes, and provenance (front, back, selfie, portrait, signature, and related captures)
detailsResult status and processor logs
livenessTime-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:

PartContents
detailsResult status and document type (utility bill, bank document, and other supported types)
documentcontent_type and file data bytes
document_infoExtracted 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​

StatusWhen
401Missing or invalid API key
403Publishable key used, Export API not enabled (product_not_active), or the key is not allowed to read this organization
404Unknown flow result or step result, or a result that is neither yours nor shared with you
400Invalid request, for example a missing sandbox query parameter