> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trio.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard entity

> Onboards an entity

> [!NOTE]
>
> **IMPORTANT:** This feature is only available after a distribution channel has been created for your organization.
>
> To request the creation of a distribution channel, contact Trio Support or your Trio Account Manager.


## OpenAPI

````yaml v2/api-reference/openapi.json POST /v2/onboarding
openapi: 3.0.0
info:
  title: Trio API v2
  version: 2026-10-19.v2
servers:
  - url: https://api.sandbox.trio.com.br
    variables: {}
  - url: https://api.qa.trio.com.br
    variables: {}
  - url: https://api.trio.com.br
    variables: {}
security: []
tags: []
paths:
  /v2/onboarding:
    parameters:
      - description: >-
          Version of the v2 contract the client is written against. Each
          breaking change publishes a new version.
        example: 2026-10-19.v2
        in: header
        name: Trio-Version
        required: true
        schema:
          enum:
            - 2026-10-19.v2
          type: string
          x-struct: null
          x-validate: null
      - description: >-
          ID of another org to act on instead of the API key's own org. The
          key's org must have been granted access to it, and the request is
          refused with 403 FORBIDDEN otherwise. When that access or the API key
          is read-only, only GET and HEAD requests may carry it. When the target
          org requires mTLS, so does the request. Leave it out to act on the
          key's own org.
        in: header
        name: Trio-Target-Org-Id
        required: false
        schema:
          format: uuid
          type: string
          x-struct: null
          x-validate: null
    post:
      tags:
        - Onboarding
      summary: Onboard entity
      description: Onboards an entity
      operationId: TrioFoundationWeb.V2.Onboarding.OnboardController.create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2_onboarding_parameters'
        description: The onboard entity attributes
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2_onboard_response'
          description: Compliance
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2_error'
          description: >-
            Malformed request: a body that is not valid JSON
            (MALFORMED_REQUEST), or a Trio-Version header that is missing or not
            the current one (INVALID_TRIO_VERSION).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2_error'
          description: Missing or invalid API key credentials (INVALID_CREDENTIALS).
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2_error'
          description: >-
            The API key may not do this (FORBIDDEN): for instance
            Trio-Target-Org-Id names an org it has no access to, or writes
            through a read-only access.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2_error'
          description: >-
            Invalid input (INVALID_PARAMETER, REQUIRED_PARAMETER, or the code of
            the rule the request breaks). A request outside the operation's
            schema lists the offending fields in `errors`.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2_error'
          description: >-
            A service needed to answer is unavailable
            (TRIO_SERVICE_UNAVAILABLE).
      callbacks: {}
      security:
        - authorization: []
components:
  schemas:
    V2_onboarding_parameters:
      description: Onboard parameters for creating entity
      example:
        business_infos:
          annual_revenue:
            amount: 500000
            currency: BRL
          average_ticket:
            amount: 10000000
            currency: BRL
        consent:
          consent_at: '2026-08-25T07:00:00.000Z'
          ip_address: 8.8.8.8
          tax_number: '04969361908'
        external_id: 12345ET
        name: Entity Test
        representatives:
          - email: john@gcorp.com
            is_pep: false
            is_us_person: false
            name: John
            phone: '+5541999990000'
            tax_number: '04969361908'
        tax_number: '61775921000110'
      properties:
        business_infos:
          $ref: >-
            #/components/schemas/V2_onboarding_entity_business_information_parameters
        consent:
          $ref: '#/components/schemas/Onboarding_entity_consent_parameters'
        external_id:
          description: External ID of the Entity
          type: string
          x-struct: null
          x-validate: null
        name:
          description: Name of the Entity
          type: string
          x-struct: null
          x-validate: null
        representatives:
          items:
            $ref: '#/components/schemas/Onboarding_entity_representative_parameters'
          type: array
          x-struct: null
          x-validate: null
        tax_number:
          description: Tax number of the Entity
          type: string
          x-struct: null
          x-validate: null
      required:
        - tax_number
        - name
        - business_infos
        - representatives
        - consent
      title: V2 onboarding parameters
      type: object
      x-struct: Elixir.TrioFoundationWeb.Schemas.Onboarding.V2.Entity.OnboardParams
      x-validate: null
    V2_onboard_response:
      description: Entity onboard response
      example:
        data:
          business_infos:
            annual_revenue:
              amount: 5000000
              currency: BRL
            average_ticket:
              amount: 500000
              currency: BRL
          consent:
            consent_at: '2026-08-25T07:00:00.000000Z'
            ip_address: 8.8.8.8
            tax_number: '52998224725'
          entity_id: 01a0ee9f-7418-625f-e4b2-624b4ad4959f
          external_id: 404ANVIL
          inserted_at: '2026-09-29T19:23:42.485921Z'
          name: ACME INC
          org_id: 92b0f620-7105-4c10-84a1-f5a034a14efa
          representatives:
            - email: w.coyote@acme.com
              id: 8c61c7fd-3509-4306-9fec-9090e82fe121
              name: Willy Coyote
              phone: '+5541999990000'
              required_documents:
                - identification
              status: in_validation
              tax_number: '52998224725'
          required_documents:
            - company_contract
          status: in_validation
          tax_number: '61775921000110'
          updated_at: '2026-09-29T19:23:42.485921Z'
      properties:
        data:
          $ref: '#/components/schemas/V2_entity_onboard_data'
      title: V2 onboard response
      type: object
      x-struct: Elixir.TrioFoundationWeb.Schemas.Onboarding.V2.Entity.OnboardResponse
      x-validate: null
    V2_error:
      example:
        error:
          error_code: INVALID_PARAMETER
          error_message: 'Invalid parameters: /amount: Invalid integer. Got: string'
          errors:
            - field: /amount
              message: 'Invalid integer. Got: string'
      properties:
        error:
          properties:
            error_code:
              description: >-
                Stable UPPER_SNAKE identifier of the error, for programs and
                logs. Branch on this, not on the message.
              type: string
              x-struct: null
              x-validate: null
            error_message:
              description: Human readable explanation of the error.
              type: string
              x-struct: null
              x-validate: null
            errors:
              description: >-
                Only on INVALID_PARAMETER for a request outside the operation's
                schema: one entry per offending field.
              items:
                properties:
                  field:
                    description: JSON pointer to the field, e.g. /amount.
                    type: string
                    x-struct: null
                    x-validate: null
                  message:
                    description: What is wrong with it.
                    type: string
                    x-struct: null
                    x-validate: null
                required:
                  - field
                  - message
                type: object
                x-struct: null
                x-validate: null
              type: array
              x-struct: null
              x-validate: null
          required:
            - error_code
            - error_message
          type: object
          x-struct: null
          x-validate: null
      required:
        - error
      title: V2 error
      type: object
      x-struct: Elixir.TrioFoundationWeb.Schemas.HTTP.V2Error
      x-validate: null
    V2_onboarding_entity_business_information_parameters:
      description: Onboard business information parameters for creating entity
      example:
        annual_revenue:
          amount: 500000
          currency: BRL
        average_ticket:
          amount: 10000000
          currency: BRL
      properties:
        annual_revenue:
          $ref: '#/components/schemas/Money'
        average_ticket:
          $ref: '#/components/schemas/Money'
      required:
        - average_ticket
        - annual_revenue
      title: V2 onboarding entity business information parameters
      type: object
      x-struct: >-
        Elixir.TrioFoundationWeb.Schemas.Onboarding.V2.Entity.EntityBusinessInfosParams
      x-validate: null
    Onboarding_entity_consent_parameters:
      description: Onboard consent parameters for creating entity
      example:
        consent_at: '2026-08-25T07:00:00.000Z'
        ip_address: 8.8.8.8
        tax_number: '04969361908'
      properties:
        consent_at:
          description: Date of the entity consent
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        ip_address:
          description: Consent IP Address (IPv4 or IPv6)
          type: string
          x-struct: null
          x-validate: null
        tax_number:
          description: Consent tax number of a legal representative
          type: string
          x-struct: null
          x-validate: null
      required:
        - tax_number
        - ip_address
        - consent_at
      title: Onboarding entity consent parameters
      type: object
      x-struct: Elixir.TrioFoundationWeb.Schemas.Onboarding.Entity.EntityConsentParams
      x-validate: null
    Onboarding_entity_representative_parameters:
      description: Onboard legal representatives parameters for creating entity
      example:
        email: john@gcorp.com
        is_pep: false
        is_us_person: false
        name: John
        phone: '+5541999990000'
        tax_number: '04969361908'
      properties:
        email:
          description: Legal representative email
          type: string
          x-struct: null
          x-validate: null
        is_pep:
          default: false
          description: Whether the legal representative is a politically exposed person
          type: boolean
          x-struct: null
          x-validate: null
        is_us_person:
          default: false
          description: Whether the legal representative is a US person
          type: boolean
          x-struct: null
          x-validate: null
        name:
          description: Legal representative name
          type: string
          x-struct: null
          x-validate: null
        phone:
          description: Legal representative phone number in e.164 format
          type: string
          x-struct: null
          x-validate: null
        tax_number:
          description: Legal representative tax number
          type: string
          x-struct: null
          x-validate: null
      required:
        - tax_number
        - email
        - phone
        - name
      title: Onboarding entity representative parameters
      type: object
      x-struct: >-
        Elixir.TrioFoundationWeb.Schemas.Onboarding.Entity.EntityRepresentativeParams
      x-validate: null
    V2_entity_onboard_data:
      description: >-
        The entity as Trio registered it to onboard, with the fields of the
        onboarding request under the same names
      example:
        business_infos:
          annual_revenue:
            amount: 5000000
            currency: BRL
          average_ticket:
            amount: 500000
            currency: BRL
        consent:
          consent_at: '2026-08-25T07:00:00.000000Z'
          ip_address: 8.8.8.8
          tax_number: '52998224725'
        entity_id: 01a0ee9f-7418-625f-e4b2-624b4ad4959f
        external_id: 404ANVIL
        inserted_at: '2026-09-29T19:23:42.485921Z'
        name: ACME INC
        org_id: 92b0f620-7105-4c10-84a1-f5a034a14efa
        representatives:
          - email: w.coyote@acme.com
            id: 8c61c7fd-3509-4306-9fec-9090e82fe121
            name: Willy Coyote
            phone: '+5541999990000'
            required_documents:
              - identification
            status: in_validation
            tax_number: '52998224725'
        required_documents:
          - company_contract
        status: in_validation
        tax_number: '61775921000110'
        updated_at: '2026-09-29T19:23:42.485921Z'
      properties:
        business_infos:
          description: Business information sent in the request
          properties:
            annual_revenue:
              description: Annual revenue
              nullable: true
              properties:
                amount:
                  description: Amount in cents
                  type: integer
                  x-struct: null
                  x-validate: null
                currency:
                  description: Currency
                  type: string
                  x-struct: null
                  x-validate: null
              type: object
              x-struct: null
              x-validate: null
            average_ticket:
              description: Average ticket
              nullable: true
              properties:
                amount:
                  description: Amount in cents
                  type: integer
                  x-struct: null
                  x-validate: null
                currency:
                  description: Currency
                  type: string
                  x-struct: null
                  x-validate: null
              type: object
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
        consent:
          description: Consent sent in the request
          properties:
            consent_at:
              description: When the representative consented
              format: date-time
              type: string
              x-struct: null
              x-validate: null
            ip_address:
              description: IP address of the consent
              type: string
              x-struct: null
              x-validate: null
            tax_number:
              description: CPF of the representative who consented
              nullable: true
              type: string
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
        entity_id:
          description: Entity ID
          format: uuid
          type: string
          x-struct: null
          x-validate: null
        external_id:
          description: External ID
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        inserted_at:
          description: When the entity was registered
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        name:
          description: Name of the entity as registered at Receita Federal
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        org_id:
          description: >-
            Org created for the onboarded entity, to act on it with the
            Trio-Target-Org-Id header
          format: uuid
          type: string
          x-struct: null
          x-validate: null
        representatives:
          description: Legal representatives sent in the request
          items:
            properties:
              email:
                description: Email of the representative
                type: string
                x-struct: null
                x-validate: null
              id:
                description: >-
                  Representative ID, the reference_id of its documents in POST
                  /v2/onboarding/documents
                format: uuid
                type: string
                x-struct: null
                x-validate: null
              name:
                description: Name of the representative
                type: string
                x-struct: null
                x-validate: null
              phone:
                description: Phone number of the representative, in E.164 format
                nullable: true
                type: string
                x-struct: null
                x-validate: null
              required_documents:
                description: Documents to upload for the representative
                items:
                  enum:
                    - identification
                  type: string
                  x-struct: null
                  x-validate: null
                type: array
                x-struct: null
                x-validate: null
              status:
                description: Representative validation status
                enum:
                  - in_validation
                  - in_review
                  - rejected
                  - approved
                type: string
                x-struct: null
                x-validate: null
              tax_number:
                description: CPF of the representative
                type: string
                x-struct: null
                x-validate: null
            type: object
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
        required_documents:
          description: Documents to upload for the entity
          items:
            enum:
              - power_of_attorney
              - company_contract
              - financial_statement
            type: string
            x-struct: null
            x-validate: null
          type: array
          x-struct: null
          x-validate: null
        status:
          description: Onboarding status
          enum:
            - in_validation
            - in_review
            - rejected
            - approved
          type: string
          x-struct: null
          x-validate: null
        tax_number:
          description: CNPJ of the entity
          type: string
          x-struct: null
          x-validate: null
        updated_at:
          description: When the entity was last updated
          format: date-time
          type: string
          x-struct: null
          x-validate: null
      title: V2 entity onboard data
      type: object
      x-struct: Elixir.TrioFoundationWeb.Schemas.Onboarding.V2.Entity.EntityData
      x-validate: null
    Money:
      description: Money
      nullable: true
      properties:
        amount:
          description: Amount of the money
          minimum: 1
          type: integer
          x-struct: null
          x-validate: null
        currency:
          $ref: '#/components/schemas/Currency'
      required:
        - amount
        - currency
      title: Money
      type: object
      x-struct: null
      x-validate: null
    Currency:
      description: Currency
      items:
        enum:
          - BRL
        type: string
        x-struct: null
        x-validate: null
      title: Currency
      type: string
      x-struct: null
      x-validate: null
  securitySchemes:
    authorization:
      scheme: basic
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.