On this page
Before running a request
These commands are synthetic examples. api.example.invalid is not a test environment and does not resolve to a real service. Replace the base only with the confirmed URL for your enabled environment and keep the key on your backend. To explore without network requests or credentials, open the simulator.
1. Create a transaction
Choose an idempotency key that stays unchanged for the same creation attempt. The CPF below is a fictitious documentation value.
# 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.
2. Hand over the journey
The POST returns 201 and a transaction_id. Store that identifier alongside your external_id. Direct the person to the returned hosted URL in links.webview_url; do not construct journey URLs from transaction identifiers.
3. Read the result
# 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_TRANSACTION_ID:?Use the returned transaction_id}"
curl --fail-with-body --max-time 15 --request GET \
"${KYC_API_BASE_URL%/}/v1/face-auth/transactions/${KYC_TRANSACTION_ID}" \
--header "X-API-Key: ${KYC_API_KEY}"
# 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.
Read status, decision and decision_reason together. A pending decision does not allow your application to treat the flow as approved. The request must use a key for the same Tenant and environment as the transaction.
Next step
Implement webhooks with HMAC verification and reconciliation. Before production, cover rejection, expiration, manual review, duplicates and temporary connection loss.