> ## Documentation Index > Fetch the complete documentation index at: https://docs.crown-brlv.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Account (KYC) > Requests onboarding of an individual account whose KYC Crown runs itself. The body carries the holder's profile plus the documents captured in the partner's liveness session. Documents travel as ids: upload each one with `POST /v1/accounts/documents`, then reference the returned id here. Request-first: the response describes a creation request, not an account. The request enters compliance review and the account is provisioned on approval. **Validated on this request** — every rule below is answered before anything is created, so no valid body needs a round trip to discover a condition: - The parent account must onboard accounts in kyc mode. A parent that onboards in reliance mode is refused with `403` and must use `POST /v1/accounts/reliance`. - The parent must hold the `subaccounts--tier` capability matching `reward-tier`, or the request is refused with `403`. - Exactly one of `cpf` and `passport` must be sent, never both. A Brazilian tax residence (`tax-residence` = `BRA`) requires `cpf`, and it must be a valid CPF. Every other residence requires `passport`. - `date-of-birth` must be the birth date of someone at least 18 years old. - `address.state` is required when `address.country` is `BRA`, where it must be the two-letter federal unit code (`SP`, `RJ`, `MG`, …). Elsewhere it is free text and optional. - `document` is required. Its `type` must be `passport` for any tax residence other than `BRA`. `back-file-id` is required when `type` is `rg`, and rejected for `cnh` and `passport`, which are each read from a single page. - When `pep.declared` is `true`, `pep.full-name`, `pep.role` and `pep.relationship` are all required. - Every file id referenced in `document` must have been uploaded by this same parent account via `POST /v1/accounts/documents`. - Addresses in `external-wallets` must be unique within the request, and none may already be registered to another account. **Idempotency**: a non-terminal request already open for the same taxpayer identifier under the same parent is returned as-is with `200`, instead of a second request being created. ## OpenAPI ````yaml POST /api/v1/accounts/kyc openapi: 3.1.0 info: title: Crown API & Webhooks version: 1.0.0 description: >- Open API 3 docs for Crown API Webhook events that Crown will POST to your configured endpoint URL. All webhooks expect a 200 OK response. Payloads use kebab-case for all keys to match the Crown API conventions. servers: - url: https://app.crown-brlv.com description: Production server security: [] paths: /api/v1/accounts/kyc: post: summary: Create an account (kyc) description: >- Requests onboarding of an individual account whose KYC Crown runs itself. The body carries the holder's profile plus the documents captured in the partner's liveness session. Documents travel as ids: upload each one with `POST /v1/accounts/documents`, then reference the returned id here. Request-first: the response describes a creation request, not an account. The request enters compliance review and the account is provisioned on approval. **Validated on this request** — every rule below is answered before anything is created, so no valid body needs a round trip to discover a condition: - The parent account must onboard accounts in kyc mode. A parent that onboards in reliance mode is refused with `403` and must use `POST /v1/accounts/reliance`. - The parent must hold the `subaccounts--tier` capability matching `reward-tier`, or the request is refused with `403`. - Exactly one of `cpf` and `passport` must be sent, never both. A Brazilian tax residence (`tax-residence` = `BRA`) requires `cpf`, and it must be a valid CPF. Every other residence requires `passport`. - `date-of-birth` must be the birth date of someone at least 18 years old. - `address.state` is required when `address.country` is `BRA`, where it must be the two-letter federal unit code (`SP`, `RJ`, `MG`, …). Elsewhere it is free text and optional. - `document` is required. Its `type` must be `passport` for any tax residence other than `BRA`. `back-file-id` is required when `type` is `rg`, and rejected for `cnh` and `passport`, which are each read from a single page. - When `pep.declared` is `true`, `pep.full-name`, `pep.role` and `pep.relationship` are all required. - Every file id referenced in `document` must have been uploaded by this same parent account via `POST /v1/accounts/documents`. - Addresses in `external-wallets` must be unique within the request, and none may already be registered to another account. **Idempotency**: a non-terminal request already open for the same taxpayer identifier under the same parent is returned as-is with `200`, instead of a second request being created. requestBody: content: application/json: schema: type: object properties: cpf: oneOf: - type: string - type: 'null' description: >- A Brazilian resident's CPF. Send this for a BRA tax residence, and passport for any other example: '12345678901' passport: type: object properties: number: type: string description: >- Passport number, the identifier of a holder resident outside Brazil example: X1234567 country: type: string description: Country that issued the passport, ISO-3 example: PRT additionalProperties: false required: - number - country description: A non-Brazilian resident's passport, sent in place of cpf tax-residence: type: string description: Tax residence country, ISO-3 example: BRA reward-tier: type: number format: double enum: - 93.5 - 90 - 97 description: >- CDI reward tier (%) for the account. The parent account must hold the matching subaccounts--tier capability. example: 97 first-name: type: string description: Account holder's given name example: Maria last-name: type: string description: Account holder's family name example: Silva email: type: string format: email example: maria@example.com phone: type: string description: At most 32 characters example: '+5511999999999' date-of-birth: type: string format: date description: Must be the birth date of someone at least 18 years old example: '1990-04-12' mother-full-name: type: string example: Ana Silva address: type: object properties: postal-code: type: string example: 01310-100 line1: type: string example: Avenida Paulista, 1000 line2: type: string description: Empty when there is nothing to add to line1 city: type: string example: Sao Paulo state: type: string description: >- Required when country is BRA, where it must be the two-letter federal unit code example: SP country: type: string description: ISO 3166-1 alpha-3 country code example: BRA additionalProperties: false required: - postal-code - line1 - city - country document: type: object properties: type: type: string enum: - rg - cnh - passport description: >- Identity document captured during the partner's liveness session. A Brazilian tax resident sends an rg or a cnh; every other residence is identified by passport front-file-id: type: string pattern: ^ev_[A-Z0-9]+$ description: Front, or single page, of the document example: ev_019712CFC86D703F85B8BDAA4FC8D254 back-file-id: type: string pattern: ^ev_[A-Z0-9]+$ description: >- Back of the document. Required for an rg, and accepted for nothing else: a cnh and a passport are each read from a single page example: ev_019712CFC86D703F85B8BDAA4FC8D254 additionalProperties: false required: - type - front-file-id description: >- The holder's identity document. Referenced ids come from POST /v1/accounts/documents liveness: type: object properties: id: type: string description: The session's id at the provider provider: type: string enum: - unico - sumsub - idwall - persona - idenfy description: Liveness provider that ran the session example: idwall additionalProperties: false required: - id - provider pep: type: object properties: declared: type: boolean description: >- Whether the holder is a politically exposed person, or related to one. When true the three detail fields below are all required full-name: type: string description: Full name of the exposed person role: type: string description: Public role held relationship: type: string enum: - self - spouse - child - parent - business_associate - other description: The holder's relationship to the exposed person additionalProperties: false required: - declared financial-profile: type: object description: >- What the holder does, earns and owns. A declaration that informs compliance review properties: sector: type: string enum: - gambling - weapons - adult - mining - remittances - crypto - art - realty - vehicles - nonprofits - tcsp - scrap - hospitality - factoring - trade - construction - agribusiness - consulting - other description: >- The sector the holder works in, which feeds the risk rule in compliance review: | Value | Description | |---|---| | `gambling` | Gambling and betting, including online betting and casinos | | `weapons` | Weapons, ammunition and military equipment | | `adult` | Adult content | | `mining` | Mining, prospecting and trade of precious metals and stones | | `remittances` | Foreign exchange, international remittances and banking correspondent services | | `crypto` | Crypto assets and virtual assets | | `art` | Art, antiques and auctions | | `realty` | Real estate brokerage | | `vehicles` | Trade of vehicles, aircraft and vessels | | `nonprofits` | Nonprofit organizations and religious entities | | `tcsp` | Company and trust formation and administration services | | `scrap` | Trade and recycling of scrap and recyclable materials | | `hospitality` | Bars, restaurants, nightclubs and events | | `factoring` | Cash-in-transit (armored transport) and factoring services | | `trade` | Foreign trade, import and export | | `construction` | Construction and real estate development | | `agribusiness` | Agriculture, livestock, logging and trade of agricultural commodities | | `consulting` | Business consulting and advisory services with no specific defined activity | | `other` | Any other economic activity | example: consulting currency: type: string enum: - BRL - USD description: The one currency every amount below is declared in example: BRL monthly-income: type: number format: double description: What the holder earns monthly example: 12000 net-worth: type: number format: double description: Everything the holder owns, net of debt example: 850000 source-of-funds: type: array description: Every source that applies; at least one items: type: string enum: - salary - business - investment - inheritance - asset_sale - other additionalProperties: false required: - sector - currency - monthly-income external-wallets: type: array items: type: object properties: address: type: string description: On-chain destination address example: 0xabc... custody-country: oneOf: - type: string - type: 'null' description: Custodian country, ISO-3 example: BRA custody-type: oneOf: - type: string enum: - self - exchange - type: 'null' description: Self-custody or exchange custody custodian-name: oneOf: - type: string - type: 'null' description: Custodian/exchange name additionalProperties: false required: - address additionalProperties: false required: - tax-residence - reward-tier - first-name - last-name - date-of-birth - address - document - liveness - pep - financial-profile responses: '200': description: An equivalent non-terminal request already exists content: application/json: schema: type: object properties: account: type: object properties: id: type: string format: uuid description: Unique identifier of the account example: 019712cf-c86d-703f-85b8-bdaa4fc8d254 alias: oneOf: - type: string - type: 'null' description: Human-readable alias for the account example: Trading account status: type: string description: >- Current status of the account. A provisioned account is 'pending-setup' or 'active'. An account still being created is projected as pending, carrying its request status: 'pending', 'rejected', or 'provisioning-failed' (see ADR-0008). example: active external-id: oneOf: - type: string - type: 'null' description: External identifier associated with the account example: ext-12345 parent-id: oneOf: - type: string format: uuid - type: 'null' description: >- Parent account id when this account has a parent; null for a top-level account created-at: type: string example: '2024-01-15T10:30:00Z' format: date-time additionalProperties: false required: - id - alias - status - external-id - created-at additionalProperties: false required: - account '201': description: Account creation requested content: application/json: schema: type: object properties: account: type: object properties: id: type: string format: uuid description: Unique identifier of the account example: 019712cf-c86d-703f-85b8-bdaa4fc8d254 alias: oneOf: - type: string - type: 'null' description: Human-readable alias for the account example: Trading account status: type: string description: >- Current status of the account. A provisioned account is 'pending-setup' or 'active'. An account still being created is projected as pending, carrying its request status: 'pending', 'rejected', or 'provisioning-failed' (see ADR-0008). example: active external-id: oneOf: - type: string - type: 'null' description: External identifier associated with the account example: ext-12345 parent-id: oneOf: - type: string format: uuid - type: 'null' description: >- Parent account id when this account has a parent; null for a top-level account created-at: type: string example: '2024-01-15T10:30:00Z' format: date-time additionalProperties: false required: - id - alias - status - external-id - created-at additionalProperties: false required: - account '400': description: Bad request - Invalid input parameters content: application/json: schema: type: object properties: error: type: object properties: type: type: string message: type: string code: type: string additionalProperties: false required: - type - message - code description: Bad request error details additionalProperties: false required: - error '403': description: Forbidden - Access denied content: application/json: schema: type: object properties: error: type: object properties: type: type: string message: type: string code: type: string additionalProperties: false required: - type - message - code description: Forbidden access error details additionalProperties: false required: - error '404': description: Not found - Resource does not exist content: application/json: schema: type: object properties: error: type: object properties: type: type: string message: type: string code: type: string additionalProperties: false required: - type - message - code description: Resource not found error details additionalProperties: false required: - error '422': description: Unprocessable entity - Validation failed content: application/json: schema: type: object properties: error: type: object properties: type: type: string message: type: string code: type: string additionalProperties: false required: - type - message - code description: Validation error details additionalProperties: false required: - error ````