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 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
SetverifyOnChain: 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.
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 flatSyncRecord objects. Useful for syncing Trusset state back into your core systems or for audit purposes.
SyncRecord schema
Every record requiresexternalId. All other fields are optional.
Handle per-record errors
Import errors are collected per-record rather than failing the entire batch. Theerrors array in the result contains one entry per failed record:
