> ## 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, Company) > Requests onboarding of a company account whose verification Crown runs itself. The body carries the company profile plus the people behind it: every representative, director and ultimate beneficial owner, each with their identity document and, where their role asks for one, the liveness session and the power of attorney. Files travel as ids: upload each one with `POST /v1/accounts/files`, then reference the returned id here. `tax-residence` selects the body. A company resident in `BRA` sends the Brazilian Company body; every other company sends the Foreign Company body. Request-first: the response describes a creation request, not an account. The request enters compliance review and the account is provisioned on approval. Every country code in the body is ISO 3166-1 alpha-3, read regardless of case: `bra` is read as `BRA`. **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`. - `identifiers` carries at most one entry per country, and at most one outside `BRA`. - A company whose `tax-residence` is `BRA` lists its CNPJ alone. A company resident abroad must list an entry under its `tax-residence`, and may add the CNPJ it also holds under `BRA`. - An entry under `BRA` must be a valid CNPJ and carries no `type`. Every entry outside `BRA` carries a `type`. - `headquarters-address.state` is required when `headquarters-address.country` is `BRA`, where it must be the two-letter federal unit code (`SP`, `RJ`, `MG`, …). - For every entry in `related-parties`, `identifier.country` must be `BRA` exactly when that person's `tax-residence` is `BRA`, and a BRA identifier must be a valid CPF. Each person's identifier and residence are read on their own, not against the company's. - For every entry in `related-parties`, `date-of-birth`, `address` and `document` follow the same rules as an individual holder's. - At least one entry in `related-parties` holds the `representative` role. - `liveness` and `power-of-attorney-file-id` are required of every representative and rejected on anyone else. `ownership-percentage` and `financial-profile` are required of every ubo and rejected on anyone else. - The declared `ownership-percentage` values together cannot exceed 100. - The same person, by `identifier`, appears at most once in `related-parties`. - Every file id referenced in the body must have been uploaded by this same parent account via `POST /v1/accounts/files`. - Addresses in `external-wallets` must be unique within the request, and none may already be registered to another account. **Idempotency**: a request under the same parent with the same number in the entry under its `tax-residence`, whether `pending`, `approved` or `active`, is returned as-is with `200`, instead of a second request being created. ## OpenAPI ````yaml POST /api/v1/accounts/kyc/company 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/company: post: summary: Create a company account (kyc) description: >- Requests onboarding of a company account whose verification Crown runs itself. The body carries the company profile plus the people behind it: every representative, director and ultimate beneficial owner, each with their identity document and, where their role asks for one, the liveness session and the power of attorney. Files travel as ids: upload each one with `POST /v1/accounts/files`, then reference the returned id here. `tax-residence` selects the body. A company resident in `BRA` sends the Brazilian Company body; every other company sends the Foreign Company body. Request-first: the response describes a creation request, not an account. The request enters compliance review and the account is provisioned on approval. Every country code in the body is ISO 3166-1 alpha-3, read regardless of case: `bra` is read as `BRA`. **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`. - `identifiers` carries at most one entry per country, and at most one outside `BRA`. - A company whose `tax-residence` is `BRA` lists its CNPJ alone. A company resident abroad must list an entry under its `tax-residence`, and may add the CNPJ it also holds under `BRA`. - An entry under `BRA` must be a valid CNPJ and carries no `type`. Every entry outside `BRA` carries a `type`. - `headquarters-address.state` is required when `headquarters-address.country` is `BRA`, where it must be the two-letter federal unit code (`SP`, `RJ`, `MG`, …). - For every entry in `related-parties`, `identifier.country` must be `BRA` exactly when that person's `tax-residence` is `BRA`, and a BRA identifier must be a valid CPF. Each person's identifier and residence are read on their own, not against the company's. - For every entry in `related-parties`, `date-of-birth`, `address` and `document` follow the same rules as an individual holder's. - At least one entry in `related-parties` holds the `representative` role. - `liveness` and `power-of-attorney-file-id` are required of every representative and rejected on anyone else. `ownership-percentage` and `financial-profile` are required of every ubo and rejected on anyone else. - The declared `ownership-percentage` values together cannot exceed 100. - The same person, by `identifier`, appears at most once in `related-parties`. - Every file id referenced in the body must have been uploaded by this same parent account via `POST /v1/accounts/files`. - Addresses in `external-wallets` must be unique within the request, and none may already be registered to another account. **Idempotency**: a request under the same parent with the same number in the entry under its `tax-residence`, whether `pending`, `approved` or `active`, is returned as-is with `200`, instead of a second request being created. requestBody: content: application/json: schema: oneOf: - title: Brazilian Company description: >- A company whose tax residence is Brazil, and therefore identified by a CNPJ. The CNPJ answers for the company itself, so the body asks for its names and the people behind it and nothing else type: object properties: identifiers: type: array description: >- Every register the company is known to, one entry each, at most one per country. The entry whose country is the company's tax residence is the one that identifies it. A company resident abroad that also holds a CNPJ adds a second entry under BRA items: type: object properties: type: type: string enum: - tax-id - registration-number description: >- Which of the two numbers a foreign register issues this is: the country's tax identification, or the number the company is registered by at the registrar. Required outside BRA and not accepted under it, where the CNPJ is the only number the register issues example: registration-number value: type: string description: >- The number the register issued the company: a CNPJ when country is BRA example: 98-7654321 country: type: string description: Country whose register issued the number, ISO-3 example: CYM additionalProperties: false required: - value - country example: - value: '12345678000195' country: BRA tax-residence: type: string enum: - BRA description: Tax residence country, ISO-3 example: BRA legal-name: type: string description: The name the company is registered under example: Acme Servicos Ltda trade-name: type: string description: >- The name the company trades under, when it differs from the registered one example: Acme 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 related-parties: type: array minItems: 1 items: type: object properties: first-name: type: string description: >- The person's given name, as their identity document spells it example: Ana last-name: type: string description: >- The person's family name, as their identity document spells it example: Silva date-of-birth: type: string format: date description: >- Must be the birth date of someone at least 18 years old example: '1990-04-12' identifier: type: object properties: value: type: string description: >- The number that identifies the person: a CPF when country is BRA, the passport number otherwise example: '12345678909' country: type: string description: >- Country that issued the number, ISO-3. BRA means the number is a CPF; every other country means it is the passport that country issued example: BRA additionalProperties: false required: - value - country description: >- How the person is identified. A Brazilian tax resident is identified by CPF, every other residence by passport tax-residence: type: string description: >- The person's own tax residence, ISO-3. It is read on its own, not against the company's example: BRA 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 description: >- Where the person lives. state is required when country is BRA, where it must be the two-letter federal unit code document: type: object properties: type: type: string enum: - rg - cnh - passport description: >- The person's identity document. 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 person's identity document. Referenced ids come from POST /v1/accounts/files pep: type: object properties: declared: type: boolean description: >- Whether the person 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 roles: type: array minItems: 1 items: type: string enum: - representative - director - ubo description: >- Every role the person holds in the company. One person is one entry, carrying the fields each of their roles asks for: | Value | Description | |---|---| | `representative` | Acts for the company. Sends `liveness` and `power-of-attorney-file-id` | | `director` | Sits on the company's management | | `ubo` | Ultimately owns more than 25% of the company. Sends `ownership-percentage` and `financial-profile` | example: - representative - ubo 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 description: >- The liveness session the partner ran on the person. Required of a representative, and accepted of no one else power-of-attorney-file-id: type: string pattern: ^ev_[A-Z0-9]+$ description: >- The instrument appointing the person to act for the company. Required of a representative, and accepted of no one else. Referenced by the id returned from POST /v1/accounts/files example: ev_019712CFC86D703F85B8BDAA4FC8D254 ownership-percentage: type: number format: double exclusiveMinimum: 0 maximum: 100 description: >- How much of the company the person ultimately owns. Required of a ubo, and accepted of no one else example: 35 financial-profile: type: object description: >- What the person owns, net of debt. Required of a ubo, and accepted of no one else properties: currency: type: string enum: - BRL - USD description: >- The one currency every amount below is declared in example: BRL net-worth: type: number format: double description: Everything the person owns, net of debt example: 850000 additionalProperties: false required: - currency - net-worth additionalProperties: false required: - first-name - last-name - date-of-birth - identifier - tax-residence - address - document - pep - roles description: >- The natural persons behind the company: its representatives, its directors and every ultimate beneficial owner above 25%. The ownership chain is flattened: this list never carries a company, only the people at the end of it 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: - identifiers - tax-residence - legal-name - reward-tier - related-parties - title: Foreign Company description: >- A company whose tax residence is outside Brazil. No single register answers for it, so the body carries the company's own profile and its corporate documents alongside the people behind it type: object properties: identifiers: type: array description: >- Every register the company is known to, one entry each, at most one per country. The entry whose country is the company's tax residence is the one that identifies it. A company resident abroad that also holds a CNPJ adds a second entry under BRA items: type: object properties: type: type: string enum: - tax-id - registration-number description: >- Which of the two numbers a foreign register issues this is: the country's tax identification, or the number the company is registered by at the registrar. Required outside BRA and not accepted under it, where the CNPJ is the only number the register issues example: registration-number value: type: string description: >- The number the register issued the company: a CNPJ when country is BRA example: 98-7654321 country: type: string description: Country whose register issued the number, ISO-3 example: CYM additionalProperties: false required: - value - country example: - type: registration-number value: 98-7654321 country: CYM - value: '12345678000195' country: BRA tax-residence: type: string description: Tax residence country, ISO-3. Any country other than BRA example: CYM legal-name: type: string description: The name the company is registered under example: Acme Holdings Ltd trade-name: type: string description: >- The name the company trades under, when it differs from the registered one example: Acme giin: type: string description: >- The Global Intermediary Identification Number the IRS issued the company under FATCA. Only a financial institution registered there holds one example: ABC123.00000.LE.136 headquarters-address: type: object properties: postal-code: type: string example: KY1-1104 line1: type: string example: 190 Elgin Avenue line2: type: string description: Empty when there is nothing to add to line1 city: type: string example: George Town state: type: string description: >- Required when country is BRA, where it must be the two-letter federal unit code example: Grand Cayman country: type: string description: ISO 3166-1 alpha-3 country code example: CYM additionalProperties: false required: - postal-code - line1 - city - country description: >- Where the company is headquartered. state is required when country is BRA, where it must be the two-letter federal unit code financial-profile: type: object description: >- What the company does, earns and owns, with the files that evidence it properties: sector: type: string enum: - other - gambling - weapons - adult - mining - remittances - crypto - art - realty - vehicles - nonprofits - tcsp - scrap - hospitality - factoring - trade - construction - agribusiness - consulting description: >- The economic activity the company operates in. `other` covers every activity outside the sectors named below. A named sector is sent only when the company's activity falls within it: | Value | Description | |---|---| | `other` | Every economic activity not named below | | `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 | example: other 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 company earns monthly, its average monthly revenue over the last 12 months example: 250000 net-worth: type: number format: double description: Everything the company owns, net of debt example: 5000000 source-of-funds: type: array minItems: 1 items: type: string description: >- Where the company's funds come from, each source in the partner's own words example: - Revenue from software licensing revenue-statement-file-ids: type: array items: type: string pattern: ^ev_[A-Z0-9]+$ example: ev_019712CFC86D703F85B8BDAA4FC8D254 minItems: 1 description: >- Evidence of the last 12 months' revenue. Several files when the statement comes split by period bank-statement-file-ids: type: array items: type: string pattern: ^ev_[A-Z0-9]+$ example: ev_019712CFC86D703F85B8BDAA4FC8D254 minItems: 1 description: >- Bank statements for the last 3 months, one file per statement or a single consolidated one additionalProperties: false required: - sector - currency - monthly-income - revenue-statement-file-ids 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 corporate-documents: type: array items: type: string pattern: ^ev_[A-Z0-9]+$ example: ev_019712CFC86D703F85B8BDAA4FC8D254 minItems: 1 description: >- Every corporate document the company has, each file referenced by the id returned from POST /v1/accounts/files. A multi-page instrument is one file and one id: - The instrument that constitutes the company, whatever its jurisdiction calls it: certificate of incorporation, articles of incorporation, memorandum and articles of association, bylaws, operating agreement, contrato social, estatuto social or the local equivalent. - Every amendment to it, and its latest consolidated version. - Certificates the registrar issues on the company, such as a certificate of good standing or of incumbency. - The registers of directors and of shareholders or members, and the shareholders' agreement when there is one. related-parties: type: array minItems: 1 items: type: object properties: first-name: type: string description: >- The person's given name, as their identity document spells it example: Ana last-name: type: string description: >- The person's family name, as their identity document spells it example: Silva date-of-birth: type: string format: date description: >- Must be the birth date of someone at least 18 years old example: '1990-04-12' identifier: type: object properties: value: type: string description: >- The number that identifies the person: a CPF when country is BRA, the passport number otherwise example: '12345678909' country: type: string description: >- Country that issued the number, ISO-3. BRA means the number is a CPF; every other country means it is the passport that country issued example: BRA additionalProperties: false required: - value - country description: >- How the person is identified. A Brazilian tax resident is identified by CPF, every other residence by passport tax-residence: type: string description: >- The person's own tax residence, ISO-3. It is read on its own, not against the company's example: BRA 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 description: >- Where the person lives. state is required when country is BRA, where it must be the two-letter federal unit code document: type: object properties: type: type: string enum: - rg - cnh - passport description: >- The person's identity document. 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 person's identity document. Referenced ids come from POST /v1/accounts/files pep: type: object properties: declared: type: boolean description: >- Whether the person 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 roles: type: array minItems: 1 items: type: string enum: - representative - director - ubo description: >- Every role the person holds in the company. One person is one entry, carrying the fields each of their roles asks for: | Value | Description | |---|---| | `representative` | Acts for the company. Sends `liveness` and `power-of-attorney-file-id` | | `director` | Sits on the company's management | | `ubo` | Ultimately owns more than 25% of the company. Sends `ownership-percentage` and `financial-profile` | example: - representative - ubo 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 description: >- The liveness session the partner ran on the person. Required of a representative, and accepted of no one else power-of-attorney-file-id: type: string pattern: ^ev_[A-Z0-9]+$ description: >- The instrument appointing the person to act for the company. Required of a representative, and accepted of no one else. Referenced by the id returned from POST /v1/accounts/files example: ev_019712CFC86D703F85B8BDAA4FC8D254 ownership-percentage: type: number format: double exclusiveMinimum: 0 maximum: 100 description: >- How much of the company the person ultimately owns. Required of a ubo, and accepted of no one else example: 35 financial-profile: type: object description: >- What the person owns, net of debt. Required of a ubo, and accepted of no one else properties: currency: type: string enum: - BRL - USD description: >- The one currency every amount below is declared in example: BRL net-worth: type: number format: double description: Everything the person owns, net of debt example: 850000 additionalProperties: false required: - currency - net-worth additionalProperties: false required: - first-name - last-name - date-of-birth - identifier - tax-residence - address - document - pep - roles description: >- The natural persons behind the company: its representatives, its directors and every ultimate beneficial owner above 25%. The ownership chain is flattened: this list never carries a company, only the people at the end of it 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: - identifiers - tax-residence - legal-name - headquarters-address - financial-profile - reward-tier - corporate-documents - related-parties 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.