Bring Your Own Biometrics (BYO)

By default, onboarding identity verification uses CorpX biometrics — we generate the facial capture link and manage the whole journey. If you already collect facial biometrics from your customers with a partner platform, you can use the alternative BYO (Bring Your Own biometrics) flow: you send us the evidence exported by your platform and we validate its authenticity directly with the partner.

Enablement required

The BYO flow is disabled by default. It must be enabled on your tenant, provider by provider, by our team — contact support and let us know which platform you use. Without enablement, the biometry object is rejected with 422.

Supported platforms

Provider	`provider` value
Unico	`unico`
SERPRO	`serpro`
IDWALL	`idwall`
SUMSUB	`sumsub`
ClearSale	`clearsale`
CAF	`caf`
Valid	`valid`

Each platform has its own export format. You send the exported file + a metadata JSON (typically containing the hash or ID that lets us verify that check's validity directly with the partner).

Differences from the default flow

	CorpX biometrics (default)	Bring Your Own (BYO)
Facial capture	Link generated by us	Already done on your platform
Validation	Automatic within the journey	We verify validity with the partner
Acceptance term	Embedded in the journey	Acceptance link hosted by us, per person
PF approval	Automatic	Prior review required
PJ approval	Prior review	Prior review

Flow

Step 1: Send the evidence

First, register the evidence and receive an upload URL:

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/biometry-evidence" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "clearsale",
    "fileName": "export-customer-12345.zip",
    "contentType": "application/zip"
  }'

{
  "evidenceId": "evd_5f4e3d2c1b0a",
  "uploadUrl": "https://kyc-archive.s3.sa-east-1.amazonaws.com/staging/...",
  "uploadExpiresAt": "2026-07-07T19:00:00Z",
  "scanStatus": "PENDING",
  "info": "O arquivo enviado passa por verificação de tipo, antivírus e sanitização antes de ser arquivado (poucos segundos). Arquivos infectados ou corrompidos são recusados e não ficam disponíveis."
}

Then upload the file exported by your platform via PUT to the uploadUrl (presigned URL, valid for 1 hour):

curl -X PUT "{uploadUrl}" \
  -H "Content-Type: application/zip" \
  --data-binary @export-customer-12345.zip

The PUT returns 200 as soon as the file is received, but archiving is not immediate: every upload goes through real type detection (magic bytes, not the extension), antivirus and sanitization. PDFs are rasterized and images re-encoded; infected, corrupted or unexpected-type files are rejected and never become available for review.

Step 2: Create the accreditation with the `biometry` object

Use the same PF and PJ endpoints, including the biometry object on the person (inside person for PF; inside each partners[] item for PJ):

{
  "person": {
    "name": "Maria da Silva",
    "cpf": "12345678901",
    "birthDate": "1990-05-20",
    "email": "maria@email.com",
    "phone": "+5511999998888",
    "biometry": {
      "provider": "clearsale",
      "evidenceId": "evd_5f4e3d2c1b0a",
      "metadata": {
        "transactionHash": "8f7a6b5c4d3e2f1a...",
        "sessionId": "cs-session-998877"
      }
    }
  },
  "address": { "...": "..." }
}

Field	Description
`biometry.provider`	Platform that collected the biometrics (table above). Must be enabled on your tenant.
`biometry.evidenceId`	ID returned in Step 1.
`biometry.metadata`	Free-form JSON with the data that lets us validate the evidence with the partner (hash, session/transaction ID, etc.). The exact format depends on the provider — our support informs the required fields during enablement.

Single mode per accreditation

A single accreditation uses one biometrics mode: either all persons with CorpX biometrics (default) or all with BYO. For PJ with BYO, send the biometry object for all partners.

Step 3: Acceptance term

Since the capture did not happen within our journey, each individual must confirm the account opening terms on a page hosted by us — this provides the formal consent record (date/time, IP and device of whoever accepted).

After the evidence is validated, you receive the accreditation.acceptance.link.created webhook with an acceptance link per person. The same URL appears as persons[].acceptanceLink on GET / the POST response (once the token has been issued).
Deliver the link to the end user. The page displays your brand (logo and colors, configured with our support) and the opening terms.
The acceptance expires in 7 days; use the retry endpoint to regenerate.

Embedding the acceptance page in an iframe

You can embed the acceptance page inside your own site via <iframe>. By default this is blocked — we send Content-Security-Policy: frame-ancestors 'none' on the HTML response. To enable it, share with our support the HTTPS origins of your site (e.g. https://app.yourcompany.com); we add them to your tenant allowlist and the CSP starts including frame-ancestors https://app.yourcompany.com ....

Allowlist rules:

HTTPS only (http:// is not accepted, even in dev).
Accepted forms: https://host, https://host:port or https://*.host (wildcard only on the first label).
Up to 10 origins per tenant.

Sample embed once enabled:

<iframe
  src="https://tenant.api.corpx.com/v1/accreditations/accept/tok_..."
  style="width: 100%; height: 720px; border: 0;"
  title="Account opening acceptance"
></iframe>

{
  "type": "accreditation.acceptance.link.created",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "cpf": "12345678901",
    "acceptanceLink": "https://tenant.api.corpx.com/v1/accreditations/accept/tok_...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}

Step 4: Prior review and opening

With evidences validated and acceptances recorded for all persons, the accreditation enters PENDING_REVIEW — in the BYO flow prior review is required even for PF. After approval, the process continues identically to the default flow: INTEGRATING → ACTIVE, with the same webhooks.

Common failure reasons

Rejected immediately, in the HTTP response to the POST:

Code	HTTP	Meaning	What to do
`provider_not_enabled`	422	Provider not enabled on your tenant.	Ask support for enablement.
`unsupported_provider`	422	`provider` outside the accepted list.	Use one of the values in the platforms table.
`evidence_not_found`	422	The `biometry.evidenceId` does not exist or does not belong to your tenant.	Complete Step 1 before creating the accreditation.
`mixed_biometry_mode`	422	PJ with some partners on BYO and some on the default flow.	Send `biometry` for all partners, or for none.

Ending the accreditation later, on the accreditation.failed webhook (errorReason):

`errorReason`	Meaning	What to do
`evidence_invalid`	The partner did not confirm the evidence validity.	Check the hash/ID in the metadata and resend.
`acceptance_timeout`	The user did not confirm the acceptance in time.	Retry to regenerate the link.
`castle_deny`	The device risk assessment blocked the acceptance.	Contact support.
`review_rejected`	Rejected during prior review.	Contact support for details.

Supported platforms​

Differences from the default flow​

Flow​

Step 1: Send the evidence​

Step 2: Create the accreditation with the biometry object​

Step 3: Acceptance term​

Embedding the acceptance page in an iframe​

Step 4: Prior review and opening​

Common failure reasons​