Retrieve an entity

GET

/api/identity/entities/:externalUserId

GET

/api/identity/entities/:externalUserId

curl https://sandbox-api.toden.co/api/identity/entities/externalUserId \
     -H "Authorization: Bearer <apiKey>"

{
  "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": []
}

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.

Authentication

AuthorizationBearer

Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Path parameters

externalUserIdstringRequired

Your own stable reference for the person or business, as sent when the entity was registered.

Response

Success

entityobject

identityobject or null

The linked shared identity, or null when the entity is not linked to one.

identifierslist of objects

The types of verified identity document linked to the identity in this environment, oldest first. Numbers are never returned here.

verificationslist of objects

Up to 25 verifications run for this reference, newest first.

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

503

Service Unavailable Error