Management
Create Customer
Register a new customer for the authenticated instance
POST
/
customers
/
api
/
manage
curl -X POST "https://api.trusset.org/customers/api/manage" \
-H "Content-Type: application/json" \
-H "X-API-Key: trusset_abc123xy_secret..." \
-d '{
"walletAddress": "0xaBc123DEf456789012345678901234567890aBCD",
"name": "Acme Corp",
"customerType": "COMPANY",
"companyUrl": "acme.example",
"country": "DE",
"investorType": "PROFESSIONAL"
}'
curl -X POST "https://api.trusset.org/customers/api/manage" \
-H "Content-Type: application/json" \
-H "X-API-Key: trusset_abc123xy_secret..." \
-d '{
"name": "Acme Corp",
"customerType": "COMPANY",
"country": "DE",
"investorType": "PROFESSIONAL"
}'
const response = await fetch('https://api.trusset.org/customers/api/manage', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'trusset_abc123xy_secret...'
},
body: JSON.stringify({
name: 'Acme Corp',
customerType: 'COMPANY',
country: 'DE',
investorType: 'PROFESSIONAL'
})
});
const { data: customer } = await response.json();
console.log(customer.referenceKey);
{
"success": true,
"data": {
"id": "cmt0k3b9x0004cghxw7r2d5ya",
"instanceId": "cmrz4d1v20000cghx8k6p3m7t",
"issuerId": "cmrz3a8q10000cghxf5w2n9k4",
"walletAddress": "0xaBc123DEf456789012345678901234567890aBCD",
"externalId": null,
"name": "Acme Corp",
"country": "DEU",
"investorType": "PROFESSIONAL",
"customerType": "COMPANY",
"companyUrl": "https://acme.example/",
"companyId": null,
"status": "pending",
"frozen": false,
"kycHash": null,
"onChainTxHash": null,
"sumsubApplicantId": null,
"idLinkId": null,
"referenceKey": null,
"contactChannels": [],
"metadata": null,
"archived": false,
"archivedAt": null,
"verifiedAt": null,
"revokedAt": null,
"onChainSyncedAt": null,
"createdAt": "2026-09-30T12:00:00.000Z",
"updatedAt": "2026-09-30T12:00:00.000Z"
},
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-09-30T12:00:00.000Z"
}
}
{
"success": true,
"data": {
"id": "cmt0k3b9x0004cghxw7r2d5ya",
"instanceId": "cmrz4d1v20000cghx8k6p3m7t",
"issuerId": "cmrz3a8q10000cghxf5w2n9k4",
"walletAddress": null,
"externalId": null,
"name": "Acme Corp",
"country": "DEU",
"investorType": "PROFESSIONAL",
"customerType": "COMPANY",
"companyUrl": null,
"companyId": null,
"status": "pending",
"frozen": false,
"kycHash": null,
"onChainTxHash": null,
"sumsubApplicantId": null,
"idLinkId": null,
"referenceKey": "ref_a1b2c3d4e5f67890abcdef1234567890",
"contactChannels": [],
"metadata": null,
"archived": false,
"archivedAt": null,
"verifiedAt": null,
"revokedAt": null,
"onChainSyncedAt": null,
"createdAt": "2026-09-30T12:00:00.000Z",
"updatedAt": "2026-09-30T12:00:00.000Z"
},
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-09-30T12:00:00.000Z"
}
}
{
"success": false,
"error": {
"code": "CUSTOMER_EXISTS",
"message": "Customer with this wallet already exists"
},
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-09-30T12:00:00.000Z"
}
}
Creates a new customer record tied to the authenticated instance. You can either provide a wallet address directly, or omit it to receive a
referenceKey that allows linking a wallet later via the Link Wallet endpoint.
If an archived customer on your instance has this
walletAddress as its primary, the call restores that record rather than creating one. The record keeps its ID, linked wallets and kycHash. Its status and verifiedAt are set as for a new record, and its referenceKey is cleared. Every other field this endpoint takes is replaced from the body, and a field you omit is cleared or reset to its default.Body Parameters
At least one ofname, walletAddress and externalId is required.
string
Primary wallet. Letter case does not matter, but a mixed-case address must carry a valid checksum. Stored checksummed. If omitted, a
referenceKey is generated for deferred wallet linking.string
Customer display name. Required when
customerType is COMPANY.string
Your own external reference identifier for this customer. It must be unique among the customers of your instance that are not archived. Update Customer does not take it.
string
default:"INDIVIDUAL"
INDIVIDUAL or COMPANY, in any letter case. Update Customer refuses to change it.string
ISO 3166-1 alpha-2, alpha-3 or numeric code, in any letter case (
DE, DEU or 276). Stored and returned as alpha-3.string
default:"RETAIL"
RETAIL, PROFESSIONAL or ELIGIBLE_COUNTERPARTY in any letter case, or the key of one of your custom verification profiles, also in any letter case. The record stores the key as the profile spells it, so professional is stored as PROFESSIONAL. A profile that is disabled takes no new customer, so naming one is refused with INVALID_INVESTOR_TYPE and the message says the profile is disabled. Omitted, null or an empty string stores RETAIL, unless the RETAIL preset is disabled. Anything else, a number included, is refused with INVALID_INVESTOR_TYPE, and the message lists the values your instance accepts.When the profile’s blocked-country list holds country, the call is refused with COUNTRY_BLOCKED.string
Company records only. Up to 300 characters.
https:// is added when no scheme is given, and the URL must use http or https with a dotted hostname. Stored in normalised form.string
Individual records only. The ID of a company record on your instance that is not archived.
string[]
Up to 20 strings of up to 200 characters each. Entries are trimmed, blank ones are dropped, and duplicates are removed ignoring case.
object
Arbitrary key-value metadata to store with the customer record.
Response Fields
Returns201, including when an archived record was restored.
boolean
Request status
object
The customer record, with the fields listed on Get Customer other than its linked wallets, company links, Sumsub applicant record and audit entries.
referenceKey is set when no walletAddress was sent.status starts as pending. It starts as verified when the registry already holds a verified identity for walletAddress, registered by the Trusset platform verifier or by one of your instance’s verified wallets. On an instance bound to its own register, any verifier counts. A registry read that fails leaves the record pending and does not fail the call.curl -X POST "https://api.trusset.org/customers/api/manage" \
-H "Content-Type: application/json" \
-H "X-API-Key: trusset_abc123xy_secret..." \
-d '{
"walletAddress": "0xaBc123DEf456789012345678901234567890aBCD",
"name": "Acme Corp",
"customerType": "COMPANY",
"companyUrl": "acme.example",
"country": "DE",
"investorType": "PROFESSIONAL"
}'
curl -X POST "https://api.trusset.org/customers/api/manage" \
-H "Content-Type: application/json" \
-H "X-API-Key: trusset_abc123xy_secret..." \
-d '{
"name": "Acme Corp",
"customerType": "COMPANY",
"country": "DE",
"investorType": "PROFESSIONAL"
}'
const response = await fetch('https://api.trusset.org/customers/api/manage', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'trusset_abc123xy_secret...'
},
body: JSON.stringify({
name: 'Acme Corp',
customerType: 'COMPANY',
country: 'DE',
investorType: 'PROFESSIONAL'
})
});
const { data: customer } = await response.json();
console.log(customer.referenceKey);
{
"success": true,
"data": {
"id": "cmt0k3b9x0004cghxw7r2d5ya",
"instanceId": "cmrz4d1v20000cghx8k6p3m7t",
"issuerId": "cmrz3a8q10000cghxf5w2n9k4",
"walletAddress": "0xaBc123DEf456789012345678901234567890aBCD",
"externalId": null,
"name": "Acme Corp",
"country": "DEU",
"investorType": "PROFESSIONAL",
"customerType": "COMPANY",
"companyUrl": "https://acme.example/",
"companyId": null,
"status": "pending",
"frozen": false,
"kycHash": null,
"onChainTxHash": null,
"sumsubApplicantId": null,
"idLinkId": null,
"referenceKey": null,
"contactChannels": [],
"metadata": null,
"archived": false,
"archivedAt": null,
"verifiedAt": null,
"revokedAt": null,
"onChainSyncedAt": null,
"createdAt": "2026-09-30T12:00:00.000Z",
"updatedAt": "2026-09-30T12:00:00.000Z"
},
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-09-30T12:00:00.000Z"
}
}
{
"success": true,
"data": {
"id": "cmt0k3b9x0004cghxw7r2d5ya",
"instanceId": "cmrz4d1v20000cghx8k6p3m7t",
"issuerId": "cmrz3a8q10000cghxf5w2n9k4",
"walletAddress": null,
"externalId": null,
"name": "Acme Corp",
"country": "DEU",
"investorType": "PROFESSIONAL",
"customerType": "COMPANY",
"companyUrl": null,
"companyId": null,
"status": "pending",
"frozen": false,
"kycHash": null,
"onChainTxHash": null,
"sumsubApplicantId": null,
"idLinkId": null,
"referenceKey": "ref_a1b2c3d4e5f67890abcdef1234567890",
"contactChannels": [],
"metadata": null,
"archived": false,
"archivedAt": null,
"verifiedAt": null,
"revokedAt": null,
"onChainSyncedAt": null,
"createdAt": "2026-09-30T12:00:00.000Z",
"updatedAt": "2026-09-30T12:00:00.000Z"
},
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-09-30T12:00:00.000Z"
}
}
{
"success": false,
"error": {
"code": "CUSTOMER_EXISTS",
"message": "Customer with this wallet already exists"
},
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-09-30T12:00:00.000Z"
}
}
Error Codes
| Code | HTTP | Cause |
|---|---|---|
INVALID_COUNTRY | 400 | country is not an ISO 3166-1 code |
INVALID_INVESTOR_TYPE | 400 | investorType names neither a preset nor one of your verification profiles, names a disabled profile, or is not a string |
MISSING_IDENTIFIER | 400 | None of name, walletAddress and externalId was sent |
INVALID_ADDRESS | 400 | walletAddress is not a valid address |
INVALID_CUSTOMER_TYPE | 400 | customerType is not INDIVIDUAL or COMPANY |
MISSING_NAME | 400 | A company was sent without name |
COMPANY_CANNOT_LINK | 400 | A company was sent with companyId |
INVALID_COMPANY_URL | 400 | companyUrl was sent for an individual, or is not a usable URL |
COMPANY_URL_TOO_LONG | 400 | companyUrl is over 300 characters |
INVALID_COMPANY | 400 | companyId is not a string of 20 to 40 characters |
INVALID_CONTACT_CHANNELS | 400 | contactChannels is not an array |
TOO_MANY_CONTACT_CHANNELS | 400 | More than 20 contact channels |
INVALID_CONTACT_CHANNEL | 400 | A contact channel is not a string |
CONTACT_CHANNEL_TOO_LONG | 400 | A contact channel is over 200 characters |
COUNTRY_BLOCKED | 403 | country is on the blocked-country list of the profile investorType names |
COMPANY_NOT_FOUND | 404 | companyId names no company record on your instance that is not archived |
CUSTOMER_EXISTS | 409 | The wallet is another active customer’s primary or any customer’s linked wallet, or externalId is taken |
CREATE_FAILED | 500 | The record could not be written |
⌘I
curl -X POST "https://api.trusset.org/customers/api/manage" \
-H "Content-Type: application/json" \
-H "X-API-Key: trusset_abc123xy_secret..." \
-d '{
"walletAddress": "0xaBc123DEf456789012345678901234567890aBCD",
"name": "Acme Corp",
"customerType": "COMPANY",
"companyUrl": "acme.example",
"country": "DE",
"investorType": "PROFESSIONAL"
}'
curl -X POST "https://api.trusset.org/customers/api/manage" \
-H "Content-Type: application/json" \
-H "X-API-Key: trusset_abc123xy_secret..." \
-d '{
"name": "Acme Corp",
"customerType": "COMPANY",
"country": "DE",
"investorType": "PROFESSIONAL"
}'
const response = await fetch('https://api.trusset.org/customers/api/manage', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'trusset_abc123xy_secret...'
},
body: JSON.stringify({
name: 'Acme Corp',
customerType: 'COMPANY',
country: 'DE',
investorType: 'PROFESSIONAL'
})
});
const { data: customer } = await response.json();
console.log(customer.referenceKey);
{
"success": true,
"data": {
"id": "cmt0k3b9x0004cghxw7r2d5ya",
"instanceId": "cmrz4d1v20000cghx8k6p3m7t",
"issuerId": "cmrz3a8q10000cghxf5w2n9k4",
"walletAddress": "0xaBc123DEf456789012345678901234567890aBCD",
"externalId": null,
"name": "Acme Corp",
"country": "DEU",
"investorType": "PROFESSIONAL",
"customerType": "COMPANY",
"companyUrl": "https://acme.example/",
"companyId": null,
"status": "pending",
"frozen": false,
"kycHash": null,
"onChainTxHash": null,
"sumsubApplicantId": null,
"idLinkId": null,
"referenceKey": null,
"contactChannels": [],
"metadata": null,
"archived": false,
"archivedAt": null,
"verifiedAt": null,
"revokedAt": null,
"onChainSyncedAt": null,
"createdAt": "2026-09-30T12:00:00.000Z",
"updatedAt": "2026-09-30T12:00:00.000Z"
},
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-09-30T12:00:00.000Z"
}
}
{
"success": true,
"data": {
"id": "cmt0k3b9x0004cghxw7r2d5ya",
"instanceId": "cmrz4d1v20000cghx8k6p3m7t",
"issuerId": "cmrz3a8q10000cghxf5w2n9k4",
"walletAddress": null,
"externalId": null,
"name": "Acme Corp",
"country": "DEU",
"investorType": "PROFESSIONAL",
"customerType": "COMPANY",
"companyUrl": null,
"companyId": null,
"status": "pending",
"frozen": false,
"kycHash": null,
"onChainTxHash": null,
"sumsubApplicantId": null,
"idLinkId": null,
"referenceKey": "ref_a1b2c3d4e5f67890abcdef1234567890",
"contactChannels": [],
"metadata": null,
"archived": false,
"archivedAt": null,
"verifiedAt": null,
"revokedAt": null,
"onChainSyncedAt": null,
"createdAt": "2026-09-30T12:00:00.000Z",
"updatedAt": "2026-09-30T12:00:00.000Z"
},
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-09-30T12:00:00.000Z"
}
}
{
"success": false,
"error": {
"code": "CUSTOMER_EXISTS",
"message": "Customer with this wallet already exists"
},
"metadata": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-09-30T12:00:00.000Z"
}
}