> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# Dracma biometrics on account opening

Use this flow when the facial check already happened in **Dracma**. You send the verification id with the holder (individual) or with each partner (company). The API reads that verification with your tenant's Dracma credential and finishes biometrics in that call.

There is no capture link, no acceptance page, and no selfie upload. The id must be `approved` and carry the same CPF as the person. Each id approves one account opening.

The tenant needs an active Dracma credential. Without it, creation returns `422 dracma_not_configured`.

## Flow

```mermaid
sequenceDiagram
  participant You as Your system
  participant API as CorpX API
  participant Dracma as Dracma

  You->>API: POST /v1/accreditations/pf or /pj with biometry
  API->>Dracma: GET /v1/verifications/{id}
  alt approved and same CPF
    API-->>You: 201 with no link
  else rejected, pending, or different CPF
    API-->>You: 422 and no account opening is created
  end
  Note over You,API: Individuals proceed to opening. Companies stay PENDING_REVIEW
  You->>API: POST .../documents kind=account_opening_terms (optional)
```

## The `biometry` object

On `person` (individual) or on **every** `partners` item (company). Everyone uses the same mode: Dracma does not mix with the default flow or with another provider (`422 mixed_biometry_mode`).

```json
"biometry": {
  "provider": "dracma",
  "evidenceId": "ver_01h..."
}
```

`evidenceId` is the Dracma verification id, not a file. The `provider` in this guide is only `dracma`.

**`Individual`**

```bash title="Individual"
curl -X POST "https://api.corpx.com/v1/accreditations/pf" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "person": {
      "name": "Ana Silva",
      "cpf": "12345678909",
      "birthDate": "1990-01-15",
      "email": "ana@example.com",
      "phone": "+5511999998888",
      "biometry": { "provider": "dracma", "evidenceId": "ver_01hxyz" }
    },
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "cityIbgeCode": "3550308"
    }
  }'
```

**`Company`**

```bash title="Company"
curl -X POST "https://api.corpx.com/v1/accreditations/pj" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "company": {
      "legalName": "Acme Ltda",
      "tradeName": "Acme",
      "cnpj": "12345678000199",
      "email": "financeiro@acme.example",
      "phone": "+5511333334444",
      "legalForm": "ltda"
    },
    "partners": [
      {
        "name": "Ana Silva",
        "cpf": "12345678909",
        "birthDate": "1990-01-15",
        "email": "ana@example.com",
        "phone": "+5511999998888",
        "isAdministrator": true,
        "ownershipPercent": 100,
        "biometry": { "provider": "dracma", "evidenceId": "ver_01hxyz" }
      }
    ],
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "cityIbgeCode": "3550308"
    }
  }'
```

The `201` response has no `biometryLink` and no `acceptanceLink`. The person is already biometrically approved.

* **Individuals** open like the default flow: no manual review, subject to the tenant's existing auto-approve policy.
* **Companies** stay in `PENDING_REVIEW`. The required company PDFs are unchanged.

The verification counts only when all three hold:

* status `approved` (`pending` and `review_required` do not approve);
* `subject.cpf` has the same 11 digits as the person;
* that id is not already bound to another opening that has not failed.

A network failure at Dracma does not approve. Creation returns `503 dracma_unavailable` and no live opening is left behind.

## Account-opening terms (optional)

The terms PDF does not block the account. Send it whenever you want, for individuals or companies, until status is `ACTIVE` or `FAILED` — including after biometrics, while `INTEGRATING`.

```bash
curl -X POST "https://api.corpx.com/v1/accreditations/$ACR_ID/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "account_opening_terms",
    "contentType": "application/pdf",
    "sizeBytes": 120034
  }'
```

`PUT` the PDF to the `uploadUrl` you get back. This kind does not appear in `missingDocumentKinds`.

## Errors

| HTTP | `errorCode`                 | When                                                          |
| ---- | --------------------------- | ------------------------------------------------------------- |
| 422  | `dracma_not_configured`     | The tenant has no active Dracma credential                    |
| 422  | `verification_not_approved` | The verification is not `approved`, or Dracma did not find it |
| 422  | `verification_cpf_mismatch` | The verification CPF is not the person's, or no CPF came back |
| 409  | `verification_already_used` | This id already approves another opening that has not failed  |
| 422  | `mixed_biometry_mode`       | A company mixed Dracma with another mode                      |
| 503  | `dracma_unavailable`        | Dracma did not respond. Retry; nothing was approved           |