# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.