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


---

# 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://docs.ospree.io/ospree-api/accounts-directory/create-account.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.