Workflows
A workflow is a verification flow you build once in the dashboard (the capture steps, the countries and ID types, the branding and copy, any extra checks, and an optional decisioning graph), and then reuse without touching your code. Instead of passing a dozen props to the SDK, you reference a workflow by its id (wf_…) and the server hands the SDK the whole configuration.
Because the configuration lives on the server, you can change the flow (add a step, tighten a rule, tweak the welcome copy) by re-publishing in the dashboard. Live integrations pick up the new version on their next verification. No SDK upgrade, no redeploy.
Build workflows under Dashboard → Workflows. Each is scoped to one environment (a sandbox workflow doesn't exist in production) and has a draft you edit and a published snapshot your integrations read.
Three ways to run a workflow
1. Embed it in the SDK (workflowId)
Mount the Web, React Native, or Flutter SDK with a workflowId instead of spelling out country, idTypes, and the step toggles:
Minimum SDK versions for
workflowId. Web@myazahq/kyc-sdk-react≥ 2.2.0 · React Native@myazahq/kyc-sdk-react-native≥ 2.1.0 · Flutterkyc_sdk_flutter≥ 2.2.0. Earlier versions can't resolve a workflow ID: the web and React Native SDKs silently ignore it (the flow runs on props alone), and Flutter below 2.2.0 won't compile a workflow mount without a placeholdercountry. If a workflow embed seems to "do nothing", check the installed SDK version first.
<MyazaKYC
apiKey="pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
workflowId="wf_AbC123dEf456"
userId="user_42"
metadata={{ requestId: "order_1001" }}
onSubmit={(s) => console.log(s.verificationId)}
/>The SDK resolves the workflow on mount and uses it as the source of truth: the workflow's configuration wins over any overlapping props (country, ID types, step toggles, appearance, copy). Runtime data (userId, userData, metadata, and your callbacks) always comes from your code. With a workflowId, country becomes optional (the workflow carries it).
An unknown, unpublished, or wrong-environment workflow surfaces as a blocking error via onError, never a silently different flow.
2. Share a hosted link
Every published workflow can also be turned into a hosted link: a public URL you send directly to a person (WhatsApp, email, SMS) with zero integration:
https://trust.myaza.co/verify/workflow/<linkToken>The person opens the link, completes the flow in their browser, and you receive the result by webhook exactly as you would from an embedded SDK. Desktop visitors are offered a "continue on your phone" QR hand-off for the camera steps. Enable, disable, or regenerate the link from the workflow's page. Regenerating immediately kills the old URL. A link opened inside a WebView or an iframe reports the applicant's progress to its host as hosted link events.
3. Mint a per-applicant session from your backend
When you know exactly who should verify, POST /api/kyc/sessions (secret key) mints a hosted link that belongs to one applicant: single use, traceable to your externalUserId, optionally prefilled with what you already know, and optionally emailed on your behalf. A hosted link is one URL for many people; this is one URL for one person. The dashboard's "Create session" action mints the same thing by hand.
How the SDK resolves a workflow
When mounted with a workflowId, the SDK calls one endpoint (instead of GET /config):
GET /api/kyc/workflows/:workflowId
Authorization: Bearer pk_…{
"workflow": { "id": "wf_AbC123dEf456", "name": "Standard KYC", "version": 3 },
"config": { "country": "NG", "idTypes": ["bvn", "passport"], "enableLiveness": true },
"environment": "PRODUCTION",
"idTypes": [ { "country": "NG", "idType": "bvn", "features": { "govDbCheck": true } } ],
"branding": { "companyName": "Acme Inc.", "logo": "https://…", "primaryColor": "#5645F5" }
}The workflow must belong to the API key's organisation and environment and be published: anything else is an indistinguishable 404 workflow_not_found, so ids can't be probed across organisations. The config is org-authored template data and contains no PII, so a publishable (pk_) key is enough. You normally never call this yourself; the SDK does.
Capture add-ons
A workflow can turn on extra capture steps and checks beyond the core document + selfie + liveness flow. Each one is a step you toggle in the builder; most feed a soft signal into decisioning without ever changing the verification's own pass/fail status.
| Add-on | What it does |
|---|---|
| Contact verification | An email and/or phone OTP right after consent: a cheap possession check that filters fake contacts before any gov-DB or liveness spend. Branch on email.disposable, phone.countryMismatch, and the like. |
| Proof of Address | Collects a utility bill / bank statement / tenancy document, then checks the name match and recency. Branch on verification.poaStatus. |
| Address Intelligence | A map pin (+ optional entrance photo and directions) corroborated against the government record, the PoA document and the IP country. On KYB flows the pin is the business premises. Branch on address.tier and the other address.* fields. |
| NFC chip read | Reads the eMRTD chip in a passport (mobile only) and runs server-side passive authentication, the strongest assurance tier. Branch on verification.nfcStatus / verification.assuranceLevel. |
| Questionnaire | Extra compliance declarations (source of funds, expected volume, …) asked before submission. Answers ride the webhook and can be branched on as questionnaire.<key>. A question can map onto canonical profile fields via mapsTo, including walletAddress, which appends the answer to the entity's wallet set and enrols WALLET screening. |
| Device Intelligence | Device + IP fraud analysis (multi-accounting, emulators, datacentre IPs, velocity), on by default. Branch on device.* and ip.*. |
| Liveness mode | Choose gesture challenges, the screen-flash sequence, or both for the strongest presence check. |
| Multi-region | List several countries; the flow opens with a country-select step and applies that country's ID types and validation rules. |
| Multiple IDs | Verify two or three IDs in one run (e.g. NIN and BVN): the applicant picks each from what you allow for their country, one selfie covers them all, and it lands as one verification whose result follows your pass policy (all must pass, at least two, or any one). Works across regions, each country choosing which IDs its verifications offer. Branch on the multiId.* fields for finer routing. |
The web SDK accepts these as props too, but a workflow is the recommended path: you compose the checks once in the dashboard, and every embed and hosted link inherits them, and you change them by re-publishing, with no redeploy.
Templates
New workflows start from a template: a pre-built flow you can use as-is or customise. Templates are country-agnostic (you pick the country and ID types in the builder) and ship with a sensible decision graph. The catalogue:
Onboarding: everyday signup shapes.
- Standard KYC: full capture, auto-approve on pass.
- Low-friction signup: number-only IDs (BVN/NIN) + selfie; failures go to review, not decline.
- Hosted link collection: tuned for sharing; can't be dismissed mid-way, desktop→phone hand-off.
- Re-verification: a light refresh for customers due for renewal.
- High-assurance biometric: camera-only, gesture + flash liveness, NFC chip read; chip-verified identities auto-approve, softer matches go to review.
- Contact-verified onboarding: email + phone OTP before capture; throwaway emails routed to review.
Compliance: screening, strict regimes, human-in-the-loop.
- KYC + AML screening: screen every verified user; watchlist hits open a case.
- Strict compliance: auto-decline confirmed matches, escalate the rest.
- Manual review everything: no auto-approvals; a human signs off each customer.
- Geographic risk routing: extra scrutiny for high-risk nationalities or IP-country mismatches.
- Risk-tiered onboarding: let the monitoring risk tier set the friction.
- Crypto exchange onboarding: full KYC plus AML screening that covers the customer's crypto wallet addresses; watchlist or wallet hits open a case, network-flagged identities are declined.
Specialised: targeted checks.
- Age-gated service (18+): verify identity and age together.
- Expired-document guard: decline expired IDs, flag soon-to-expire ones.
- Network trust fast-track: trust identities already verified elsewhere on the Myaza network.
- Strict data & face match: both checks must explicitly pass.
- Failure triage & retry: give recoverable capture failures a second chance.
- Device & IP fraud guard: route multi-accounting, emulator, and bot signals to review.
- Address-verified onboarding: identity plus a proof-of-address check.
- Presence-verified address: smart-address capture plus a multi-day presence watch the decision holds on.
- Address-only verification: no identity step at all; the address capture is the whole flow, for books verified elsewhere. See Address Intelligence.
- Biometric enrolment and Face re-authentication: a liveness selfie into, then against, the customer's biometric template; the workflow-shaped face check with contact-code companions and a decision on the outcome.
- Declarations refresh: a questionnaire alone, for periodic attestations and source-of-funds updates.
- Contact re-verification: one-time codes to the email and phone on file, nothing else.
These five are scoped workflows: scope on the config names the one thing the flow verifies (address, biometric-authentication, biometric-enrollment, questionnaire, contact), publish rejects any stronger evidence, submissions carry the scope's marker idType and require the published workflow, and the capture lands on your existing customer record by externalUserId without ever touching its KYC status.
A workflow's scope is chosen with the Scope control at the top of the builder rail and is editable until the first publish, then locked: verifications, hosted links and embeds already reference what that workflow ID verifies, so a mid-life change would rewrite their meaning (the API returns scope_locked). To get a different scope from a live workflow, use Scoped copy on the workflows list. It creates a fresh draft under a new workflow ID that carries the parts that mean the same thing under any scope (branding, country, contact steps, session policy) and none of the identity evidence, seeded so the copy opens ready to publish.
Business (KYB): registry lookups with due diligence.
- Standard KYB: registry lookup with a customer due-diligence gate for key people.
- KYB + AML screening: screen every verified business before approval.
- Enhanced KYB with declarations: registry check plus a compliance questionnaire.
Business (KYB) workflows
A workflow can verify a business instead of a person. It looks the company up in the official registry, optionally collects company documents and declarations, and runs customer due diligence on the people who own or control it, screening directors, beneficial owners (UBOs), and the applicant, and optionally requiring each to complete their own KYC via a per-person invite link.
Live business submissions require a published KYB workflow; the server rejects a business verification with no workflow. See Business verification (KYB) for the full guide (products, the application layers, the result shape, and decisioning), Key people & ownership for the due-diligence layer (roles, thresholds, corporate shareholders, ownership chains), and Supported countries for registry coverage.
Versioning
Editing a published workflow only changes its draft: live integrations keep seeing the last published snapshot until you publish again. Every publish bumps the version and appends an immutable history entry you can inspect or restore from. Each verification records the exact workflowId and version that drove it, and the data.workflowId field appears on every verification webhook so you can attribute results back to a flow.
Next steps
- Decisioning: the rules engine that turns verification data into approve / decline / review.
- Webhooks: the
workflow.run.completedevent and workflow attribution on results. - Web SDK: mounting with a
workflowId.