How to connect your customer records with Myaza Trust
Connect the customers already in your application to Myaza records using stable references. Retain what you know about their verification source rather than upgrading imported claims into verified facts.
Charles Archibong, Co-founder
· 3 min read
Key takeaways
- One external reference resolves to the intended record.
- Import acknowledgement and completion are distinct.
- Failed rows remain explainable and retryable.
- Imported claims retain truthful provenance.
- A scoped recapture attaches to the existing customer.
Connect the customers already in your application to Myaza records using stable references. Retain what you know about their verification source rather than upgrading imported claims into verified facts.
Before you begin
Stable customer references
Authorised import or profile-management access
Use a team member with permission for this control. Check the organisation and environment before changing a setting. Review the current price before a paid check or ongoing enrolment. Screenshots show an example workspace or the public integration reference; they do not show a real customer or a completed paid check.
Set up and use the capability
Step 1: Choose a stable customer reference
Use the durable customer or business ID from your own system as externalUserId. Keep one reference for the same subject across imports, verification and activity. Decide whether the subject is an individual or business. Do not use an email that can change as the only customer key. Obtain authority to transfer the profile details you intend to register.
Integration reference: Register or update an entity
Step 2: Choose the correct provenance
Use UNVERIFIED for a record that has not completed verification. Use EXTERNAL_VERIFIED only when your own authorised KYC process verified it, with a truthful kycSource. Do not claim MYAZA_VERIFIED for an imported external record merely to unlock a feature. Identity links and risk evidence depend on their own contracts; a claimed wallet is not ownership evidence.
Integration reference: KYC provenance & identity resolution
Step 3: Register one record from your backend
Call POST /api/identity/entities with a secret key and the customer’s externalUserId, type and permitted profile. Supply only known details. Reusing the same customer reference updates the existing entity rather than creating another one. Keep metadata replacement semantics deliberate, and store the returned entityId with your application record.
Integration reference: Request
Step 4: Read back the record before sending activity
Retrieve GET /api/identity/entities/{externalUserId} and compare the returned subject, provenance and permitted profile with the intended record. Review screening enrolment separately. INACTIVE means screening is not active; QUEUED is not a completed clear check. Keep Myaza entity IDs and your external references distinct so later assessments use the endpoint’s expected subject form.
Integration reference: Look up an entity
Step 5: Import a larger book using the async job
For a supported batch, call POST /api/identity/entities/import with 1–1,000 entries using the documented registration shape. Store the returned jobId from the 202 response. Poll the job’s progress until it settles, then inspect succeeded, failed and pending counts and the bounded failure details. An acknowledged import is not proof every row succeeded.
Integration reference: Bulk import
Step 6: Fix failures and connect the next capability
Reconcile failed customer references against your source data before retrying them. Do not reimport successful records with fabricated values. Once a record exists, link capture using the same reference or send supported account activity. Explicit risk assessments and monitoring may need the returned entity ID and separate activation. Maintain customer-level errors and job evidence for support.
Integration reference: Assess or monitor an existing customer
Get more from the capability
Keep the customer reference stable when a profile name or email changes.
Use truthful external-verification provenance and retain the source so reviewers can understand the origin.
Treat wallet addresses as scoped risk attributes, not global identity keys or permission to transfer.
Test before relying on it
Run the supported Sandbox or simulator scenarios for this product. Where a tool is Production only, check access and scope first, then use only a permitted, deliberately reviewed Production test. A documentation screenshot or a successful page load is not an end-to-end integration test.
One external reference resolves to the intended record.
Import acknowledgement and completion are distinct.
Failed rows remain explainable and retryable.
Imported claims retain truthful provenance.
A scoped recapture attaches to the existing customer.
Troubleshooting
A batch returned 202 but records are missing
Read the durable job’s progress and failures instead of assuming acknowledgement means completion.
A profile edit is refused
Check which fields the contract allows for that verified record. Do not overwrite verified identity facts through a general patch.
An assessment cannot find the customer
Check the organisation, environment, reference type and entity ID expected by that endpoint.
Open the setup and integration references
Read the integration reference
Back to Solutions. Choose the capability you want to activate, then follow its own guide.
Sources
Charles Archibong
Co-founder
Charles Archibong co-founded Myaza Trust. He writes about identity verification, financial technology, and the practical work of building trusted digital services.
