> Toden documentation. For the full index fetch /llms.txt. Every page is available as Markdown by appending .md to its URL. Identity verification uses /api/kyc, Risk Intelligence uses /api/v1; they are separate contracts with different error shapes. Never invent an endpoint, field or enum value: read the API reference page for the operation first.

# Register or update an entity

POST https://sandbox-api.toden.co/api/identity/entities
Content-Type: application/json

Creates the entity for `externalUserId`, or updates it when one already exists in this organisation and environment. The call is an idempotent upsert on `externalUserId`: repeating it never creates a second entity. Registering a reference you previously deleted brings that entity back (`restored: true`).

`type`, `kycProvenance` and `kycSource` are written from every request, so send them again on an update (an omitted `kycProvenance` is stored as `UNVERIFIED`). Profile fields and `metadata` you omit keep their stored values.

When the entity is declared verified (`MYAZA_VERIFIED` or `EXTERNAL_VERIFIED`) and `profile.idType` and `profile.idNumber` are both present, the entity is linked to a shared identity by exact match on that document. No name or date-of-birth matching is done, and an unverified entity is never linked.

Side effects: the `entity.imported` webhook fires when the entity is created, and `identity.resolved` fires when its identity link changes. The entity is enrolled in ongoing screening where screening runs for your organisation; screening is billed per screen run in production and is free in sandbox. The call is recorded in your audit log.

**Error codes**

| `error` | Status | Meaning |
|---|---|---|
| `invalid_request` | 400 | The body failed validation. `details` carries the field-level breakdown. |
| `secret_key_required` | 403 | A publishable key was used. This API accepts secret keys only. |
| `environment_mismatch` | 403 | The key belongs to an environment this host does not serve. |
| `rate_limited` | 429 | The request rate limit for this key was reached. Retry after a short wait. |
| `rate_limit_store_unavailable` | 503 | Rate limiting is temporarily unavailable. Retry shortly. |

A missing or unknown key returns `401` with a plain sentence in `error` rather than a code.

Requires a secret (`sk_`) key. A publishable key receives `403 secret_key_required`.

Reference: https://docs.toden.co/api-reference/verification/entities/upsert-entity

## Authentication

- `Authorization` header (bearer token, required) — Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

## Servers

- `https://sandbox-api.toden.co` (Sandbox, default)
- `https://api.toden.co` (Production)

## Request

### Body (application/json)

This endpoint expects an EntityUpsertRequest.

- `externalUserId` (string, required) — Your own stable reference for the person or business. It is the key of the entity within your organisation and environment.
- `metadata` (map from string to any, optional) — Your own correlation fields for the entity, returned on reads and carried on webhooks about it. Sending it again replaces the stored object. At most 16 KiB of JSON, four levels deep, 100 keys in total, 50 keys per object, 20 items per array, keys up to 64 characters and strings up to 1,000 characters.
- `type` (enum, optional) — Whether the entity is a person or a business. Written on every call, so an omitted value is stored as `INDIVIDUAL`.
  - Allowed values: `INDIVIDUAL`, `BUSINESS`
- `kycProvenance` (enum, optional) — How the entity was verified. `EXTERNAL_VERIFIED` records a verification done outside Toden, which is trusted as declared. Written on every call, so an omitted value is stored as `UNVERIFIED`.
  - Allowed values: `MYAZA_VERIFIED`, `EXTERNAL_VERIFIED`, `UNVERIFIED`
- `kycSource` (string, optional) — A label for where the external verification came from, such as the name of your previous provider. Omitting it clears the stored value.
- `profile` (EntityProfileInput, optional) — Attributes you hold about the entity. Every field is optional, and a field you omit keeps its stored value.

## Response

### 200

The existing entity was updated.

- `entityId` (string, required) — The Toden identifier of the entity.
- `identityId` (string, required, nullable) — The identifier of the shared identity the entity is linked to, or `null` when it has not been resolved to one.
- `externalUserId` (string, required) — Your reference, echoed back.
- `metadata` (map from string to any, required, nullable) — Your metadata exactly as stored, or `null` when none is held.
- `kycProvenance` (enum, required) — The provenance sent in this request, or `UNVERIFIED` when none was sent.
  - Allowed values: `MYAZA_VERIFIED`, `EXTERNAL_VERIFIED`, `UNVERIFIED`
- `created` (boolean, required) — True when this call created the entity, false when it updated an existing one.
- `restored` (boolean, required) — True when the reference had been deleted and this call brought the entity back.
- `screening` (EntityUpsertResponseScreening, required) — The screening enrolment, or the string `INACTIVE` when screening does not run for your organisation.

### 201

The entity was created.

- `entityId` (string, required) — The Toden identifier of the entity.
- `identityId` (string, required, nullable) — The identifier of the shared identity the entity is linked to, or `null` when it has not been resolved to one.
- `externalUserId` (string, required) — Your reference, echoed back.
- `metadata` (map from string to any, required, nullable) — Your metadata exactly as stored, or `null` when none is held.
- `kycProvenance` (enum, required) — The provenance sent in this request, or `UNVERIFIED` when none was sent.
  - Allowed values: `MYAZA_VERIFIED`, `EXTERNAL_VERIFIED`, `UNVERIFIED`
- `created` (boolean, required) — True when this call created the entity, false when it updated an existing one.
- `restored` (boolean, required) — True when the reference had been deleted and this call brought the entity back.
- `screening` (EntityUpsertResponseScreening, required) — The screening enrolment, or the string `INACTIVE` when screening does not run for your organisation.

## Errors

### 400 Bad Request Error

The request body, query or path was invalid.

- `error` (string, required) — A stable machine-readable code such as `invalid_input`. Authentication failures (401) carry a short sentence here instead of a code.
- `message` (string, optional) — A human-readable explanation, safe to log. The wording may change.

### 401 Unauthorized Error

The Authorization header is missing, or the API key is unknown or revoked.

- `error` (string, required) — A stable machine-readable code such as `invalid_input`. Authentication failures (401) carry a short sentence here instead of a code.
- `message` (string, optional) — A human-readable explanation, safe to log. The wording may change.

### 403 Forbidden Error

The key may not call this endpoint, or the organisation may not use this feature.

- `error` (string, required) — A stable machine-readable code such as `invalid_input`. Authentication failures (401) carry a short sentence here instead of a code.
- `message` (string, optional) — A human-readable explanation, safe to log. The wording may change.

### 429 Too Many Requests Error

A rate limit was reached. Retry after a short wait.

- `error` (string, required) — A stable machine-readable code such as `invalid_input`. Authentication failures (401) carry a short sentence here instead of a code.
- `message` (string, optional) — A human-readable explanation, safe to log. The wording may change.

### 503 Service Unavailable Error

The service is temporarily unavailable.

- `error` (string, required) — A stable machine-readable code such as `invalid_input`. Authentication failures (401) carry a short sentence here instead of a code.
- `message` (string, optional) — A human-readable explanation, safe to log. The wording may change.

## Types

### EntityProfileInput

Attributes you hold about the entity. Every field is optional, and a field you omit keeps its stored value.

- `fullName` (string, optional) — The full name of the person, or the registered name of the business.
- `dateOfBirth` (string, optional) — The date of birth, as a string such as `1990-01-01`.
- `nationality` (string, optional) — The nationality or country, ideally as an ISO 3166-1 alpha-2 code.
- `idType` (string, optional) — The type of identity document the number belongs to, such as `bvn` or `passport`.
- `idNumber` (string, optional) — The identity document number. Together with `idType` it drives identity resolution on a verified entity.
- `address` (map from string to any, optional) — The address you hold, as free-form JSON. It is recorded as declared address evidence for the entity.
- `email` (string, optional) — An email address you hold for the entity. Recorded as declared contact evidence.
- `phone` (string, optional) — A phone number you hold for the entity. Recorded as declared contact evidence.
- `declaredMonthlyVolume` (double, optional) — The monthly transaction volume the customer declared.
- `declaredVolumeCurrency` (string, optional) — The ISO 4217 currency code the declared volume is stated in. Lower case input is upper-cased.
- `declaredTxnTypes` (list of string, optional) — The kinds of transaction the customer declared they expect to make.
- `walletAddresses` (list of EntityProfileInputWalletAddressesItems, optional) — Crypto wallet addresses attached to the entity. Omit the key to leave the stored set unchanged; send an array (including an empty one) to replace it. Wallets are risk attributes for wallet screening, never identity keys.

### EntityUpsertResponseScreening

The screening enrolment, or the string `INACTIVE` when screening does not run for your organisation.

### EntityProfileInputWalletAddressesItems

- `address` (string, required) — The wallet address.
- `chain` (string, optional) — The network the address belongs to, in your own naming.
- `label` (string, optional) — Your own label for the wallet.

### EntityScreeningEnrolment

- `status` (enum, required) — Always `ENQUEUED`: the entity is enrolled and its screens are queued to run.
  - Allowed values: `ENQUEUED`
- `types` (list of enum, required) — Every screening type the entity is enrolled in after this call. `PEP` is skipped for businesses and `WALLET` applies only when a wallet address is attached.
  - Allowed values: `SANCTIONS`, `PEP`, `ADVERSE_MEDIA`, `WALLET`

## Examples

### Example 1

**Request**

```json
{
  "externalUserId": "user_42",
  "metadata": {
    "accountId": "acc_7732"
  },
  "type": "INDIVIDUAL",
  "kycProvenance": "EXTERNAL_VERIFIED",
  "kycSource": "previous-provider",
  "profile": {
    "fullName": "Ada Example",
    "dateOfBirth": "1990-01-01",
    "nationality": "NG",
    "idType": "bvn",
    "idNumber": "00000000001",
    "address": {
      "addressLine": "1 Example Street, Lagos"
    },
    "declaredMonthlyVolume": 500000,
    "declaredVolumeCurrency": "NGN",
    "declaredTxnTypes": [
      "transfer",
      "deposit"
    ]
  }
}
```

**Response**

```json
{
  "entityId": "ent_01j9x2k4m8",
  "identityId": "myz_01j9x2k4m8",
  "externalUserId": "user_42",
  "metadata": {
    "accountId": "acc_7732"
  },
  "kycProvenance": "EXTERNAL_VERIFIED",
  "created": true,
  "restored": false,
  "screening": {
    "status": "ENQUEUED",
    "types": [
      "SANCTIONS",
      "PEP",
      "ADVERSE_MEDIA"
    ]
  }
}
```

**SDK Code**

```python
import requests

url = "https://sandbox-api.toden.co/api/identity/entities"

payload = {
    "externalUserId": "user_42",
    "metadata": { "accountId": "acc_7732" },
    "type": "INDIVIDUAL",
    "kycProvenance": "EXTERNAL_VERIFIED",
    "kycSource": "previous-provider",
    "profile": {
        "fullName": "Ada Example",
        "dateOfBirth": "1990-01-01",
        "nationality": "NG",
        "idType": "bvn",
        "idNumber": "00000000001",
        "address": { "addressLine": "1 Example Street, Lagos" },
        "declaredMonthlyVolume": 500000,
        "declaredVolumeCurrency": "NGN",
        "declaredTxnTypes": ["transfer", "deposit"]
    }
}
headers = {
    "Authorization": "Bearer <apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://sandbox-api.toden.co/api/identity/entities';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <apiKey>', 'Content-Type': 'application/json'},
  body: '{"externalUserId":"user_42","metadata":{"accountId":"acc_7732"},"type":"INDIVIDUAL","kycProvenance":"EXTERNAL_VERIFIED","kycSource":"previous-provider","profile":{"fullName":"Ada Example","dateOfBirth":"1990-01-01","nationality":"NG","idType":"bvn","idNumber":"00000000001","address":{"addressLine":"1 Example Street, Lagos"},"declaredMonthlyVolume":500000,"declaredVolumeCurrency":"NGN","declaredTxnTypes":["transfer","deposit"]}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.toden.co/api/identity/entities"

	payload := strings.NewReader("{\n  \"externalUserId\": \"user_42\",\n  \"metadata\": {\n    \"accountId\": \"acc_7732\"\n  },\n  \"type\": \"INDIVIDUAL\",\n  \"kycProvenance\": \"EXTERNAL_VERIFIED\",\n  \"kycSource\": \"previous-provider\",\n  \"profile\": {\n    \"fullName\": \"Ada Example\",\n    \"dateOfBirth\": \"1990-01-01\",\n    \"nationality\": \"NG\",\n    \"idType\": \"bvn\",\n    \"idNumber\": \"00000000001\",\n    \"address\": {\n      \"addressLine\": \"1 Example Street, Lagos\"\n    },\n    \"declaredMonthlyVolume\": 500000,\n    \"declaredVolumeCurrency\": \"NGN\",\n    \"declaredTxnTypes\": [\n      \"transfer\",\n      \"deposit\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://sandbox-api.toden.co/api/identity/entities")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalUserId\": \"user_42\",\n  \"metadata\": {\n    \"accountId\": \"acc_7732\"\n  },\n  \"type\": \"INDIVIDUAL\",\n  \"kycProvenance\": \"EXTERNAL_VERIFIED\",\n  \"kycSource\": \"previous-provider\",\n  \"profile\": {\n    \"fullName\": \"Ada Example\",\n    \"dateOfBirth\": \"1990-01-01\",\n    \"nationality\": \"NG\",\n    \"idType\": \"bvn\",\n    \"idNumber\": \"00000000001\",\n    \"address\": {\n      \"addressLine\": \"1 Example Street, Lagos\"\n    },\n    \"declaredMonthlyVolume\": 500000,\n    \"declaredVolumeCurrency\": \"NGN\",\n    \"declaredTxnTypes\": [\n      \"transfer\",\n      \"deposit\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://sandbox-api.toden.co/api/identity/entities")
  .header("Authorization", "Bearer <apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalUserId\": \"user_42\",\n  \"metadata\": {\n    \"accountId\": \"acc_7732\"\n  },\n  \"type\": \"INDIVIDUAL\",\n  \"kycProvenance\": \"EXTERNAL_VERIFIED\",\n  \"kycSource\": \"previous-provider\",\n  \"profile\": {\n    \"fullName\": \"Ada Example\",\n    \"dateOfBirth\": \"1990-01-01\",\n    \"nationality\": \"NG\",\n    \"idType\": \"bvn\",\n    \"idNumber\": \"00000000001\",\n    \"address\": {\n      \"addressLine\": \"1 Example Street, Lagos\"\n    },\n    \"declaredMonthlyVolume\": 500000,\n    \"declaredVolumeCurrency\": \"NGN\",\n    \"declaredTxnTypes\": [\n      \"transfer\",\n      \"deposit\"\n    ]\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://sandbox-api.toden.co/api/identity/entities', [
  'body' => '{
  "externalUserId": "user_42",
  "metadata": {
    "accountId": "acc_7732"
  },
  "type": "INDIVIDUAL",
  "kycProvenance": "EXTERNAL_VERIFIED",
  "kycSource": "previous-provider",
  "profile": {
    "fullName": "Ada Example",
    "dateOfBirth": "1990-01-01",
    "nationality": "NG",
    "idType": "bvn",
    "idNumber": "00000000001",
    "address": {
      "addressLine": "1 Example Street, Lagos"
    },
    "declaredMonthlyVolume": 500000,
    "declaredVolumeCurrency": "NGN",
    "declaredTxnTypes": [
      "transfer",
      "deposit"
    ]
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://sandbox-api.toden.co/api/identity/entities");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"externalUserId\": \"user_42\",\n  \"metadata\": {\n    \"accountId\": \"acc_7732\"\n  },\n  \"type\": \"INDIVIDUAL\",\n  \"kycProvenance\": \"EXTERNAL_VERIFIED\",\n  \"kycSource\": \"previous-provider\",\n  \"profile\": {\n    \"fullName\": \"Ada Example\",\n    \"dateOfBirth\": \"1990-01-01\",\n    \"nationality\": \"NG\",\n    \"idType\": \"bvn\",\n    \"idNumber\": \"00000000001\",\n    \"address\": {\n      \"addressLine\": \"1 Example Street, Lagos\"\n    },\n    \"declaredMonthlyVolume\": 500000,\n    \"declaredVolumeCurrency\": \"NGN\",\n    \"declaredTxnTypes\": [\n      \"transfer\",\n      \"deposit\"\n    ]\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "externalUserId": "user_42",
  "metadata": ["accountId": "acc_7732"],
  "type": "INDIVIDUAL",
  "kycProvenance": "EXTERNAL_VERIFIED",
  "kycSource": "previous-provider",
  "profile": [
    "fullName": "Ada Example",
    "dateOfBirth": "1990-01-01",
    "nationality": "NG",
    "idType": "bvn",
    "idNumber": "00000000001",
    "address": ["addressLine": "1 Example Street, Lagos"],
    "declaredMonthlyVolume": 500000,
    "declaredVolumeCurrency": "NGN",
    "declaredTxnTypes": ["transfer", "deposit"]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox-api.toden.co/api/identity/entities")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Example 2

**Request**

```json
{
  "externalUserId": "user_42",
  "metadata": {
    "accountId": "acc_7732"
  },
  "type": "INDIVIDUAL",
  "kycProvenance": "EXTERNAL_VERIFIED",
  "kycSource": "previous-provider",
  "profile": {
    "fullName": "Ada Example",
    "dateOfBirth": "1990-01-01",
    "nationality": "NG",
    "idType": "bvn",
    "idNumber": "00000000001",
    "address": {
      "addressLine": "1 Example Street, Lagos"
    },
    "declaredMonthlyVolume": 500000,
    "declaredVolumeCurrency": "NGN",
    "declaredTxnTypes": [
      "transfer",
      "deposit"
    ]
  }
}
```

**Response**

```json
{
  "entityId": "ent_01j9x2k4m8",
  "identityId": "myz_01j9x2k4m8",
  "externalUserId": "user_42",
  "metadata": {
    "accountId": "acc_7732"
  },
  "kycProvenance": "EXTERNAL_VERIFIED",
  "created": true,
  "restored": false,
  "screening": {
    "status": "ENQUEUED",
    "types": [
      "SANCTIONS",
      "PEP",
      "ADVERSE_MEDIA"
    ]
  }
}
```

**SDK Code**

```python
import requests

url = "https://sandbox-api.toden.co/api/identity/entities"

payload = {
    "externalUserId": "user_42",
    "metadata": { "accountId": "acc_7732" },
    "type": "INDIVIDUAL",
    "kycProvenance": "EXTERNAL_VERIFIED",
    "kycSource": "previous-provider",
    "profile": {
        "fullName": "Ada Example",
        "dateOfBirth": "1990-01-01",
        "nationality": "NG",
        "idType": "bvn",
        "idNumber": "00000000001",
        "address": { "addressLine": "1 Example Street, Lagos" },
        "declaredMonthlyVolume": 500000,
        "declaredVolumeCurrency": "NGN",
        "declaredTxnTypes": ["transfer", "deposit"]
    }
}
headers = {
    "Authorization": "Bearer <apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://sandbox-api.toden.co/api/identity/entities';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <apiKey>', 'Content-Type': 'application/json'},
  body: '{"externalUserId":"user_42","metadata":{"accountId":"acc_7732"},"type":"INDIVIDUAL","kycProvenance":"EXTERNAL_VERIFIED","kycSource":"previous-provider","profile":{"fullName":"Ada Example","dateOfBirth":"1990-01-01","nationality":"NG","idType":"bvn","idNumber":"00000000001","address":{"addressLine":"1 Example Street, Lagos"},"declaredMonthlyVolume":500000,"declaredVolumeCurrency":"NGN","declaredTxnTypes":["transfer","deposit"]}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.toden.co/api/identity/entities"

	payload := strings.NewReader("{\n  \"externalUserId\": \"user_42\",\n  \"metadata\": {\n    \"accountId\": \"acc_7732\"\n  },\n  \"type\": \"INDIVIDUAL\",\n  \"kycProvenance\": \"EXTERNAL_VERIFIED\",\n  \"kycSource\": \"previous-provider\",\n  \"profile\": {\n    \"fullName\": \"Ada Example\",\n    \"dateOfBirth\": \"1990-01-01\",\n    \"nationality\": \"NG\",\n    \"idType\": \"bvn\",\n    \"idNumber\": \"00000000001\",\n    \"address\": {\n      \"addressLine\": \"1 Example Street, Lagos\"\n    },\n    \"declaredMonthlyVolume\": 500000,\n    \"declaredVolumeCurrency\": \"NGN\",\n    \"declaredTxnTypes\": [\n      \"transfer\",\n      \"deposit\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://sandbox-api.toden.co/api/identity/entities")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalUserId\": \"user_42\",\n  \"metadata\": {\n    \"accountId\": \"acc_7732\"\n  },\n  \"type\": \"INDIVIDUAL\",\n  \"kycProvenance\": \"EXTERNAL_VERIFIED\",\n  \"kycSource\": \"previous-provider\",\n  \"profile\": {\n    \"fullName\": \"Ada Example\",\n    \"dateOfBirth\": \"1990-01-01\",\n    \"nationality\": \"NG\",\n    \"idType\": \"bvn\",\n    \"idNumber\": \"00000000001\",\n    \"address\": {\n      \"addressLine\": \"1 Example Street, Lagos\"\n    },\n    \"declaredMonthlyVolume\": 500000,\n    \"declaredVolumeCurrency\": \"NGN\",\n    \"declaredTxnTypes\": [\n      \"transfer\",\n      \"deposit\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://sandbox-api.toden.co/api/identity/entities")
  .header("Authorization", "Bearer <apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalUserId\": \"user_42\",\n  \"metadata\": {\n    \"accountId\": \"acc_7732\"\n  },\n  \"type\": \"INDIVIDUAL\",\n  \"kycProvenance\": \"EXTERNAL_VERIFIED\",\n  \"kycSource\": \"previous-provider\",\n  \"profile\": {\n    \"fullName\": \"Ada Example\",\n    \"dateOfBirth\": \"1990-01-01\",\n    \"nationality\": \"NG\",\n    \"idType\": \"bvn\",\n    \"idNumber\": \"00000000001\",\n    \"address\": {\n      \"addressLine\": \"1 Example Street, Lagos\"\n    },\n    \"declaredMonthlyVolume\": 500000,\n    \"declaredVolumeCurrency\": \"NGN\",\n    \"declaredTxnTypes\": [\n      \"transfer\",\n      \"deposit\"\n    ]\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://sandbox-api.toden.co/api/identity/entities', [
  'body' => '{
  "externalUserId": "user_42",
  "metadata": {
    "accountId": "acc_7732"
  },
  "type": "INDIVIDUAL",
  "kycProvenance": "EXTERNAL_VERIFIED",
  "kycSource": "previous-provider",
  "profile": {
    "fullName": "Ada Example",
    "dateOfBirth": "1990-01-01",
    "nationality": "NG",
    "idType": "bvn",
    "idNumber": "00000000001",
    "address": {
      "addressLine": "1 Example Street, Lagos"
    },
    "declaredMonthlyVolume": 500000,
    "declaredVolumeCurrency": "NGN",
    "declaredTxnTypes": [
      "transfer",
      "deposit"
    ]
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://sandbox-api.toden.co/api/identity/entities");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"externalUserId\": \"user_42\",\n  \"metadata\": {\n    \"accountId\": \"acc_7732\"\n  },\n  \"type\": \"INDIVIDUAL\",\n  \"kycProvenance\": \"EXTERNAL_VERIFIED\",\n  \"kycSource\": \"previous-provider\",\n  \"profile\": {\n    \"fullName\": \"Ada Example\",\n    \"dateOfBirth\": \"1990-01-01\",\n    \"nationality\": \"NG\",\n    \"idType\": \"bvn\",\n    \"idNumber\": \"00000000001\",\n    \"address\": {\n      \"addressLine\": \"1 Example Street, Lagos\"\n    },\n    \"declaredMonthlyVolume\": 500000,\n    \"declaredVolumeCurrency\": \"NGN\",\n    \"declaredTxnTypes\": [\n      \"transfer\",\n      \"deposit\"\n    ]\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "externalUserId": "user_42",
  "metadata": ["accountId": "acc_7732"],
  "type": "INDIVIDUAL",
  "kycProvenance": "EXTERNAL_VERIFIED",
  "kycSource": "previous-provider",
  "profile": [
    "fullName": "Ada Example",
    "dateOfBirth": "1990-01-01",
    "nationality": "NG",
    "idType": "bvn",
    "idNumber": "00000000001",
    "address": ["addressLine": "1 Example Street, Lagos"],
    "declaredMonthlyVolume": 500000,
    "declaredVolumeCurrency": "NGN",
    "declaredTxnTypes": ["transfer", "deposit"]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox-api.toden.co/api/identity/entities")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```