Define the process being verified
Create a transaction with POST /v1/face-auth/transactions. Required fields are country_code and subject; inside subject, provide identity with type, number and country. Check supported countries and locales in the reference; the website’s language list is not the API’s enum list.
# Server-side only. Configure KYC_API_BASE_URL with your authorized base (https://api.example.invalid is illustrative), and KYC_API_KEY privately. Never expose credentials in browser code.
set -eu
: "${KYC_API_BASE_URL:?Set authorized base}" "${KYC_API_KEY:?Set API key}"
: "${KYC_IDEMPOTENCY_KEY:?Persist the key for this creation intent}"
curl --fail-with-body --max-time 15 --request POST \
"${KYC_API_BASE_URL%/}/v1/face-auth/transactions" \
--header "X-API-Key: ${KYC_API_KEY}" \
--header "Idempotency-Key: ${KYC_IDEMPOTENCY_KEY}" \
--header 'Content-Type: application/json' \
--data-binary '{"country_code":"BR","external_id":"docs-example-0001","locale":"pt-BR","subject":{"identity":{"country":"BR","number":"00000000000","type":"CPF"}}}'
# Persist transaction_id and business correlation; use the returned links.webview_url. Read status, decision and decision_reason together. Reuse the SAME idempotency key AND original payload only for the same creation intent; never silently bypass a 409 conflict.
Correlate without duplicating data
Use external_id to relate the process in your system. subject.tenant_subject_id identifies the person in your database. These identifiers serve different purposes and do not replace the transaction_id returned by the API.
source describes the originating system, integration and channel. metadata holds business context, limited to 8 KB; avoid sensitive or unnecessary data. Set expiration with expires_in_minutes within the contract’s bounds; omitting it uses the Tenant default.
Handle the response
The documented response is 201, including creation recovered through idempotency. Persist the identifier before directing the person to the journey. If the response is lost after sending the request, repeat the same creation with the same key and payload; do not automatically generate a new key.
When provided, callback_url sets the webhook for that transaction; otherwise, the Tenant configuration applies. Review idempotency and webhooks before moving this workflow into production.