Register or update an entity

POST

/api/identity/entities

POST

/api/identity/entities

curl -X POST https://sandbox-api.toden.co/api/identity/entities \
     -H "Authorization: Bearer <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "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"
    ]
  }
}'

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

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.

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.

Request

This endpoint expects an object.

externalUserIdstringRequired>=1 character

Your own stable reference for the person or business. It is the key of the entity within your organisation and environment.

metadatamap from strings to anyOptional

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.

typeenumOptional

Whether the entity is a person or a business. Written on every call, so an omitted value is stored as INDIVIDUAL.

Allowed values:

kycProvenanceenumOptional

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:

kycSourcestringOptional

A label for where the external verification came from, such as the name of your previous provider. Omitting it clears the stored value.

profileobjectOptional

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

Response

The existing entity was updated.

entityIdstring

The Toden identifier of the entity.

identityIdstring or null

The identifier of the shared identity the entity is linked to, or null when it has not been resolved to one.

externalUserIdstring

Your reference, echoed back.

metadatamap from strings to any or null

Your metadata exactly as stored, or null when none is held.

kycProvenanceenum

The provenance sent in this request, or UNVERIFIED when none was sent.

Allowed values:

createdboolean

True when this call created the entity, false when it updated an existing one.

restoredboolean

True when the reference had been deleted and this call brought the entity back.

screeningobject or enum

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

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

503

Service Unavailable Error