Manage UBOs

A UBO is a natural person who owns or controls a company. In Entities a UBO is not a separate object: it is a link between a COMPANY entity and an INDIVIDUAL entity.

Prerequisites

The company registered as a COMPANY entity. See Create an Entity.
Each owner registered as an INDIVIDUAL entity, with their own documents and files.
The internalId of the company and of each owner.

Flow

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart TD
    A["1. Create each owner<br/>POST /api/entity/v1/entities (INDIVIDUAL)"] --> B["2. Upload their proofs"]
    C["3. Create the company<br/>POST /api/entity/v1/entities (COMPANY)"] --> D["4. Upload the company proofs"]
    B --> E["5. Link each owner<br/>POST /api/entity/v1/entities/{companyId}/ubos"]
    D --> E
    E --> F["6. GET /api/entity/v1/entities/{companyId}<br/>uboCount, uboRequirementMet"]
    F --> G["7. Localpayment reviews<br/>the company and each owner"]:::lp
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px

The link needs both internalId values, so create the entities first. Owners can be linked while the company is still PENDING_KYC.

Link an owner

Link Jane Doe as CEO with 60% ownership:

curl -X POST https://api.stage.localpayment.com/api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos \
  -H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"personId": "c1e384f5-ae1c-475e-9e64-a0abe533a96f", "ownershipPercentage": 60.0, "controlRole": "CEO"}'

{
  "id": "4584b476-ccc6-4e98-be40-0c5082748e35",
  "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "personId": "c1e384f5-ae1c-475e-9e64-a0abe533a96f",
  "ownershipPercentage": 60.0,
  "controlRole": "CEO",
  "validFrom": "2024-01-15",
  "validTo": null,
  "createdAt": "2024-01-15T17:20:47Z"
}

Link John Doe as partner with 40%. Send the role in upper case; lower or mixed case (Partner) returns 422 INVALID_CONTROL_ROLE:

{
  "personId": "8f5b2c9a-1caf-4b2c-b085-82bbaead6ddd",
  "ownershipPercentage": 40,
  "controlRole": "PARTNER",
  "validFrom": "2023-06-01"
}

{
  "id": "2c203b2b-5f92-427d-a75f-92981e2719bf",
  "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "personId": "8f5b2c9a-1caf-4b2c-b085-82bbaead6ddd",
  "ownershipPercentage": 40.0,
  "controlRole": "PARTNER",
  "validFrom": "2023-06-01",
  "validTo": null,
  "createdAt": "2024-01-15T17:20:48Z"
}

After linking, Get an Entity on the company returns uboCount and uboRequirementMet.

Rules

Rule	Behavior
Types	companyId must be a COMPANY and personId an INDIVIDUAL (422 INVALID_ENTITY_TYPE).
Company status	Not CLOSED, BLOCKED, or REJECTED (422 ENTITY_NOT_ACTIVE). While it is IN_REVIEW, links cannot be created, changed, or ended (409 ENTITY_IN_REVIEW).
Percentage	0 to 100 with up to two decimals (422 INVALID_PERCENTAGE). Send `null` when the percentage is unknown.
Role	One of the role codes listed in Link a UBO, case-sensitive (422 INVALID_CONTROL_ROLE). Values: `LEGAL_REPRESENTATIVE` for the legal representative, `AUTHORIZED_SIGNATORY` for a person who signs under a power of attorney, and an owner's role such as `CEO`, `DIRECTOR`, `PARTNER`, or `OWNER` (full list in the KYB Requirements option lists).
Validity	validFrom defaults to today. validTo must not precede it (422 INVALID_VALIDITY_RANGE).
Limits	50 active links per company (409 UBO_LIMIT_EXCEEDED). One active link per person and company (409 UBO_ALREADY_LINKED).
Privacy	UBO responses carry identifiers only. Read the person with Get an Entity.

Error when you link the same person twice:

{
  "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": "acdfa68b-e1da-4764-84df-0a1e949d0939",
  "details": []
}

Treat UBO_ALREADY_LINKED as a success when you retry a link, and read the current links with List UBOs of a Company.

Maintain links

Change the percentage or the role: Update a UBO. The role cannot be cleared: change it to another code, or end the link with End a UBO Link and link the person again without controlRole.
End an ownership: End a UBO Link sets validTo to today. The history is kept and visible with includeEnded=true.
See it from the person's side: List Companies of a Person.

{
  "items": [
    {
      "id": "4584b476-ccc6-4e98-be40-0c5082748e35",
      "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "personId": "c1e384f5-ae1c-475e-9e64-a0abe533a96f",
      "ownershipPercentage": 55.5,
      "controlRole": null,
      "validFrom": "2024-01-15",
      "validTo": null,
      "createdAt": "2024-01-15T17:20:47Z"
    },
    {
      "id": "2c203b2b-5f92-427d-a75f-92981e2719bf",
      "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "personId": "8f5b2c9a-1caf-4b2c-b085-82bbaead6ddd",
      "ownershipPercentage": 40.0,
      "controlRole": "PARTNER",
      "validFrom": "2023-06-01",
      "validTo": "2024-01-15",
      "createdAt": "2024-01-15T17:20:48Z"
    }
  ]
}

⚠️
Each owner is an entity with its own KYC, reviewed by Localpayment together with the company. uboRequirementMet only tells you that at least one owner is linked, not that the owners are approved.

Next steps

Track the Review and Fix Rejections

Follow the review of the company and each owner.

Link a UBO reference

All request fields, response fields, and error codes.