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

# Onboard a Corporate Customer with KYB and UBO Verification

> Verify a business entity against official company registries, retrieve its ownership structure, and run KYC and AML screening on each ultimate beneficial owner.

Onboarding a corporate customer requires more than verifying the company name — you need to confirm the business is legitimately registered, identify who controls it, and screen those individuals for sanctions, PEP exposure, and adverse media. Youverify handles all of this through a single entity-centric model: the business entity carries its ownership graph, and each UBO can be promoted to its own entity for full KYC and AML treatment.

This guide walks you through creating a business entity, triggering a KYB registry check, screening the business and its UBOs for AML risks, and linking verified UBO entities back to the parent business.

## Prerequisites

* A Youverify account at [cowork.youverify.co](https://cowork.youverify.co)
* Your API secret key from the dashboard under **Settings → API Keys**
* The business's registered name, registration number, and country of incorporation

***

## Supported countries for KYB

<Note>
  KYB registry checks are available for **Nigeria**, **Kenya**, **South Africa**, and **Côte d'Ivoire**, with additional countries available via the global business verification endpoint. Contact your Youverify account team or consult the dashboard for the complete, up-to-date list.
</Note>

***

## Steps

<Steps>
  ### Create the business entity

  Send a `POST /v2/api/entities` request with `entityType: "business"` and the company's incorporation details. The platform creates the entity, runs an automatic AML screen against the company name, and returns a `Created` entity with an initial risk score.

  <CodeGroup>
    ```bash cURL theme={null}
    curl -X POST "https://api.youverify.co/v2/api/entities" \
      -H "token: $YV_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "entityType": "business",
        "isSubjectConsent": true,
        "incorporationName": "Acme Payments Ltd",
        "incorporationNumber": "RC123456",
        "incorporationCountry": "NG",
        "incorporationDate": "2015-03-20",
        "businessType": "Fintech",
        "address": "12 Marina Street, Lagos"
      }'
    ```

    ```javascript Node.js theme={null}
    const response = await fetch('https://api.youverify.co/v2/api/entities', {
      method: 'POST',
      headers: {
        'token': process.env.YV_SECRET_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        entityType: 'business',
        isSubjectConsent: true,
        incorporationName: 'Acme Payments Ltd',
        incorporationNumber: 'RC123456',
        incorporationCountry: 'NG',
        incorporationDate: '2015-03-20',
        businessType: 'Fintech',
        address: '12 Marina Street, Lagos',
      }),
    });
    const { data } = await response.json();
    const entityId = data.id;
    ```

    ```python Python theme={null}
    import os, requests

    resp = requests.post(
        'https://api.youverify.co/v2/api/entities',
        headers={
            'token': os.environ['YV_SECRET_KEY'],
            'Content-Type': 'application/json',
        },
        json={
            'entityType': 'business',
            'isSubjectConsent': True,
            'incorporationName': 'Acme Payments Ltd',
            'incorporationNumber': 'RC123456',
            'incorporationCountry': 'NG',
            'incorporationDate': '2015-03-20',
            'businessType': 'Fintech',
            'address': '12 Marina Street, Lagos',
        },
    )
    entity_id = resp.json()['data']['id']
    ```
  </CodeGroup>

  ```json Response theme={null}
  {
    "success": true,
    "status_code": 201,
    "message": "Entity created successfully.",
    "data": {
      "id": "ent_69dab0119abad240d91071a4",
      "businessId": "61d880f1e8e15aaf24558f1a",
      "createdBy": {
        "firstName": "Timothy",
        "lastName": "Akinyelu",
        "middleName": "",
        "id": "61f162ec1fd251c3a63f31c2"
      }
    },
    "links": []
  }
  ```

  ### Run the KYB registry check

  Cross-reference the company against the official company registry using `POST /v2/api/entities/{id}/verify/kyb`. Supply the registration number, country, and check type. Use `"standard"` for most cases; `"premium"` returns additional ownership data where available.

  <CodeGroup>
    ```bash cURL theme={null}
    curl -X POST "https://api.youverify.co/v2/api/entities/ent_69dab0119abad240d91071a4/verify/kyb" \
      -H "token: $YV_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "entityType": "business",
        "isSubjectConsent": true,
        "incorporationNumber": "RC123456",
        "incorporationCountry": "NG",
        "checkType": "standard"
      }'
    ```

    ```javascript Node.js theme={null}
    const response = await fetch(
      `https://api.youverify.co/v2/api/entities/${entityId}/verify/kyb`,
      {
        method: 'POST',
        headers: {
          'token': process.env.YV_SECRET_KEY,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          entityType: 'business',
          isSubjectConsent: true,
          incorporationNumber: 'RC123456',
          incorporationCountry: 'NG',
          checkType: 'standard',
        }),
      }
    );
    const result = await response.json();
    ```
  </CodeGroup>

  The response returns the verified company record including registration status, entity type, registration date, and — where the registry provides it — directors and ownership data:

  ```json Response — KYB found theme={null}
  {
    "success": true,
    "status_code": 200,
    "message": "Business check successful!",
    "data": {
      "id": "ent_69dab0119abad240d91071a4",
      "entity": {
        "entityId": "ent_69dab0119abad240d91071a4",
        "isNew": false
      },
      "businessCheck": {
        "id": "69dab502682626b4e9e6d77c",
        "status": "found",
        "name": "Acme Payments Ltd",
        "registrationNumber": "RC123456",
        "companyStatus": "ACTIVE",
        "typeOfEntity": "PRIVATE COMPANY LIMITED BY SHARES",
        "registrationDate": "2015-03-20",
        "country": "Nigeria",
        "directors": [
          {
            "firstName": "Michael",
            "lastName": "Okonkwo",
            "designation": "DIRECTOR"
          }
        ]
      }
    },
    "links": []
  }
  ```

  <Warning>
    If `"status": "not_found"` is returned, the registration number does not match any active record in the registry. Verify the number with the customer before proceeding — do not approve the entity until the discrepancy is resolved.
  </Warning>

  ### Screen the business and its UBOs for AML risks

  Run AML screening on the business entity using `POST /v2/api/entities/{id}/verify/aml`. Supply UBO details in the `ubos` block — the platform runs individual checks on each person simultaneously.

  ```bash cURL theme={null}
  curl -X POST "https://api.youverify.co/v2/api/entities/ent_69dab0119abad240d91071a4/verify/aml" \
    -H "token: $YV_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityType": "business",
      "isSubjectConsent": true,
      "incorporationName": "Acme Payments Ltd",
      "incorporationCountry": "NG",
      "amlCheckType": "name",
      "amlChecks": ["pep", "sanctions", "adverseMedia"],
      "ubos": {
        "uboList": [
          {
            "category": "individual",
            "firstName": "Michael",
            "lastName": "Okonkwo"
          },
          {
            "category": "individual",
            "firstName": "Amina",
            "lastName": "Bello"
          }
        ],
        "amlChecks": ["pep", "sanctions", "adverseMedia"]
      }
    }'
  ```

  <Tip>
    AML screening also runs automatically at entity creation. The explicit `verify/aml` call is for supplementary or re-screening — for example, when the ownership structure has changed or you are screening UBOs from registry data.
  </Tip>

  ### Create individual entities for each UBO and run KYC

  For full KYB compliance, promote each UBO to its own entity. This attaches the UBO to the parent business via `parentId` and allows you to run KYC verification on them individually.

  **Create the UBO entity:**

  ```bash cURL theme={null}
  curl -X POST "https://api.youverify.co/v2/api/entities" \
    -H "token: $YV_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityType": "individual",
      "isSubjectConsent": true,
      "firstName": "Michael",
      "lastName": "Okonkwo",
      "phone": "+2348090000001",
      "nationality": "NG",
      "parentId": "ent_69dab0119abad240d91071a4"
    }'
  ```

  The `parentId` field links this individual to the business entity. The platform's ownership graph reflects the relationship, and you can retrieve the business's full UBO list at any time:

  ```bash cURL theme={null}
  curl -X GET "https://api.youverify.co/v2/api/entities/ent_69dab0119abad240d91071a4" \
    -H "token: $YV_SECRET_KEY"
  ```

  **Run KYC on the UBO:**

  ```bash cURL theme={null}
  curl -X POST "https://api.youverify.co/v2/api/entities/ent_UBO_ENTITY_ID/verify/kyc" \
    -H "token: $YV_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityType": "individual",
      "isSubjectConsent": true,
      "identity": {
        "id": "22222222222",
        "countryCode": "NG",
        "idType": "bvn"
      },
      "validations": {
        "data": {
          "firstName": "Michael",
          "lastName": "Okonkwo"
        }
      }
    }'
  ```

  Repeat this step for each UBO retrieved from the registry or ownership graph.

  ### Retrieve the full business 360

  Once KYB, AML, and UBO KYC are complete, retrieve the business entity to see its complete 360: verification history, ownership graph, risk score, and any signals raised.

  ```bash cURL theme={null}
  curl -X GET "https://api.youverify.co/v2/api/entities/ent_69dab0119abad240d91071a4" \
    -H "token: $YV_SECRET_KEY"
  ```

  The ownership graph in the response reflects all linked UBOs, their verification status, and their individual risk scores:

  ```json Ownership graph (excerpt) theme={null}
  {
    "ubos": [
      {
        "designation": "DIRECTOR",
        "principalOwner": true,
        "firstName": "Michael",
        "lastName": "Okonkwo",
        "entityId": "ent_ubo_abc123",
        "verificationStatus": "found",
        "riskLevel": "low"
      },
      {
        "designation": "SHAREHOLDER",
        "sharesCount": 9990000,
        "firstName": "Amina",
        "lastName": "Bello",
        "entityId": "ent_ubo_def456",
        "verificationStatus": "found",
        "riskLevel": "low"
      }
    ]
  }
  ```
</Steps>

***

## What happens in the background

The moment you create the business entity, Youverify automatically runs a company-level AML screen. The explicit KYB and UBO calls are deliberate steps you control:

```
Your system                Youverify API             Company Registry      AML Engine
    |                           |                           |                  |
    |-- POST /entities -------> |                           |                  |
    |<-- 201 entityId ----------|                           |                  |
    |                           |-- auto AML screen ------> |                  |
    |                           |<-- initial risk score ----                   |
    |-- POST /entities/{id}/verify/kyb --------> |          |                  |
    |                           |-- registry lookup ------> |                  |
    |                           |<-- status · directors ----                   |
    |<-- KYB result ------------|                           |                  |
    |-- POST /entities/{id}/verify/aml --------> |                             |
    |                           |-- UBO AML checks --------------------------------->|
    |<-- per-UBO PEP/sanctions --|                                             |
```

***

## KYB check types

| `checkType` | What it returns |
| - | - |
| `basic` | Company name, registration number, status, registration date |
| `standard` | Basic + directors, entity type, nature of business |
| `premium` | Standard + UBO ownership graph (where registry provides it) |

***

## What's next

* Run [AML screening](/api-reference/entities/verify-entity-aml) on individual UBO entities
* Review the [KYB API reference](/api-reference/entities/verify-entity-kyb) for all available parameters
* Read the [Entity 360](/concepts/entity-360) to understand the ownership graph and how to traverse it
* Set up [webhooks](/webhooks/overview) to receive KYB completion and AML signal events