Identities

Every entity on the platform — individual, organization, application — is an Identity. KYC, KYB, and sanctions screening live here. Tier 1/2/3 unlocks more dollars per month.

The Identity object

{
  "id":           "usr_01HZ...",
  "type":         "individual",
  "email":        "ada@example.com",
  "display_name": "Ada Lovelace",
  "kyc_tier":     2,
  "status":       "active",
  "created_at":   "2026-05-15T13:45:09Z"
}

Identity types

individual — a human.
organization — a 501(c)(3), fiscal sponsor, or business.
application — a programmatic actor (used by partner platforms).

POST /v1/identities

Create an identity. Tier 0 by default; submit a verification to upgrade.

Field	Type		Description
type	string	required	individual \| organization \| application
email	string	required	Unique per identity.
display_name	string	optional	Public-facing name.
legal_name	string	optional	Legal name for organizations / KYC.
ein	string	optional	EIN for organizations.
metadata	object	optional	Arbitrary key-value pairs.

GET /v1/identities/{id}

Retrieve an identity. Use ?expand=verification to inline the latest KYC record.

POST /v1/identities/{id}/verifications

Start a KYC/KYB verification. Returns a hosted URL where the identity can submit documents.

Field	Type		Description
tier_attempted	integer	required	Tier 1, 2, or 3.
redirect_url	string	optional	Where to send the user after submission.

Example response

{
  "id":             "kyc_01HZ...",
  "identity_id":    "usr_01HZ...",
  "tier_attempted": 2,
  "status":         "pending",
  "hosted_url":     "https://2026.bequest.org/v/kyc_01HZ..."
}

Returns: A verification record with a hosted URL.

GET /v1/identities/{id}/verifications

List the verifications for an identity.

Tier limits

Tier	Documents	Monthly limit
0	Email-verified only.	$1,000 incoming / $250 outgoing
1	Government ID.	$10,000 incoming / $2,500 outgoing
2	Government ID + selfie + address.	$100,000 / $25,000
3	Full KYC dossier; organizations require KYB.	Unlimited (subject to sanctions screening).

Events

identity.kyc_started
identity.kyc_passed
identity.kyc_failed
identity.suspended