# 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 %}