> 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.

# Retrieve an entity

GET https://sandbox-api.toden.co/api/identity/entities/{externalUserId}

Returns the entity registered under your reference, its stored profile, the shared identity it is linked to, the verified document types contributed through it, and up to 25 of its verifications, newest first.

The result is scoped to the organisation and environment of the key. A deleted entity answers the same as one that never existed.

**Error codes**

| `error` | Status | Meaning |
|---|---|---|
| `entity_not_found` | 404 | No live entity has this reference in this organisation and environment. |
| `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/get-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

### Path parameters

- `externalUserId` (string, required) — Your own stable reference for the person or business, as sent when the entity was registered.

## Response

### 200

Success

- `entity` (Entity, required)
- `identity` (EntityIdentity, required, nullable) — The linked shared identity, or `null` when the entity is not linked to one.
- `identifiers` (list of EntityIdentifier, required) — The types of verified identity document linked to the identity in this environment, oldest first. Numbers are never returned here.
- `verifications` (list of EntityVerificationSummary, required) — Up to 25 verifications run for this reference, newest first.

## Errors

### 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.

### 404 Not Found Error

The resource does not exist for this organisation and environment.

- `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

### Entity

- `entityId` (string, required) — The Toden identifier of the entity.
- `externalUserId` (string, required) — Your own reference for the entity.
- `type` (enum, required) — Whether the entity is a person or a business.
  - Allowed values: `INDIVIDUAL`, `BUSINESS`
- `status` (enum, required) — The lifecycle status of the entity.
  - Allowed values: `ACTIVE`, `SUSPENDED`, `CLOSED`
- `disposition` (enum, required) — The current compliance decision on the entity.
  - Allowed values: `PENDING`, `UNDER_REVIEW`, `APPROVED`, `REJECTED`
- `kycProvenance` (enum, required) — How the entity was verified.
  - Allowed values: `MYAZA_VERIFIED`, `EXTERNAL_VERIFIED`, `UNVERIFIED`
- `riskTier` (enum, required) — The current risk band of the entity.
  - Allowed values: `LOW`, `MEDIUM`, `HIGH`, `UNSCORED`
- `createdAt` (datetime, required) — When the entity was created.
- `metadata` (map from string to any, optional, nullable) — Your metadata as stored, or `null`.
- `identityId` (string, optional, nullable) — The identifier of the shared identity the entity is linked to, or `null` when it has not been resolved to one.
- `kycSource` (string, optional, nullable) — The label of the external verification source, when one was recorded.
- `kycVerifiedAt` (datetime, optional, nullable) — When the entity was verified.
- `riskScore` (double, optional, nullable) — The latest risk score recorded for the entity.
- `profile` (EntityProfile, optional, nullable) — The stored profile, or `null` when none has been written.

### EntityIdentity

- `id` (string, required) — The identifier of the shared identity.
- `type` (enum, required) — Whether the identity is a person or a business.
  - Allowed values: `INDIVIDUAL`, `BUSINESS`
- `trustState` (enum, required) — The trust flag of the identity. `FLAGGED` means a confirmed risk finding is attached to it.
  - Allowed values: `UNVERIFIED`, `VERIFIED`, `FLAGGED`
- `riskTier` (enum, required) — The current risk band of the identity.
  - Allowed values: `LOW`, `MEDIUM`, `HIGH`, `UNSCORED`
- `riskScore` (double, required, nullable) — The latest risk score recorded for the identity.

### EntityIdentifier

- `idType` (string, required) — The type of a verified identity document the person carries, such as `bvn` or `nin`.
- `environment` (enum, required) — The environment the identifier was verified in.
  - Allowed values: `DEVELOPMENT`, `SANDBOX`, `PRODUCTION`
- `createdAt` (datetime, required) — When the identifier was first recorded.

### EntityVerificationSummary

- `id` (string, required) — The identifier of the verification.
- `idType` (string, required) — The identity document type the verification used.
- `country` (string, required) — The ISO 3166-1 alpha-2 country of the verification.
- `status` (string, required) — The result of the checks, such as `VERIFIED`, `FAILED`, `NOT_FOUND`, `ERROR` or `PENDING`.
- `createdAt` (datetime, required) — When the verification was submitted.
- `idNumber` (string, optional, nullable) — The identity number verified, or `null` when none was supplied or read.
- `reasonCode` (string, optional, nullable) — The stable reason code when the verification did not pass.
- `businessName` (string, optional, nullable) — The registered name, for a business verification.
- `deviceMetadata` (map from string to any, optional, nullable) — Device and submission context recorded with the verification.
- `workflowId` (string, optional, nullable) — The public identifier of the workflow that ran, when one did.
- `workflowVersion` (integer, optional, nullable) — The published version of that workflow.

### EntityProfile

The stored profile, or `null` when none has been written.

- `entityId` (string, optional) — The Toden identifier of the entity.
- `fullName` (string, optional, nullable) — The full name or registered business name held for the entity.
- `dateOfBirth` (string, optional, nullable) — The date of birth held for the entity.
- `nationality` (string, optional, nullable) — The nationality or country held for the entity.
- `idType` (string, optional, nullable) — The type of the most recent identity document held.
- `idNumber` (string, optional, nullable) — The most recent identity document number held.
- `idExpiresAt` (datetime, optional, nullable) — When the verified document expires.
- `address` (map from string to any, optional, nullable) — The strongest address held for the entity, as JSON. Its keys depend on where the address came from.
- `email` (string, optional, nullable) — The strongest email address held for the entity.
- `phone` (string, optional, nullable) — The strongest phone number held for the entity.
- `declaredMonthlyVolume` (string, optional, nullable) — The declared monthly volume, as a decimal string.
- `declaredVolumeCurrency` (string, optional, nullable) — The ISO 4217 currency of the declared volume.
- `declaredTxnTypes` (list of string, optional) — The transaction types the customer declared.
- `declaredInfo` (map from string to any, optional, nullable) — Answers the customer gave to a workflow questionnaire, keyed by question.
- `walletAddresses` (list of map from string to any, optional, nullable) — The attached wallet addresses, each with `address` and optional `chain`, `label` and `addedAt`.
- `selfieUrl` (string, optional, nullable) — A display photo uploaded for the entity from the dashboard.
- `createdAt` (datetime, optional) — When the profile was first written.
- `updatedAt` (datetime, optional) — When the profile last changed.

## Examples

**Response**

```json
{
  "entity": {
    "entityId": "ent_01j9x2k4m8",
    "externalUserId": "user_42",
    "type": "INDIVIDUAL",
    "status": "ACTIVE",
    "disposition": "APPROVED",
    "kycProvenance": "EXTERNAL_VERIFIED",
    "riskTier": "LOW",
    "createdAt": "2026-04-27T12:00:00.000Z",
    "metadata": {
      "accountId": "acc_7732"
    },
    "identityId": "myz_01j9x2k4m8",
    "kycSource": "previous-provider",
    "kycVerifiedAt": "2026-04-27T12:00:00.000Z",
    "riskScore": 12,
    "profile": {
      "entityId": "ent_01j9x2k4m8",
      "fullName": "Ada Example",
      "nationality": "NG",
      "idType": "bvn",
      "idNumber": "00000000001"
    }
  },
  "identity": {
    "id": "myz_01j9x2k4m8",
    "type": "INDIVIDUAL",
    "trustState": "VERIFIED",
    "riskTier": "LOW",
    "riskScore": 12
  },
  "identifiers": [
    {
      "idType": "bvn",
      "environment": "PRODUCTION",
      "createdAt": "2026-04-27T12:00:00.000Z"
    }
  ],
  "verifications": []
}
```

**SDK Code**

```python
import requests

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

headers = {"Authorization": "Bearer <apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://sandbox-api.toden.co/api/identity/entities/externalUserId';
const options = {method: 'GET', headers: {Authorization: 'Bearer <apiKey>'}};

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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <apiKey>")

	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/externalUserId")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <apiKey>'

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.get("https://sandbox-api.toden.co/api/identity/entities/externalUserId")
  .header("Authorization", "Bearer <apiKey>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://sandbox-api.toden.co/api/identity/entities/externalUserId', [
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://sandbox-api.toden.co/api/identity/entities/externalUserId");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <apiKey>"]

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

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()
```