Skip to content
ClearDil Docs

API Ultimate Business Owner Identification

Get Started > API User Guide > Ultimate Business Owner Identification

Ultimate Business Owner Identification

ClearDil UBO Identification lets you look up company records in the Global Database, retrieve ownership (shareholder) data, and persist those shareholders against a COMPANY customer.

This guide covers the straightforward force-create flow: ClearDil auto-creates customer records for shareholders and finalises ownership links, without a manual reconciliation step against existing customers.

Typical sequence:

  1. Create (or reuse) a COMPANY customer
  2. Search companies, then fetch company details
  3. Start an ownership preview with forceCreate: true
  4. Finalise the preview to create shareholder links
  5. List the company’s shareholders

Search companies

Search the Global Database by company name (and optionally country).

Example request:

Terminal window
curl -X POST 'https://sandbox.cleardil.com/v1/tools/companies/search?page=0&size=10' \
  -H 'Authorization: Bearer your_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_name": "Acme Holdings",
    "country_code": "GB"
  }'

Example response:

{
  "content": [
    {
      "id": "22401777",
      "company_name": "Acme Holdings Limited",
      "registration_number": "12345678",
      "country_code": "GB",
      "status": "Active"
    }
  ],
  "totalElements": 1,
  "number": 0,
  "size": 10
}

Use the company id from the search results as the external company id in the next steps.

Fetch company details

GET returns cached details only (404 if nothing is cached).
POST …/fetch loads fresh data from the Global Database and optionally links the company to your customer via customerId.

Example request:

Terminal window
curl -X POST https://sandbox.cleardil.com/v1/tools/companies/{company_id}/fetch \
  -H 'Authorization: Bearer your_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "{customer_id}"
  }'

Example response:

{
  "external_id": "22401777",
  "company_name": "Acme Holdings Limited",
  "registration_number": "12345678",
  "country_code": "GB",
  "status": "Active",
  "founding_date": "2010-01-15",
  "address": {
    "line": "1 Example Street",
    "city": "London",
    "postal_code": "EC1A 1BB",
    "country": "United Kingdom"
  },
  "contact": {
    "email": "info@acme.example",
    "website": "https://acme.example"
  }
}

When customerId is provided, ClearDil sets company_analysis_id on that COMPANY customer to the external company id.

Create an ownership preview (force-create)

Start a preview for your COMPANY customer. With forceCreate: true, ClearDil fetches ownership from the Global Database and auto-creates customer records for shareholders that do not already match an existing customer. Auto-created customers receive a generated email in the form {name}@cleardil.gen.

companyId is the external Global Database company id (for example from search), not the ClearDil customer uid.

Example request:

Terminal window
curl -X POST https://sandbox.cleardil.com/v1/customers/{customer_id}/ownership-previews \
  -H 'Authorization: Bearer your_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "companyId": "22401777",
    "forceCreate": true
  }'

Example response:

{
  "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "company_customer_id": "{customer_id}",
  "external_company_id": "22401777",
  "force_create": true,
  "status": "IN_PROGRESS",
  "shareholder_count": 2,
  "created_at": "2026-03-01T10:15:00Z",
  "shareholders": [
    {
      "uid": "e1111111-1111-1111-1111-111111111111",
      "raw_name": "Jane Doe",
      "shareholder_type": "INDIVIDUAL",
      "ownership_percentage": 60.0,
      "status": "CREATED",
      "resolved_customer_id": "c1111111-1111-1111-1111-111111111111"
    },
    {
      "uid": "e2222222-2222-2222-2222-222222222222",
      "raw_name": "Beta Investments Limited",
      "shareholder_type": "COMPANY",
      "ownership_percentage": 40.0,
      "status": "CREATED",
      "resolved_customer_id": "c2222222-2222-2222-2222-222222222222"
    }
  ]
}

In this force-create path, shareholder entries should reach CREATED so you can finalise without confirm/reject/assign steps.

Finalise the preview

Persist versioned shareholder links from the preview.

Example request:

Terminal window
curl -X POST https://sandbox.cleardil.com/v1/customers/{customer_id}/ownership-previews/{preview_uid}/shareholders \
  -H 'Authorization: Bearer your_token' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example response:

{
  "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "company_customer_id": "{customer_id}",
  "external_company_id": "22401777",
  "force_create": true,
  "status": "COMPLETED",
  "shareholder_count": 2
}

List shareholders

Retrieve the active shareholders linked to the COMPANY customer.

Example request:

Terminal window
curl -X GET https://sandbox.cleardil.com/v1/customers/{customer_id}/shareholders \
  -H 'Authorization: Bearer your_token'

Example response:

[
  {
    "uid": "l1111111-1111-1111-1111-111111111111",
    "company_customer_id": "{customer_id}",
    "shareholder_customer_id": "c1111111-1111-1111-1111-111111111111",
    "shareholder_type": "INDIVIDUAL",
    "ownership_percentage": 60.0,
    "from_date": "2026-03-01",
    "to_date": null
  },
  {
    "uid": "l2222222-2222-2222-2222-222222222222",
    "company_customer_id": "{customer_id}",
    "shareholder_customer_id": "c2222222-2222-2222-2222-222222222222",
    "shareholder_type": "COMPANY",
    "ownership_percentage": 40.0,
    "from_date": "2026-03-01",
    "to_date": null
  }
]

Please refer to the API reference for endpoint attributes and further detail.