> For the complete documentation index, see [llms.txt](https://docs.ospree.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ospree.io/developers/accounts-directory/create-account.md).

# Create Account

<mark style="color:yellow;">`POST`</mark> `/api/v2/directory/accounts`

This endpoint is used to create a new account within the directory module. It can create 'individual' or 'entity' accounts.

**Body**

<table><thead><tr><th width="213">Name</th><th width="128">Type</th><th width="257">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>reference_id</code></td><td>string</td><td><p>Unique identifier for the account. </p><p></p><p>Example: <mark style="color:orange;"><code>245352FA</code></mark></p></td><td>True</td></tr><tr><td><code>account_type</code></td><td>string</td><td><p>Type of the account. </p><p></p><p>Accepted Values:</p><ul><li><mark style="color:orange;"><code>individual</code></mark></li><li><mark style="color:orange;"><code>entity</code></mark></li></ul></td><td>True</td></tr><tr><td><code>account_category</code></td><td>string</td><td><p>Category of the account. </p><p></p><p>Accepted values: </p><ul><li><mark style="color:orange;"><code>customer</code></mark> </li><li><mark style="color:orange;"><code>non-customer</code></mark>.</li></ul><p></p><p>Defaults to <mark style="color:orange;"><code>customer</code></mark> when not specified.</p></td><td>False</td></tr><tr><td><code>customer_id</code></td><td>string</td><td><p>Internal identifier of the account. <br><br>Required if at least one of the following is not provided: <br><br>For <strong>individual</strong> accounts: </p><ul><li><mark style="color:orange;"><code>date_of_birth</code></mark> and <mark style="color:orange;"><code>place_of_birth</code></mark></li><li>or <mark style="color:orange;"><code>address</code></mark></li><li>or <mark style="color:orange;"><code>national_id</code></mark></li></ul><p></p><p>For <strong>entity</strong> accounts:</p><ul><li><mark style="color:orange;"><code>address</code></mark></li><li>or <mark style="color:orange;"><code>national_id</code></mark></li></ul></td><td>Conditional</td></tr><tr><td><code>email</code></td><td>string</td><td><p>Email address associated with the account. </p><p></p><p>Example: <mark style="color:orange;"><code>you@company.com</code></mark></p></td><td>False</td></tr><tr><td><code>individual</code></td><td>object</td><td>The object that contains the fields specific for an individual account. <br><br>Refer to the <mark style="color:orange;"><code>Individual Data Type</code></mark> for the complete list of fields.</td><td>Required if <mark style="color:orange;"><code>account_type</code></mark> = <mark style="color:orange;"><code>individual</code></mark></td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="213">Name</th><th width="128">Type</th><th width="257">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>entity</code></td><td>object</td><td>The object that contains the fields specific for an entity account. <br><br>Refer to the <mark style="color:orange;"><code>Entity Data Type</code></mark> for the complete list of fields.</td><td>Required if <mark style="color:orange;"><code>account_type</code></mark> = <mark style="color:orange;"><code>entity</code></mark></td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="213">Name</th><th width="128">Type</th><th width="257">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>address</code></td><td>object</td><td><p>Object describing the address of the account.<br><br>Refer to the <mark style="color:orange;"><code>Address Data Type</code></mark> for the complete list of fields.<br><br>Required if <strong>at least one</strong> of the following are not provided:<br><br>For <strong>individual</strong> accounts:</p><ul><li><mark style="color:orange;"><code>date_of_birth</code></mark> and <mark style="color:orange;"><code>place_of_birth</code></mark></li><li>or <mark style="color:orange;"><code>customer_id</code></mark> </li><li>or <mark style="color:orange;"><code>national_id</code></mark>  </li></ul><p></p><p>For <strong>entity</strong> accounts:</p><ul><li><mark style="color:orange;"><code>customer_id</code></mark> </li><li>or <mark style="color:orange;"><code>national_id</code></mark></li></ul></td><td> Conditional</td></tr><tr><td></td><td></td><td></td><td></td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="213">Name</th><th width="128">Type</th><th width="257">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>national_id</code></td><td>object</td><td><p>Object containing national ID details.<br><br>Refer to the <mark style="color:orange;"><code>National ID Data Type</code></mark> for the complete list of fields.<br><br>Required if <strong>at least one</strong> of the following are not provided:<br><br>For <strong>individual</strong> accounts: </p><ul><li><mark style="color:orange;"><code>date_of_birth</code></mark> and <mark style="color:orange;"><code>place_of_birth</code></mark> </li><li>or <mark style="color:orange;"><code>address</code></mark> </li><li>or <mark style="color:orange;"><code>customer_id</code></mark>  </li></ul><p></p><p>For <strong>entity</strong> accounts:</p><ul><li><mark style="color:orange;"><code>address</code></mark> </li><li>or <mark style="color:orange;"><code>customer_id</code></mark></li></ul></td><td>  Conditional</td></tr></tbody></table>

<details>

<summary><strong>Individual Data Type</strong></summary>

<table><thead><tr><th width="213">Name</th><th width="95.8564453125">Type</th><th width="257">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>individual_name</code></td><td>object</td><td>Object containing the individual name. <br><br>Refer to the <mark style="color:orange;"><code>Name Data Type</code></mark> for the complete list of fields.</td><td>True</td></tr><tr><td><code>individual_localname</code></td><td>object</td><td>Localized version of the individual´s name. <br><br>Refer to the <mark style="color:orange;"><code>Name Data Type</code></mark> for the complete list of fields.</td><td>False</td></tr><tr><td><code>date_of_birth</code></td><td>date</td><td><p>Date of birth of the account holder. </p><p></p><p>Required if <strong>at least one</strong> of the following are not provided:<br><br>For <strong>individual</strong> accounts:</p><ul><li><mark style="color:orange;"><code>customer_id</code></mark> </li><li>or <mark style="color:orange;"><code>address</code></mark></li><li>or <mark style="color:orange;"><code>national_id</code></mark>  </li></ul><p></p><p>Example: 1990-01-01</p></td><td>Conditional</td></tr><tr><td><code>place_of_birth</code></td><td>string</td><td><p>Place of birth of the account holder. </p><p></p><p>Required if <strong>at least one</strong> of the following are not provided:<br><br>For <strong>individual</strong> accounts:</p><ul><li><mark style="color:orange;"><code>customer_id</code></mark> </li><li>or <mark style="color:orange;"><code>address</code></mark></li><li>or <mark style="color:orange;"><code>national_id</code></mark>  </li></ul><p></p><p>Example: Singapore</p></td><td>Conditional</td></tr><tr><td><code>nationality_country</code></td><td>string</td><td><p>Nationality of the individual (ISO 3166-1 alpha-2 country code). </p><p></p><p>Example: SG</p></td><td>False</td></tr><tr><td><code>residence_country</code></td><td>string</td><td><p>Country of residence (ISO 3166-1 alpha-2 code). </p><p></p><p>Example: US</p></td><td>False</td></tr></tbody></table>

**Name Data Type**

<table><thead><tr><th width="213">Name</th><th width="95.8564453125">Type</th><th width="257">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>name_type</code></td><td>string</td><td><p>Type of the name. Required for both <mark style="color:orange;"><code>individual_name</code></mark> and <mark style="color:orange;"><code>individual_localname</code></mark>. </p><p></p><p>Accepted values: </p><ul><li><mark style="color:orange;"><code>LEGL</code></mark></li></ul></td><td>True</td></tr><tr><td><code>name_first</code></td><td>string</td><td><p>First name of the individual. <br></p><p>Example: John</p></td><td>False</td></tr><tr><td><code>name_middle</code></td><td>string</td><td><p>Middle name of the individual. </p><p></p><p>Example: Robert</p></td><td>False</td></tr><tr><td><code>name_last</code></td><td>string</td><td><p>Last name of the individual. </p><p></p><p>Example: Doe</p></td><td>True</td></tr></tbody></table>

</details>

<details>

<summary><strong>Entity Data Type</strong></summary>

<table><thead><tr><th width="215.7197265625">Name</th><th width="85.2119140625">Type</th><th width="269.958984375">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>entity_name</code></td><td>object</td><td><p>Object that contains the legal and business name of the entity. </p><p></p><p>Refer to the <mark style="color:orange;"><code>Name Data Type</code></mark> for the complete list of fields.</p></td><td>True</td></tr><tr><td><code>entity_localname</code></td><td>object</td><td><p>Local language version of the entity name. </p><p></p><p>Refer to the <mark style="color:orange;"><code>Name Data Type</code></mark> for the complete list of fields.</p></td><td>False</td></tr><tr><td><code>registration_country</code></td><td>string</td><td><p>Country of incorporation for the business (ISO 3166-1 alpha-2 country code). </p><p></p><p>Example: SG</p></td><td>False</td></tr></tbody></table>

**Name Data Type**

<table><thead><tr><th width="215.7197265625">Name</th><th width="85.2119140625">Type</th><th width="269.958984375">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>name_type</code></td><td>string</td><td><p>Type of entity name. </p><p></p><p>Accepted values: </p><ul><li><mark style="color:orange;"><code>LEGL</code></mark></li></ul></td><td>True</td></tr><tr><td><code>name_legal</code></td><td>string</td><td><p>Official legal name of the entity. </p><p></p><p>Example: Digital Capital Pte. Ltd.</p></td><td>True</td></tr><tr><td><code>name_business</code></td><td>string</td><td><p>Common or trade name of the business. </p><p></p><p>Example: Digital Capital</p></td><td>False</td></tr></tbody></table>

</details>

<details>

<summary><strong>Address Data Type</strong></summary>

<table><thead><tr><th width="214.6357421875">Name</th><th width="80.646484375">Type</th><th width="275.9453125">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>address_type</code></td><td>string</td><td>Type of address. Common value: "<mark style="color:orange;"><code>GEOG</code></mark>" (Geographic).</td><td>True</td></tr><tr><td><code>address_line</code></td><td>string</td><td>Full address in a single line. Alternatively, use <mark style="color:orange;"><code>address_street_no</code></mark> or <mark style="color:orange;"><code>address_building_name</code></mark> with <mark style="color:orange;"><code>address_street_name</code></mark>. Example: Apt 123</td><td>Conditional</td></tr><tr><td><code>address_street_no</code></td><td>string</td><td>Street number. Must be used with <mark style="color:orange;"><code>address_street_name</code></mark> if <mark style="color:orange;"><code>address_line</code></mark> is not provided. Example: 456</td><td>Conditional</td></tr><tr><td><code>address_street_name</code></td><td>string</td><td>Street name. Required if using <mark style="color:orange;"><code>address_street_no</code></mark> or <mark style="color:orange;"><code>address_building_name</code></mark>. Example: Elm Street</td><td>Conditional</td></tr><tr><td><code>address_building_name</code></td><td>string</td><td>Name of the building where the account holder is located. This field can be used as an alternative to <mark style="color:orange;"><code>address_street_no</code></mark> when combined with <mark style="color:orange;"><code>address_street_name</code></mark>. Example: Elmwood Apartments, TechHub Tower</td><td>Conditional</td></tr><tr><td><code>address_floor</code></td><td>string</td><td>Floor number within the building. Example: 15</td><td>False</td></tr><tr><td><code>address_room</code></td><td>string</td><td>Room number within the building. Example: 1503</td><td>False</td></tr><tr><td><code>address_department</code></td><td>string</td><td>Department at the address (e.g., billing, compliance).</td><td>False</td></tr><tr><td><code>address_subdepartment</code></td><td>string</td><td>Sub-department at the address.</td><td>False</td></tr><tr><td><code>address_postbox</code></td><td>string</td><td>Post office box number. Example: PO Box 789</td><td>False</td></tr><tr><td><code>address_city_location</code></td><td>string</td><td>Local city location reference. Optional, used in some jurisdictions.</td><td>False</td></tr><tr><td><code>address_city</code></td><td>string</td><td>City of the address. Example: New York</td><td>True</td></tr><tr><td><code>address_region</code></td><td>string</td><td>Region, state, or province. Example: New York</td><td>False</td></tr><tr><td><code>address_district</code></td><td>string</td><td>District of the address. Example: Manhattan</td><td>False</td></tr><tr><td><code>address_postcode</code></td><td>string</td><td>Postal code. Example: 08012</td><td>False</td></tr><tr><td><code>address_country_code</code></td><td>string</td><td>ISO 3166-1 alpha-2 country code. Example: US</td><td>True</td></tr></tbody></table>

</details>

<details>

<summary><strong>National ID Data Type</strong></summary>

<table><thead><tr><th width="213">Name</th><th width="78.83984375">Type</th><th width="279.6611328125">Description</th><th>Required</th></tr></thead><tbody><tr><td><code>national_id_type</code></td><td>string</td><td><p>Type of national identification. </p><p></p><p>For Individual Accounts: </p><ul><li><mark style="color:orange;"><code>ARNU</code></mark>- Alien registration number</li><li><mark style="color:orange;"><code>CCPT</code></mark>- Passport number</li><li><mark style="color:orange;"><code>DRLC</code></mark>- Driver License number</li><li><mark style="color:orange;"><code>FIIN</code></mark>- Foreign investment identity number</li><li><mark style="color:orange;"><code>SOCS</code></mark>- Social security number </li><li><mark style="color:orange;"><code>IDCD</code></mark> - Identity card number</li><li><mark style="color:orange;"><code>MISC</code></mark>-  Unspecified </li></ul><p></p><p>For Entity Accounts: </p><ul><li><mark style="color:orange;"><code>RAID</code></mark>- Registration authority identifier</li><li><mark style="color:orange;"><code>TXID</code></mark>- Tax identification number</li><li><mark style="color:orange;"><code>LEIX</code></mark>- Legal Entity Identifier</li><li><mark style="color:orange;"><code>MISC</code></mark>- Unspecified</li></ul><p></p></td><td>True</td></tr><tr><td><code>national_id</code></td><td>string</td><td><p>National identification number assigned to the individual or entity. </p><p></p><p>Example: ABC123456</p></td><td>True</td></tr><tr><td><code>issue_country</code></td><td>string</td><td><p>ISO 3166-1 alpha-2 country code of the country that issued the national identification. </p><p><br>This field must NOT be specified if account_type is <mark style="color:orange;"><code>entity</code></mark>. <br></p><p>Example: US</p></td><td>Conditional</td></tr><tr><td><code>registration_authority</code></td><td>string</td><td><p>Identifier of the national registration authority. </p><p></p><p>Must match an entry in the GLEIF Registration Authorities List. <br><br>This field is required if account_type is <mark style="color:orange;"><code>entity</code></mark> and national_id_type is NOT <mark style="color:orange;"><code>LEIX</code></mark>.</p></td><td>Conditional</td></tr></tbody></table>

</details>

\
**Sample Request**

{% tabs %}
{% tab title="Entity" %}

```json
curl -X POST https://sandbox.ospree.io/api/v2/directory/accounts

-h 'Content-Type: application/json' \
-h 'Accept: application/json' \
-h 'Authorization: ••••••' \
-d '{
  "reference_id": "80MBoQkMNS",
  "account_type": "entity",
  "account_category": "customer",
  "email": "you@company.com",
  "customer_id": "80MBoQkMNS",
​
  "entity": {
    "registration_country": "SG",
    "entity_name": {
      "name_type": "LEGL",
      "name_legal": "Digital Capital",
      "name_business": "Digital Capital Pte. Ltd."
    },
    "entity_localname": {
      "name_type": "LEGL",
      "name_legal": "Digital Capital",
      "name_business": "Digital Capital Pte. Ltd."
    }
​
  },
  "address": {
    "address_type": "GEOG",
    "address_line": "Apt 123",
    "address_street_no": "456",
    "address_street_name": "Elm Street",
    "address_building_name": "Elmwood Apartments",
    "address_floor": "15",
    "address_room": "1503",
    "address_postbox": "PO Box 789",
    "address_city": "New York",
    "address_region": "New York",
    "address_district": "Manhattan",
    "address_postcode": "10001",
    "address_country_code": "US"
  },

  "national_id": {
    "national_id_type": "RAID",
    "national_id": "3523524",
    "registration_authority": "RA999999"
  }
}' 
```

{% endtab %}

{% tab title="200" %}

```json
{
    "status": "success",
    "data": {
        "reference_id": "80MBoQkMNS",
        "account_type": "entity",
        "account_category": "customer",
        "email": "you@company.com",
        "customer_id": "80MBoQkMNS",
        "entity": {
            "entity_name": {
                "name_type": "LEGL",
                "name_legal": "Digital Capital",
                "name_business": "Digital Capital Pte. Ltd."
            },
            "entity_localname": {
                "name_type": "LEGL",
                "name_legal": "Digital Capital",
                "name_business": "Digital Capital Pte. Ltd."
            },
            "registration_country": "SG"
        },
        "address": {
            "address_type": "GEOG",
            "address_line": "Apt 123",
            "address_street_no": "456",
            "address_street_name": "Elm Street",
            "address_building_name": "Elmwood Apartments",
            "address_floor": "15",
            "address_room": "1503",
            "address_postbox": "PO Box 789",
            "address_city": "New York",
            "address_region": "New York",
            "address_district": "Manhattan",
            "address_postcode": "10001",
            "address_country_code": "US"
        },
        "national_id": {
            "national_id_type": "RAID",
            "national_id": "3523524",
            "registration_authority": "RA999999"
        },
        "created": "2025-04-14T23:29:38+00:00",
        "last_modified": "2025-04-14T23:29:38+00:00"
    }
}
```

{% endtab %}
{% endtabs %}

**Sample Request**

{% tabs %}
{% tab title="Individual" %}

```json
curl -X POST https://sandbox.ospree.io/api/v2/directory/accounts

-h 'Content-Type: application/json' \
-h 'Accept: application/json' \
-h 'Authorization: ••••••' \
-d '{
  "reference_id": "qJu7298S4D",
  "account_type": "individual",
  "account_category": "non-customer",
  "email": "you@company.com",
  "customer_id": "qJu7298S4D",

  "individual": {
    "date_of_birth": "1988-06-27",
    "place_of_birth": "Singapore",
    "nationality_country": "SG",
    "residence_country": "US",
    "individual_name": {
      "name_type": "LEGL",
      "name_first": "John",
      "name_middle": "Mark",
      "name_last": "Doe"
    },
    "individual_localname": {
      "name_type": "LEGL",
      "name_first": "John",
      "name_middle": "Mark",
      "name_last": "Doe"
    }

  },
  "address": {
    "address_type": "GEOG",
    "address_line": "Apt 123",
    "address_street_no": "456",
    "address_street_name": "Elm Street",
    "address_building_name": "Elmwood Apartments",
    "address_floor": "15",
    "address_room": "1503",
    "address_postbox": "PO Box 789",
    "address_city": "New York",
    "address_region": "New York",
    "address_district": "Manhattan",
    "address_postcode": "10001",
    "address_country_code": "US"
  }
}' 
```

{% endtab %}

{% tab title="200" %}

```json
{
    "status": "success",
    "data": {
        "reference_id": "qJu7298S4D",
        "account_type": "individual",
        "account_category": "non-customer",
        "email": "you@company.com",
        "individual": {
            "individual_name": {
                "name_type": "LEGL",
                "name_first": "John",
                "name_middle": "Mark",
                "name_last": "Doe"
            },
            "individual_localname": {
                "name_type": "LEGL",
                "name_first": "John",
                "name_middle": "Mark",
                "name_last": "Doe"
            },
            "date_of_birth": "1988-06-27",
            "place_of_birth": "Singapore, Singapore"
        },
        "address": {
            "address_type": "GEOG",
            "address_line": "Apt 123",
            "address_street_no": "456",
            "address_street_name": "Elm Street",
            "address_building_name": "Elmwood Apartments",
            "address_floor": "15",
            "address_room": "1503",
            "address_postbox": "PO Box 789",
            "address_city": "New York",
            "address_region": "New York",
            "address_district": "Manhattan",
            "address_postcode": "10001",
            "address_country_code": "US"
        },
        "created": "2025-04-14T13:18:31+00:00",
        "last_modified": "2025-04-14T13:18:31+00:00"
    }
}
```

{% endtab %}
{% endtabs %}