Subjects and identifiers

Creating subjects, registering verified identifiers, and withdrawing from the directory.

Requires a member credential.

`POST /subjects`

{ "subject_type": "natural_person", "external_ref": "cust_10482" }

{
  "id": "sub_9f2c41a8",
  "subject_type": "natural_person",
  "created_at": "2026-09-09T10:00:00Z"
}

subject_type is natural_person or legal_entity. It is not cosmetic: it drives the discoverability defaults below.

external_ref is your own key. The protocol never interprets it and never returns it to anyone else. No personal data belongs in a subject — names, dates of birth and documents stay in your systems.

`POST /identifiers`

{
  "subject_id": "sub_9f2c41a8",
  "identifier_type": "phone",
  "identifier": "+221771234567",
  "verification_method": "otp_sms",
  "discoverability": "network"
}

{
  "id": "idf_3b71c9",
  "identifier_type": "phone",
  "discoverability": "network",
  "verified_at": "2026-09-09T10:02:00Z"
}

The clear identifier is not stored

It is used to compute the hash and gone in the same request — not in a table, not in application logs, not in the search log. The operator keeps the hash.

Verification

verified_at is set only when verification_method is supplied. Register without one and the entry still indexes, but a counterparty reading an attestation can tell the difference — which is the only reason to record it.

Type	Reasonable methods
`phone`	`otp_sms`, `otp_voice`
`email`	`link_click`
`bank_account`	`micro_deposit`, `payee_name_check`
`lei`, `reg`, `tax`	`registry_lookup`, `document_review`

Format rules worth repeating

reg names its registry. reg:SN:RCCM:SN-DKR-2020-B-1234, not reg:SN:…. One country holds several registers — a Senegalese company has both a NINEA and an RCCM — and omitting the registry makes them indistinguishable, or collides two different companies where numeric formats overlap.

bank_account carries its scheme. iban:SN08SN01… or bban:…. Never inferred from a country.

Phone numbers are E.164. Normalisation is normative: two implementations that normalise differently split the directory in half with no error anywhere.

Discoverability defaults

Applied when you omit the field:

Type	Default	Why
`phone`	`network`	Small, dense, enumerable space
`email`	`network`	Breach-list replay, not enumeration
`bank_account`	`private`	Already printed on invoices
`lei`, `reg`, `tax`	`public`	The register is public by construction

Never move an entry towards public in a migration. Someone becoming publicly findable without asking is the one mistake here that cannot be walked back.

`POST /subjects/{id}/withdraw`

{ "subject_id": "sub_9f2c41a8", "withdrawn": true, "entries": 3 }

Sets every identifier and every address of the subject to private, and removes each entry from the directory index.

Applied at the subject level, always. Someone who opts out expects to disappear everywhere; a per-entry toggle that leaves them findable by email after they removed their phone number is a promise half kept, which is worse than none.

Withdrawal does not delete the subject, and does not erase settlement history. Ending discoverability and destroying the record of what happened are different operations with different legal consequences.

Subjects and identifiers

POST /subjects

POST /identifiers