> For the complete documentation index, see [llms.txt](https://doc.youverify.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.youverify.co/know-your-transaction-service-kyt/customer-management/create-a-business-client.md).

# Create a Business Client

<mark style="color:green;">`POST`</mark> `{{baseurl}}/v1/api/actors`

This endpoint allows you to create a business client, also known as a business actor or entity, depending on your nomenclature. This is typically a business entity with which you have a business or commercial relationship.&#x20;

### Header

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API token   |

### **Body**

| Field                                                    | Type      | Description                                                                                                                                                                                |
| -------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| actorType<mark style="color:red;">\*</mark>              | String    | type of actor <mark style="color:red;">`"legal_entity"`</mark>.                                                                                                                            |
| externalAccountId<mark style="color:red;">\*</mark>      | String    | external identifier for the client.                                                                                                                                                        |
| customerSegmentation<mark style="color:red;">\*</mark>   | String\[] | Array of strings of actor category based on business customer segmentation.                                                                                                                |
| accountNumbers<mark style="color:red;">\*</mark>         | Object\[] | array of account numbers belonging to the actor.                                                                                                                                           |
| accountType<mark style="color:red;">\*</mark>            | String    | type of account.                                                                                                                                                                           |
| accountNumber<mark style="color:red;">\*</mark>          | String    | account number.                                                                                                                                                                            |
| domicile                                                 | String    | country code where account is domiciled.                                                                                                                                                   |
| accountCreationDate<mark style="color:red;">\*</mark>    | String    | Date account number was created.                                                                                                                                                           |
| phones                                                   | Object\[] | Array of phone numbers belonging to the actor.                                                                                                                                             |
| numberType                                               | String    | type of the phone number <mark style="color:red;">`"office"`</mark>.                                                                                                                       |
| countryCode<mark style="color:red;">\*</mark>            | String    | country code.                                                                                                                                                                              |
| phone<mark style="color:red;">\*</mark>                  | String    | phone number.                                                                                                                                                                              |
| socials                                                  | Object\[] | Array of social media accounts belonging to the actor.                                                                                                                                     |
| type                                                     | String    | social media platform of the social account.                                                                                                                                               |
| handle                                                   | String    | social media handle of the social account.                                                                                                                                                 |
| emails                                                   | Object\[] | Array of email addresses belonging to the actor.                                                                                                                                           |
| emailType                                                | String    | type of the email account <mark style="color:red;">`"office"`</mark>.                                                                                                                      |
| address                                                  | String    | address of the email account.                                                                                                                                                              |
| idType<mark style="color:red;">\*</mark>                 | String    | Type of ID.                                                                                                                                                                                |
| value<mark style="color:red;">\*</mark>                  | String    | number of ID.                                                                                                                                                                              |
| issuingAuthority                                         | String    | organisation issuing the ID.                                                                                                                                                               |
| expirationDate                                           | String    | Date the ID expires.                                                                                                                                                                       |
| addresses<mark style="color:red;">\*</mark>              | Object\[] | Array of addresses belonging to the actor.                                                                                                                                                 |
| addressType                                              | String    | type of the address <mark style="color:red;">`"office"`</mark>.                                                                                                                            |
| line1<mark style="color:red;">\*</mark>                  | String    | address line 1                                                                                                                                                                             |
| line2                                                    | String    | address line 2                                                                                                                                                                             |
| postCode<mark style="color:red;">\*</mark>               | String    | post/zip code                                                                                                                                                                              |
| city<mark style="color:red;">\*</mark>                   | String    | address city                                                                                                                                                                               |
| state<mark style="color:red;">\*</mark>                  | String    | address state/province                                                                                                                                                                     |
| country<mark style="color:red;">\*</mark>                | String    | address country                                                                                                                                                                            |
| lengthOfStay<mark style="color:red;">\*</mark>           | String    | length of stay in address <mark style="color:red;">`in months`</mark>                                                                                                                      |
| legalEntity<mark style="color:red;">\*</mark>            | Object    | details of incorporation if the actor is a legal entity.                                                                                                                                   |
| dateOfRegistration                                       | String    | Date of registration of business                                                                                                                                                           |
| type<mark style="color:red;">\*</mark>                   | String    | type of business entity                                                                                                                                                                    |
| registrationNumber<mark style="color:red;">\*</mark>     | String    | business registration number                                                                                                                                                               |
| industryClassification<mark style="color:red;">\*</mark> | String    | industry of business                                                                                                                                                                       |
| url                                                      | String    | website url of business                                                                                                                                                                    |
| countryOfIncorporation                                   | String    | country of Incorporation of business                                                                                                                                                       |
| legalEntityDirectors<mark style="color:red;">\*</mark>   | Object\[] | details of directors of the business <mark style="color:red;">`at least one director is required`</mark>.                                                                                  |
| name<mark style="color:red;">\*</mark>                   | String    | name of director                                                                                                                                                                           |
| sourceOfIncome<mark style="color:red;">\*</mark>         | String    | source of income of director                                                                                                                                                               |
| industry<mark style="color:red;">\*</mark>               | String    | industry of director                                                                                                                                                                       |
| phoneNumbers<mark style="color:red;">\*</mark>           | Object\[] | Array of phone numbers belonging to director                                                                                                                                               |
| countryCode<mark style="color:red;">\*</mark>            | String    | country code                                                                                                                                                                               |
| phone<mark style="color:red;">\*</mark>                  | String    | phone number                                                                                                                                                                               |
| emails<mark style="color:red;">\*</mark>                 | String\[] | Array of emails belonging to director                                                                                                                                                      |
| uniqueIdentifier<mark style="color:red;">\*</mark>       | Object\[] | ID of director                                                                                                                                                                             |
| issuingCountry<mark style="color:red;">\*</mark>         | String    | Issuing Country of ID                                                                                                                                                                      |
| idType<mark style="color:red;">\*</mark>                 | String    | type of ID                                                                                                                                                                                 |
| idNumber<mark style="color:red;">\*</mark>               | String    | Number of ID                                                                                                                                                                               |
| kycVerifiedBy<mark style="color:red;">\*</mark>          | String    | KYC verified By one of <mark style="color:red;">`youverify - if KYC was verified by youverify, client - if KYC was verified by client, not_verified - if KYC has not been verified`</mark> |
| verificationId                                           | String    | youverify KYC verification ID - <mark style="color:red;">`if KYC was verified by youverify`</mark>                                                                                         |

{% tabs %}
{% tab title="Sample Request for Legal Entities" %}

```json
{
        "actorType": "legal_entity",
        "businessName": "hewlett packard",
        "customerSegmentation": ["business clients", "high profile"],
        "KycVerifiedBy": "youverify",
        "verificationId": "642eb06f0d84552686540c36",
        "accountNumbers": [
                      {
                       "accountType": "personal",
                       "accountNumber": "00000000000",
                       "domicile": "US",
                       "accountCreationDate": "2013-09-09"
                      }
                  ],
        "phones": [
                     {
                       "numberType": "office",
                       "phone": "00000000000"
                     }
                 ],
        "socials": [
                     {
                       "type": "twitter",
                       "handle": "john_doe"
                     }
                 ],
        "emails": [
                     {
                       "emailType": "personal",
                       "address": "johndoe@gmail.com"
                     }
                 ],
        "governmentIds": [
                     {
                       "idType": "tin",
                       "value": "11111111111",
                       "issuingAuthority": "firs",
                       "expirationDate": "2024-05-20",
                     }
                 ],
       "addresses": [
                     {
                       "addressType": "office",
                       "line1": "39 Wellsfargo",
                       "line2": "apt 8",
                       "postCode": "22222223",
                       "city": "Ferry heights",
                       "state": "New York",
                       "country": "US",
                       "lengthOfStay": "15"
                     }
                 ],
      "legalEntity": {
                       "dateOfRegistration": "1978-06-24",
                       "type": "limited liability ",
                       "url": "www.youverify.co",
                       "industryClassification": "fintech",
                       "registrationNumber": "RC0593067940",
                       "countryOfIncoporation": "US"
                     },
      "legalEntityDirectors": [
                     {
                       "name": "Olu Vichai",
                       "sourceOfIncome": "rental income",
                       "phoneNumbers": [
                                  {
                                      "countryCode": "234", 
                                      "phone": "0000000000"
                                  }
                              ],
                       "emails": ["olureal@gmail.com"],
                       "uniqueIdentifier": {
                           "type": "bvn",
                           "idNumber": "000000000"
                       }
                     }
                 ]
       
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Sample Response for Legal Entity" %}

```json
{
    "success": true,
    "statusCode": 201,
    "message": "Actor created successfully!",
    "data": {
        "parentId": "628b38f03ae28a14f52d4bf7",
        "isDeleted": false,
        "businessId": "6401c96e055bc4df85ac7753",
        "actorType": "legal_entity",
        "businessName": "hewlett packard",
        "KycVerifiedBy": "youverify",
        "verificationId": "642eb06f0d84552686540c36",
        "customerSegmentation": ["business clients", "high profile"],
        "accountNumbers": [
            {
                "_id": "642eb1260d845561cd540c3d",
                "accountType": "personal",
                "accountNumber": "00000000000",
                "domicile": "US",
                "accountCreationDate": "2013-09-09"
            }
        ],
        "phones": [
            {
                "_id": "642eb1260d845515ae540c3e",
                "numberType": "office",
                "phone": "00000000000"
            }
        ],
        "socials": [
            {
                "_id": "642eb1260d8455b6cf540c3f",
                "type": "twitter",
                "handle": "john_doe"
            }
        ],
        "emails": [
            {
                "_id": "642eb1260d8455108a540c40",
                "emailType": "personal",
                "address": "johndoe@gmail.com"
            }
        ],
        "governmentIds": [
            {
                "_id": "642eb1260d8455c6c7540c41",
                "idType": "tin",
                "value": "11111111111",
                "issuingAuthority": "firs",
                "expirationDate": "2025-04-21",
            }
        ],
        "addresses": [
            {
                "_id": "642eb1260d8455712f540c42",
                "addressType": "office",
                "line1": "39 Wellsfargo",
                "line2": "apt 8",
                "postCode": "22222223",
                "city": "Ferry heights",
                "state": "New York",
                "country": "US",
                "lengthOfStay": "20",
                "dateAdded": "2023-04-06T11:46:46.898Z",
                "lastModifiedAt": "2023-04-06T11:46:46.898Z"
            }
        ],
        "legalEntity": {
            "_id": "642eb1260d8455c872540c43",
            "dateOfRegistration": "Sat Jun 24 1978 00:00:00 GMT+0000 (Coordinated Universal Time)",
            "type": "limited liability ",
            "url": "www.youverify.co",
            "industryClassification": "fintech",
            "registrationNumber": "RC0593067940",
            "countryOfIncoporation": "US"
        },
        "legalEntityDirectors": [
            {
                "phoneNumbers": [
                       {
                            "countryCode": "234", 
                            "phone": "0000000000"
                        }            
                    ],
                "emails": [
                    "olureal@gmail.com"
                ],
                "_id": "642eb1260d8455d385540c44",
                "name": "Olu Vichai",
                "sourceOfIncome": "rental income",
                "uniqueIdentifier": {
                    "type": "bvn",
                    "idNumber": "000000000"
                }
            }
        ],
        "createdAt": "2023-04-06T11:46:46.899Z",
        "lastModifiedAt": "2023-04-06T11:46:46.899Z",
        "_createdAt": "2023-04-06T11:46:4646+00:00",
        "_lastModifiedAt": "2023-04-06T11:46:4646+00:00",
        "id": "642eb1260d84550a5e540c3c"
    },
    "links": []
   }
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Error Response" %}

```json
{
  "success": false,
  "statusCode": 404,
  "message": "You have attempted to get a resource that does not exist.",
  "name": "ResourceNotFoundError",
  "data": {}
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc.youverify.co/know-your-transaction-service-kyt/customer-management/create-a-business-client.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.