Base Path
X-API-Key header. See Authentication.
Customer records need the
customers service. Everything under /identity, /verification-profiles and the ID link flows needs identity.
Which register you write to
An instance writes to the Trusset ID Register by default, or to your own register when the instance is bound to one. Every identity call resolves that automatically, so the same request works either way and no endpoint takes a registry address. What changes with your own register is who holds the roles. A write your instance’s wallet has no role for is refused before any calldata is handed out, rather than reverting after you paid for it.Writes return calldata
Every identity write follows the same two-call shape as the rest of the platform. Call it once withouttxHash to get the unsigned transaction, broadcast it from your own wallet, then call it again with txHash to have the receipt verified and the result recorded.
Nothing is submitted on your behalf.
Claims
The registry holds eight claim slots per identity. Four of them mean something fixed and four are yours to assign.
The four canonical slots are reserved. Add Claim refuses them with
PROOF_REQUIRED, because a residency attestation that anyone could write by hand would not be worth reading. They are filled by Add Claims from Proof and nothing else.
The four assignable slots take a hash you supply. What they mean is your convention, and a proof for a field with no canonical meaning can be filed in one of them.
KYC proofs
Claims backed by proofs come from the Trusset KYC zk-Proof Tool, which runs entirely on your own machines. It takes your KYC records and produces three things per subject: a Merkle root to publish on chain, one zk-STARK per proved field, and a manifest signed with your operator key. The manifest says what was asserted, under which rule, on what evidence, and for how long. Trusset never sees the underlying data. What reaches this API is the manifest, the signature, and the proof bytes. The date of birth, the nationality and the documents stay with you.1
Register your operator key
Set Operator Key records the ed25519 public key the tool prints. Every manifest signature is checked against it.
2
Verify the identity
Verify Identity puts the subject on the registry with their
kycHash, which is the bundle’s Merkle root.3
Read the bundle
Inspect Manifest reports what the bundle contains and which leaves can be attested, without writing anything.
4
File the claims
Add Claims from Proof verifies the bundle and returns the calldata for each claim it backs.
A leaf can be a hiding commitment with no zk proof behind it, which the tool uses for fields like a surname where there is no predicate worth proving. Those leaves are marked
commitmentOnly and are not attestable while proof verification is enforced.Response envelope
success is false, data is null, and error carries code and message. Always branch on success rather than on the HTTP status alone.