Skip to main content
The sync sub-module handles bulk migration of customer data between your existing systems and Trusset. It is designed for institutions with established customer databases that need to onboard thousands of records without manual entry. Records are mapped by externalId, your system’s unique customer identifier. The SDK uses it for deduplication and conflict resolution across syncs.

Import records

externalId is the only required field on a record. kycHash takes the root hash from the KYC proof tool, which is what lets proof-backed claims attach later.
The result counts each outcome separately: The SDK processes records in configurable batches to avoid overloading the API. Each record is matched against existing customers by externalId. If a match is found, the onConflict strategy determines the outcome.

Conflict strategies

Verify on-chain during import

Set verifyOnChain: true to batch-verify imported records on chain once the database import completes. It applies to records that were created or updated, not skipped, and that carry both a walletAddress and a country. Each record’s kycHash, the root hash from the KYC proof tool, goes into the on-chain verification, so proof-backed claims can be added later. The verification transactions are signed by your registered issuer wallet, so verifyOnChain requires signer, any ethers v5 Signer for that wallet. The import throws a ValidationError before touching any record when signer is missing.
On-chain verification failures do not roll back the database import. Every entry the API refuses, whether while preparing the transaction or while confirming it, appears in result.errors with the API’s code, for example a country the verification profile blocks. When a whole verification batch fails, each of its entries appears with code VERIFY_FAILED. Verification errors carry the record’s own externalId, like every other error in the report.

Export records

Pull all customer data back out as flat SyncRecord objects. Useful for syncing Trusset state back into your core systems or for audit purposes.
The method paginates internally and fetches all records regardless of total count. For very large datasets (50k+ customers), consider using the list endpoint directly with pagination for more control.

SyncRecord schema

Every record requires externalId. All other fields are optional.

Handle per-record errors

Import errors are collected per-record rather than failing the entire batch. The errors array in the result contains one entry per failed record:
Common error codes: