> ## Documentation Index
> Fetch the complete documentation index at: https://clearlayer.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Investors

> Register an investor for compliance checks.

## Register an investor

<code>POST /v1/investors</code>

Creates a new investor record. The investor's KYC status, accreditation status, and country are used by the [decision engine](/api/decisions) when evaluating compliance against a policy.

<Warning>
  All requests to this endpoint require a valid API key in the `Authorization` header.
</Warning>

***

## Request body

<ParamField path="name" type="string" required>
  The investor's full legal name.
</ParamField>

<ParamField path="type" type="string" required>
  The investor type. Must be `"individual"` or `"entity"`.
</ParamField>

<ParamField path="country" type="string" required>
  The investor's country of residence or incorporation as a 2-letter ISO 3166-1 alpha-2 code (e.g. `"US"`, `"GB"`).
</ParamField>

<ParamField path="kyc_status" type="string" required>
  The result of the investor's KYC check. Must be `"verified"`, `"pending"`, or `"failed"`.
</ParamField>

<ParamField path="accredited_status" type="boolean" required>
  Whether the investor is accredited. Set to `true` if accreditation has been confirmed.
</ParamField>

<ParamField path="review_status" type="string">
  The manual review state of the investor record. Must be `"approved"`, `"pending"`, or `"rejected"`. Defaults to `"pending"`.
</ParamField>

***

## Response fields

<ResponseField name="id" type="string">
  Unique investor ID. Format: `inv_...`
</ResponseField>

<ResponseField name="name" type="string">
  The investor's full name.
</ResponseField>

<ResponseField name="type" type="string">
  `"individual"` or `"entity"`.
</ResponseField>

<ResponseField name="country" type="string">
  2-letter ISO country code.
</ResponseField>

<ResponseField name="kyc_status" type="string">
  `"verified"`, `"pending"`, or `"failed"`.
</ResponseField>

<ResponseField name="accredited_status" type="boolean">
  Whether the investor is accredited.
</ResponseField>

<ResponseField name="review_status" type="string">
  `"approved"`, `"pending"`, or `"rejected"`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the investor was created.
</ResponseField>

***

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://clearlayer-api-production.up.railway.app/v1/investors \
    -H "Authorization: Bearer cl_test_key_1234567890" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Alice Johnson",
      "type": "individual",
      "country": "US",
      "kyc_status": "verified",
      "accredited_status": true
    }'
  ```
</CodeGroup>

### 201 — Created

```json theme={null}
{
  "id": "inv_a1b2c3d4e5f6",
  "name": "Alice Johnson",
  "type": "individual",
  "country": "US",
  "kyc_status": "verified",
  "accredited_status": true,
  "review_status": "pending",
  "created_at": "2024-01-15T10:30:00.000Z"
}
```