Export API

Use the Export API when your backend needs full result details and media after a verification completes. 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 result id, and your custom data.
Return 200 OK immediately. 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`
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.

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).

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

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

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
`400`	Invalid request, for example a missing `sandbox` query parameter

Requirements​

Endpoints​

JSON endpoints​

Protobuf endpoints (DV and PoA)​

Document verification (dv_result_proto.Message)​

Proof of address (poa_result_proto.Message)​

Errors​

Related​