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

# Vincule um UBO

Vincula uma entidade INDIVIDUAL como beneficiário final (UBO) de uma entidade COMPANY, com o percentual de participação e o papel de controle. Ambas as entidades já devem existir.

* A vinculação é permitida enquanto a empresa estiver em PENDING\_KYC ou ACTIVE. Enquanto estiver em IN\_REVIEW, retorna 409 ENTITY\_IN\_REVIEW; não é permitida quando estiver em CLOSED, BLOCKED ou REJECTED.
* Até 50 vínculos de UBO ativos por empresa. A mesma pessoa não pode ser vinculada duas vezes enquanto houver um vínculo ativo.
* Após a vinculação, Get an Entity na empresa retorna uboCount e uboRequirementMet.

Os erros usam `application/problem+json` com um `code` estável. Catálogo completo: [Entity Statuses and Error Codes](https://docs.localpayment.com/pt-br/reference/entity-statuses-and-error-codes.md).


## OpenAPI

````yaml openapi/pt-br/localpayment.json POST /api/entity/v1/entities/{companyId}/ubos
openapi: 3.1.0
info:
  version: '1.0'
  title: Localpayment
  contact:
    name: Support
    url: mailto:support@localpayment.com
servers:
  - url: https://api.stage.localpayment.com
    description: Stage
security:
  - token: []
paths:
  /api/entity/v1/entities/{companyId}/ubos:
    post:
      summary: Vincule um UBO
      operationId: link-ubo
      parameters:
        - name: Authorization
          in: header
          description: >-
            Token de acesso Bearer para autenticação. Este token é obtido nos
            endpoints [Obter token de acesso](/pt-br/reference/get-token) ou
            [Renovar token de acesso](/pt-br/reference/refresh-token). Sua conta
            de comerciante e o usuário que realiza a ação são identificados a
            partir dele.
          required: true
          schema:
            type: string
            examples:
              - Bearer <your_access_token>
        - name: X-Correlation-ID
          in: header
          description: >-
            Identificador de rastreamento (UUID). Exibido na resposta; gerado
            pelo Localpayment se ausente.
          required: false
          schema:
            type: string
            examples:
              - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
        - name: companyId
          in: path
          description: ID interno da EMPRESA.
          required: true
          schema:
            type: string
            examples:
              - 7c9e6679-7425-40de-944b-e07fc1f90ae7
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                personId:
                  type: string
                  format: uuid
                  description: ID interno do INDIVÍDUO.
                  examples:
                    - c1e384f5-ae1c-475e-9e64-a0abe533a96f
                ownershipPercentage:
                  type:
                    - number
                    - 'null'
                  description: >-
                    De 0 a 100, com até duas casas decimais. Envie null quando a
                    porcentagem for desconhecida e 0 para um representante legal
                    que não possui ações.
                  examples:
                    - 60
                controlRole:
                  type: string
                  description: >-
                    Função da pessoa, um dos 24 códigos. Diferencia maiúsculas
                    de minúsculas: director retorna 422 INVALID_CONTROL_ROLE.
                    Use LEGAL_REPRESENTATIVE para o representante legal e
                    AUTHORIZED_SIGNATORY para uma pessoa que assina mediante
                    procuração.
                  examples:
                    - CEO
                  enum:
                    - CEO
                    - CFO
                    - COO
                    - CTO
                    - PRESIDENT
                    - VICE_PRESIDENT
                    - DIRECTOR
                    - MANAGING_DIRECTOR
                    - MANAGING_PARTNER
                    - GENERAL_PARTNER
                    - PARTNER
                    - SECRETARY
                    - TREASURER
                    - CHAIRMAN
                    - BOARD_MEMBER
                    - AUTHORIZED_SIGNATORY
                    - GENERAL_COUNSEL
                    - OWNER
                    - FOUNDER
                    - MANAGER
                    - MEMBER
                    - COMPTROLLER
                    - CHIEF_COMPLIANCE_OFFICER
                    - LEGAL_REPRESENTATIVE
                validFrom:
                  type: string
                  format: date
                  description: 'AAAA-MM-DD. Padrão: hoje.'
                  examples:
                    - '2024-01-15'
                validTo:
                  type: string
                  format: date
                  description: AAAA-MM-DD, a partir de validFrom. Omita para links abertos.
                  examples:
                    - '2025-01-15'
              required:
                - personId
                - ownershipPercentage
            examples:
              Example 1:
                value:
                  personId: c1e384f5-ae1c-475e-9e64-a0abe533a96f
                  ownershipPercentage: 60
                  controlRole: CEO
      responses:
        '201':
          description: Criado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    examples:
                      - 4584b476-ccc6-4e98-be40-0c5082748e35
                    description: Identificador de link UBO (uboId).
                  companyId:
                    type: string
                    examples:
                      - 7c9e6679-7425-40de-944b-e07fc1f90ae7
                    format: uuid
                    description: A entidade COMPANY.
                  personId:
                    type: string
                    examples:
                      - c1e384f5-ae1c-475e-9e64-a0abe533a96f
                    format: uuid
                    description: >-
                      A entidade INDIVIDUAL. Nenhum dado pessoal da pessoa é
                      retornado aqui.
                  ownershipPercentage:
                    type:
                      - number
                      - 'null'
                    examples:
                      - 60
                    description: >-
                      De 0 a 100, com até duas casas decimais. null quando a
                      porcentagem for desconhecida.
                  controlRole:
                    type: string
                    examples:
                      - CEO
                    description: >-
                      Função em maiúsculas, por exemplo CEO, PARTNER, DIRECTOR,
                      LEGAL_REPRESENTATIVE. null quando não informada.
                  validFrom:
                    type: string
                    examples:
                      - '2024-01-15'
                    format: date
                    description: >-
                      Validade do link. O parâmetro validTo é nulo enquanto o
                      link estiver ativo.
                  validTo:
                    type:
                      - string
                      - 'null'
                    format: date
                    description: >-
                      Validade do link. O parâmetro validTo é nulo enquanto o
                      link estiver ativo.
                  createdAt:
                    type: string
                    examples:
                      - '2024-01-15T17:20:47Z'
                    format: date-time
                    description: Tempo de criação.
              examples:
                Example 1:
                  value:
                    id: 4584b476-ccc6-4e98-be40-0c5082748e35
                    companyId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                    personId: c1e384f5-ae1c-475e-9e64-a0abe533a96f
                    ownershipPercentage: 60
                    controlRole: CEO
                    validFrom: '2024-01-15'
                    validTo: null
                    createdAt: '2024-01-15T17:20:47Z'
        '400':
          description: >-
            Solicitação inválida. VALIDATION_ERROR: Um campo, cabeçalho, caminho
            ou parâmetro de consulta está ausente, é desconhecido ou inválido.
            details[] lista o campo e o problema.
          content:
            application/problem+json:
              schema:
                type: object
                description: >-
                  Detalhes do problema segundo a RFC 9457
                  (application/problem+json).
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: Breve resumo do problema.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  detail:
                    type: string
                    description: Explicação em linguagem acessível a humanos.
                  instance:
                    type: string
                    description: Caminho da solicitação.
                  code:
                    type: string
                    description: >-
                      Código de erro estável e legível por máquina. Faça a
                      ramificação da lógica com base nesse valor.
                  correlationId:
                    type: string
                    format: uuid
                    description: >-
                      Identificador da solicitação. Informe-o ao entrar em
                      contato com o suporte.
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: Campos problemáticos, quando aplicável.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - VALIDATION_ERROR:
                  value:
                    type: about:blank
                    title: Validation error
                    status: 400
                    detail: >-
                      A field, header, path or query parameter is missing,
                      unknown or invalid. details[] lists field and issue.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos
                    code: VALIDATION_ERROR
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details:
                      - field: externalId
                        issue: REQUIRED
        '401':
          description: 'Não autorizado. UNAUTHORIZED: Token de acesso ausente ou inválido.'
          content:
            application/problem+json:
              schema:
                type: object
                description: >-
                  Detalhes do problema segundo a RFC 9457
                  (application/problem+json).
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: Breve resumo do problema.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  detail:
                    type: string
                    description: Explicação em linguagem acessível a humanos.
                  instance:
                    type: string
                    description: Caminho da solicitação.
                  code:
                    type: string
                    description: >-
                      Código de erro estável e legível por máquina. Faça a
                      ramificação da lógica com base nesse valor.
                  correlationId:
                    type: string
                    format: uuid
                    description: >-
                      Identificador da solicitação. Informe-o ao entrar em
                      contato com o suporte.
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: Campos problemáticos, quando aplicável.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - UNAUTHORIZED:
                  value:
                    type: about:blank
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid access token.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos
                    code: UNAUTHORIZED
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
        '404':
          description: >-
            Não encontrado. ENTITY_NOT_FOUND: A entidade não existe ou pertence
            a outro comerciante.
          content:
            application/problem+json:
              schema:
                type: object
                description: >-
                  Detalhes do problema segundo a RFC 9457
                  (application/problem+json).
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: Breve resumo do problema.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  detail:
                    type: string
                    description: Explicação em linguagem acessível a humanos.
                  instance:
                    type: string
                    description: Caminho da solicitação.
                  code:
                    type: string
                    description: >-
                      Código de erro estável e legível por máquina. Faça a
                      ramificação da lógica com base nesse valor.
                  correlationId:
                    type: string
                    format: uuid
                    description: >-
                      Identificador da solicitação. Informe-o ao entrar em
                      contato com o suporte.
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: Campos problemáticos, quando aplicável.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - ENTITY_NOT_FOUND:
                  value:
                    type: about:blank
                    title: Not found
                    status: 404
                    detail: The entity does not exist or belongs to another merchant.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos
                    code: ENTITY_NOT_FOUND
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
        '409':
          description: >-
            Conflito. ENTITY_IN_REVIEW: A entidade está IN_REVIEW: seus dados,
            documentos, arquivos e vínculos de UBO estão congelados até que o
            Compliance da Localpayment a resolva. UBO_ALREADY_LINKED: A pessoa
            já tem um vínculo de UBO ativo com esta empresa. UBO_LIMIT_EXCEEDED:
            A empresa já tem 50 vínculos de UBO ativos.
          content:
            application/problem+json:
              schema:
                type: object
                description: >-
                  Detalhes do problema segundo a RFC 9457
                  (application/problem+json).
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: Breve resumo do problema.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  detail:
                    type: string
                    description: Explicação em linguagem acessível a humanos.
                  instance:
                    type: string
                    description: Caminho da solicitação.
                  code:
                    type: string
                    description: >-
                      Código de erro estável e legível por máquina. Faça a
                      ramificação da lógica com base nesse valor.
                  correlationId:
                    type: string
                    format: uuid
                    description: >-
                      Identificador da solicitação. Informe-o ao entrar em
                      contato com o suporte.
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: Campos problemáticos, quando aplicável.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - ENTITY_IN_REVIEW:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: >-
                      The entity is IN_REVIEW: its data, documents, files and
                      UBO links are frozen until Localpayment Compliance
                      resolves it.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos
                    code: ENTITY_IN_REVIEW
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
                Example 2 - UBO_ALREADY_LINKED:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: Conflict
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos
                    code: UBO_ALREADY_LINKED
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
                Example 3 - UBO_LIMIT_EXCEEDED:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: The company already has 50 active UBO links.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos
                    code: UBO_LIMIT_EXCEEDED
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
        '422':
          description: >-
            Entidade não processável. INVALID_ENTITY_TYPE: companyId deve ser
            uma COMPANY e personId um INDIVIDUAL. ENTITY_NOT_ACTIVE: A empresa
            (ou a pessoa) está CLOSED, BLOCKED ou REJECTED. INVALID_PERCENTAGE:
            ownershipPercentage está fora do intervalo de 0 a 100 ou tem mais de
            duas casas decimais. INVALID_CONTROL_ROLE: controlRole não é um dos
            códigos de função listados em Link a UBO. Os códigos diferenciam
            maiúsculas de minúsculas: director retorna este erro.
            INVALID_VALIDITY_RANGE: validTo é anterior a validFrom.
          content:
            application/problem+json:
              schema:
                type: object
                description: >-
                  Detalhes do problema segundo a RFC 9457
                  (application/problem+json).
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: Breve resumo do problema.
                  status:
                    type: integer
                    description: Código de status HTTP.
                  detail:
                    type: string
                    description: Explicação em linguagem acessível a humanos.
                  instance:
                    type: string
                    description: Caminho da solicitação.
                  code:
                    type: string
                    description: >-
                      Código de erro estável e legível por máquina. Faça a
                      ramificação da lógica com base nesse valor.
                  correlationId:
                    type: string
                    format: uuid
                    description: >-
                      Identificador da solicitação. Informe-o ao entrar em
                      contato com o suporte.
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: Campos problemáticos, quando aplicável.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - INVALID_ENTITY_TYPE:
                  value:
                    type: about:blank
                    title: Unprocessable entity
                    status: 422
                    detail: companyId must be a COMPANY and personId an INDIVIDUAL.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos
                    code: INVALID_ENTITY_TYPE
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
                Example 2 - ENTITY_NOT_ACTIVE:
                  value:
                    type: about:blank
                    title: Unprocessable entity
                    status: 422
                    detail: >-
                      The company (or the person) is CLOSED, BLOCKED or
                      REJECTED.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos
                    code: ENTITY_NOT_ACTIVE
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
                Example 3 - INVALID_PERCENTAGE:
                  value:
                    type: about:blank
                    title: Unprocessable entity
                    status: 422
                    detail: >-
                      ownershipPercentage is outside 0 to 100 or has more than
                      two decimals.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos
                    code: INVALID_PERCENTAGE
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
                Example 4 - INVALID_CONTROL_ROLE:
                  value:
                    type: about:blank
                    title: Unprocessable entity
                    status: 422
                    detail: >-
                      controlRole is not one of the role codes listed in Link a
                      UBO. Codes are case-sensitive: director returns this
                      error.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos
                    code: INVALID_CONTROL_ROLE
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
                Example 5 - INVALID_VALIDITY_RANGE:
                  value:
                    type: about:blank
                    title: Unprocessable entity
                    status: 422
                    detail: validTo is earlier than validFrom.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos
                    code: INVALID_VALIDITY_RANGE
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
      security:
        - token: []
components:
  securitySchemes:
    token:
      type: http
      scheme: bearer

````

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