Onboarding
Build Transactions
The unsigned transactions an onboarding waits for your wallet to sign
POST
/
customers
/
api
/
onboarding
/
{customer}
/
transactions
curl -X POST "https://api.trusset.org/customers/api/onboarding/client-48213/transactions" \
-H "Content-Type: application/json" \
-H "X-API-Key: trusset_your_key_here" \
-d '{ "signerAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72" }'
const response = await fetch(
'https://api.trusset.org/customers/api/onboarding/client-48213/transactions',
{
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-API-Key': 'trusset_your_key_here' },
body: JSON.stringify({ signerAddress: await signer.getAddress() })
}
);
const { data } = await response.json();
for (const step of data.plan.steps) {
const sent = await signer.sendTransaction({ to: step.transaction.to, data: step.transaction.data });
await sent.wait();
}
{
"success": true,
"data": {
"kind": "IDENTITY_REGISTRATION",
"pendingId": "cmwgx2gur0014iinmh8m2eb6c",
"plan": {
"action": "SIGN_TRANSACTIONS",
"registerKind": "TRUSSET",
"steps": [
{
"action": "SIGN_TRANSACTION",
"chainId": 11155111,
"transaction": { "to": "0xEf244c4Bd4d71Bd9A30EDF6Edef7CCC72642291a", "data": "0x9f4cc990000000000000000000000000..." },
"functionName": "batchVerifyIdentities",
"description": "Register 1 verified identity on-chain",
"stepType": "verify",
"ids": ["cmwgx2gur0014iinmh8m2eb6c"]
},
{
"action": "SIGN_TRANSACTION",
"chainId": 11155111,
"transaction": { "to": "0xEf244c4Bd4d71Bd9A30EDF6Edef7CCC72642291a", "data": "0x07363788000000000000000000000000..." },
"functionName": "addClaim",
"description": "Add residency claim for 0xe228fefc0f7ffe27e27c8e6463c44f1bce72151f",
"stepType": "residencyClaim",
"id": "cmwgx2gur0014iinmh8m2eb6c"
}
],
"total": 1,
"ids": ["cmwgx2gur0014iinmh8m2eb6c"],
"operations": { "cmwgx2gur0014iinmh8m2eb6c": "verify" }
},
"confirmWith": {
"method": "POST",
"endpoint": "/customers/api/onboarding/cmwgx2e5l000giinmq96qvnzr/transactions/confirm",
"kind": "IDENTITY_REGISTRATION",
"fields": ["txHash", "updateTxResults", "claimTxResults"]
},
"onboarding": { "customerId": "cmwgx2e5l000giinmq96qvnzr", "status": "AWAITING_SIGNATURE" }
},
"error": null,
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-11-14T21:27:27.000Z"
}
}
Returns the transactions your wallet has to sign while the onboarding reads
On an ERC-3643 register a registration is built in phases, as Verify Identity sets out. Send the claim signatures of the previous phase back as
The example shortens
The builders behind each kind refuse with their own codes as well. Build Pending Registration, Build Admission and Approve KYC Record list them.
AWAITING_SIGNATURE. Nothing is submitted for you: a wallet of your instance signs and broadcasts them, and Confirm Transactions records the result. The call can be repeated and builds the same step again until it is confirmed.
kind says what is signed, and matches nextAction.kind of the onboarding:
| Kind | Built here | Signed by |
|---|---|---|
IDENTITY_REGISTRATION | plan, as Build Pending Registration returns it for this one customer | A wallet holding KYC_PROVIDER_ROLE on a Trusset register, or an agent of an ERC-3643 registry |
ELIGIBILITY_ADMISSION | plan, as Build Admission returns it for this wallet | An agent of the profile’s eligibility register. signerAddress is required |
WHITELIST_ADMISSION | admissions, one setListed plan for each whitelist that does not list the wallet yet | An owner or manager of the whitelist |
claimSignatures, and confirm a deployed ONCHAINID with Confirm ONCHAINID.
Path Parameters
The customer
id, your externalId, the reference key or a wallet address of the customer.Body Parameters
For an ERC-3643 registration:
{ walletAddress, signature, claimType } for each claim message the previous phase asked you to sign. At most 400 entries.Response Fields
Show child attributes
Show child attributes
With
IDENTITY_REGISTRATION: the row in the pending queue. Use it as id in claimTxResults and updateTxResults.The transactions of a registration or an eligibility admission.
plan.steps holds one entry per transaction with transaction.to, transaction.data and chainId.With
WHITELIST_ADMISSION: listId, listName, listAddress, alreadyListed and plan for each whitelist.curl -X POST "https://api.trusset.org/customers/api/onboarding/client-48213/transactions" \
-H "Content-Type: application/json" \
-H "X-API-Key: trusset_your_key_here" \
-d '{ "signerAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72" }'
const response = await fetch(
'https://api.trusset.org/customers/api/onboarding/client-48213/transactions',
{
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-API-Key': 'trusset_your_key_here' },
body: JSON.stringify({ signerAddress: await signer.getAddress() })
}
);
const { data } = await response.json();
for (const step of data.plan.steps) {
const sent = await signer.sendTransaction({ to: step.transaction.to, data: step.transaction.data });
await sent.wait();
}
{
"success": true,
"data": {
"kind": "IDENTITY_REGISTRATION",
"pendingId": "cmwgx2gur0014iinmh8m2eb6c",
"plan": {
"action": "SIGN_TRANSACTIONS",
"registerKind": "TRUSSET",
"steps": [
{
"action": "SIGN_TRANSACTION",
"chainId": 11155111,
"transaction": { "to": "0xEf244c4Bd4d71Bd9A30EDF6Edef7CCC72642291a", "data": "0x9f4cc990000000000000000000000000..." },
"functionName": "batchVerifyIdentities",
"description": "Register 1 verified identity on-chain",
"stepType": "verify",
"ids": ["cmwgx2gur0014iinmh8m2eb6c"]
},
{
"action": "SIGN_TRANSACTION",
"chainId": 11155111,
"transaction": { "to": "0xEf244c4Bd4d71Bd9A30EDF6Edef7CCC72642291a", "data": "0x07363788000000000000000000000000..." },
"functionName": "addClaim",
"description": "Add residency claim for 0xe228fefc0f7ffe27e27c8e6463c44f1bce72151f",
"stepType": "residencyClaim",
"id": "cmwgx2gur0014iinmh8m2eb6c"
}
],
"total": 1,
"ids": ["cmwgx2gur0014iinmh8m2eb6c"],
"operations": { "cmwgx2gur0014iinmh8m2eb6c": "verify" }
},
"confirmWith": {
"method": "POST",
"endpoint": "/customers/api/onboarding/cmwgx2e5l000giinmq96qvnzr/transactions/confirm",
"kind": "IDENTITY_REGISTRATION",
"fields": ["txHash", "updateTxResults", "claimTxResults"]
},
"onboarding": { "customerId": "cmwgx2e5l000giinmq96qvnzr", "status": "AWAITING_SIGNATURE" }
},
"error": null,
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-11-14T21:27:27.000Z"
}
}
onboarding and the calldata. plan also carries the confirmWith of the pending queue, which names the same confirmation on its own endpoint.
Error Codes
| Code | HTTP | Cause |
|---|---|---|
INVALID_ADDRESS | 400 | signerAddress is malformed |
INVALID_INPUT | 400 | claimSignatures is not a list, or holds more than 400 entries |
COUNTRY_BLOCKED | 403 | The profile now blocks the customer’s country |
KYC_PROVIDER_ROLE_MISSING | 403 | No wallet of your instance holds the role the registration needs. See Which register you write to |
CUSTOMER_NOT_FOUND | 404 | No customer of your instance matches customer |
NOTHING_TO_SIGN | 409 | The onboarding does not read AWAITING_SIGNATURE. error.details carries its status and nextAction |
IDENTITY_HELD_BY_ANOTHER_ISSUER | 409 | Another issuer registered the wallet on the Trusset ID Register |
RATE_LIMIT_EXCEEDED | 429 | More than 120 onboarding writes in the minute |
ONBOARDING_BUILD_FAILED | 500 | The build failed on the server |
CHAIN_UNAVAILABLE | 503 | The chain could not be read. Retry shortly |
⌘I
curl -X POST "https://api.trusset.org/customers/api/onboarding/client-48213/transactions" \
-H "Content-Type: application/json" \
-H "X-API-Key: trusset_your_key_here" \
-d '{ "signerAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72" }'
const response = await fetch(
'https://api.trusset.org/customers/api/onboarding/client-48213/transactions',
{
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-API-Key': 'trusset_your_key_here' },
body: JSON.stringify({ signerAddress: await signer.getAddress() })
}
);
const { data } = await response.json();
for (const step of data.plan.steps) {
const sent = await signer.sendTransaction({ to: step.transaction.to, data: step.transaction.data });
await sent.wait();
}
{
"success": true,
"data": {
"kind": "IDENTITY_REGISTRATION",
"pendingId": "cmwgx2gur0014iinmh8m2eb6c",
"plan": {
"action": "SIGN_TRANSACTIONS",
"registerKind": "TRUSSET",
"steps": [
{
"action": "SIGN_TRANSACTION",
"chainId": 11155111,
"transaction": { "to": "0xEf244c4Bd4d71Bd9A30EDF6Edef7CCC72642291a", "data": "0x9f4cc990000000000000000000000000..." },
"functionName": "batchVerifyIdentities",
"description": "Register 1 verified identity on-chain",
"stepType": "verify",
"ids": ["cmwgx2gur0014iinmh8m2eb6c"]
},
{
"action": "SIGN_TRANSACTION",
"chainId": 11155111,
"transaction": { "to": "0xEf244c4Bd4d71Bd9A30EDF6Edef7CCC72642291a", "data": "0x07363788000000000000000000000000..." },
"functionName": "addClaim",
"description": "Add residency claim for 0xe228fefc0f7ffe27e27c8e6463c44f1bce72151f",
"stepType": "residencyClaim",
"id": "cmwgx2gur0014iinmh8m2eb6c"
}
],
"total": 1,
"ids": ["cmwgx2gur0014iinmh8m2eb6c"],
"operations": { "cmwgx2gur0014iinmh8m2eb6c": "verify" }
},
"confirmWith": {
"method": "POST",
"endpoint": "/customers/api/onboarding/cmwgx2e5l000giinmq96qvnzr/transactions/confirm",
"kind": "IDENTITY_REGISTRATION",
"fields": ["txHash", "updateTxResults", "claimTxResults"]
},
"onboarding": { "customerId": "cmwgx2e5l000giinmq96qvnzr", "status": "AWAITING_SIGNATURE" }
},
"error": null,
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-11-14T21:27:27.000Z"
}
}
