Self-service onboarding with identity verification
Lets a person sign up as a merchant without an invitation code: they verify their identity —document, liveness check and face match— and, once it is verified, their lead is created.
There are two ways to verify the person, and both end in the same sign-up:
| Mode | Who captures the photos | When to use it |
|---|---|---|
| Migo verification SDK (recommended) | The SDK, with its own guided capture experience | Mobile and web apps. Better approval rate, and you do not build the capture yourself |
| Image-based verification | Your app, which uploads the document and selfie photos | When you need to control the whole capture interface |
The lead is created with the same endpoint and the same body as the regular sign-up, POST /leads. The difference is a header: when the request carries verificationId, the platform treats it as a verified sign-up; without it, the regular sign-up works exactly as always.
This flow is disabled by default and enabled per merchant. Talk to your Migo contact so they turn it on and grant the permissions to your integration's client. Without the permissions the response is 403 with code 7615; with the permissions but without the flow enabled, 403 with 8110 or 8111.
Verification with the Migo SDK
| Step | Endpoint | What it does |
|---|---|---|
| 1 | POST /onboarding/sessions | Opens the verification and returns the session token for the SDK |
| 2 | (in your app) | The person completes the verification inside the SDK |
| 3 | GET /onboarding/verifications/{verificationId} | You read the result until it is no longer PENDING; it carries the data and the photos |
| 4 | POST /leads with the verificationId header | Creates the lead and the business, and returns the invitation code |
| 5 | Registration and POST /users/login | The login tells you whether the identity is under review |
The SDK mode is enabled per merchant, on top of the flow itself. Your Migo contact shares the verification SDK package for Android, iOS and Flutter, and its version. If the merchant does not have it enabled, step 1 responds 403 with 8111 and you can keep using image-based verification.
1. Open the Session
The merchant and the client come from the token. The body is optional:
curl -X POST https://api.ali.app/rest/onboarding/sessions \
-H "Authorization: Bearer <token>"
If your app already knows the person's document number —for example, the one on the lead of their invitation code—, send it in expectedDocumentNumber:
curl -X POST https://api.ali.app/rest/onboarding/sessions \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "expectedDocumentNumber": "1234567890101" }'
When the merchant has document matching enabled and the person verifies a document with another number, the verification ends DECLINED with the reason DOCUMENT_NUMBER_MISMATCH. The comparison ignores spaces, dashes and case. When the merchant does not have matching enabled, the field is ignored.
{
"success": true,
"data": {
"verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21",
"status": "PENDING",
"sessionId": "<session-id>",
"sessionToken": "<session-token>",
"url": "<session-url>",
"requiredMethods": ["OCR", "LIVENESS", "FACE_MATCH"],
"paymentMethods": [{ "slug": "card", "acquirerSlug": "neonet" }],
"expiresAt": "2026-10-02T18:30:00.000Z"
}
}
Keep the verificationId: it chains the rest of the sign-up. The sessionToken is for the native SDK; the url opens the same verification on the web.
2. Open the SDK
Pass the sessionToken to the verification SDK. The person photographs their document and takes the selfie inside the SDK; your app does not handle images.
When the SDK closes, it tells you whether the person finished, cancelled or hit an error. That signal is not the verification result: use it only to decide what to show. Migo decides the result server-side, and you read it in step 3.
3. Read the Result
curl https://api.ali.app/rest/onboarding/verifications/2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21 \
-H "Authorization: Bearer <token>"
{
"success": true,
"data": {
"verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21",
"status": "APPROVED",
"expiresAt": "2026-10-02T18:30:00.000Z",
"requiredMethods": ["OCR", "LIVENESS", "FACE_MATCH"],
"fields": [
{ "key": "documentNumber", "value": "1234567890101", "source": "OCR", "required": true },
{ "key": "firstName", "value": "ANA MARIA", "source": "OCR", "required": true },
{ "key": "expirationDate", "value": "2031-04-12", "source": "OCR", "required": true },
{ "key": "countryOfBirth", "source": "MANUAL", "required": true },
{ "key": "partner", "value": "migo", "source": "DERIVED", "required": true }
],
"paymentMethods": [{ "slug": "card", "acquirerSlug": "neonet" }]
}
}
| status | What to do |
|---|---|
| PENDING | The result has not arrived yet. Read it again in a few seconds |
| OCR_APPROVED | The document is already approved and the rest of the verification is still pending. Keep reading it as with PENDING |
| APPROVED | Show the fields so the person confirms their data, and move on to step 4 |
| MANUAL_REVIEW | The identity went to review by a person, but the sign-up continues: as with APPROVED, show the fields and move on to step 4. The decision arrives later |
| DECLINED | The verification did not pass and cannot be retried. If it carries reasonCode, use it to tell the person what happened, and open a new session with step 1 |
| CONSUMING | The lead is being created right now. Read it again in a few seconds |
| CONSUMED | The verification already created its lead; the response carries the invitationCode |
The fields read the same as in image-based verification (see the source table below). With DECLINED, the response carries reasonCode with a code from the reason catalog when the decline has an identified one; it may be missing. When a person resolves a review, the response adds resolvedAt.
Verification Photos
With APPROVED, MANUAL_REVIEW or CONSUMED the response adds images: the photos the SDK captured, as signed URLs.
{
"success": true,
"data": {
"verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21",
"status": "MANUAL_REVIEW",
"expiresAt": "2026-10-05T18:30:00.000Z",
"requiredMethods": ["OCR", "LIVENESS", "FACE_MATCH"],
"fields": [
{ "key": "documentNumber", "value": "1234567890101", "source": "OCR", "required": true }
],
"paymentMethods": [{ "slug": "card", "acquirerSlug": "neonet" }],
"images": {
"expiresAt": "2026-10-02T18:40:00.000Z",
"documentFront": "<signed-url>",
"documentBack": "<signed-url>",
"documentPortrait": "<signed-url>",
"selfie": "<signed-url>"
}
}
}
| Key | What it is |
|---|---|
| documentFront | Front of the document |
| documentBack | Back of the document |
| documentPortrait | The person's photo cropped from the document |
| selfie | The face captured in the liveness check |
| expiresAt | Validity of the URLs (10 minutes), not of the verification |
- They are JPEG or PNG images. Download them with a plain GET, without headers.
- Download them as soon as they arrive: if they expire, read the status again for new URLs.
- A photo that does not exist is left out, and images may be missing: your app has to work without them.
- You do not need to upload them when the person registers: they are attached to their document automatically.
- They are personal data: do not write the URLs to your logs.
The verification expires at expiresAt. After that moment the read may still show PENDING, but it will no longer approve and the sign-up responds 410 with 8116: if you reach expiresAt without a result, open a new session.
4. Create the Lead
Same as in image-based verification: POST /leads with the verificationId header, the Idempotency-Key header and the confirmed data. See Create the Lead.
With the verification in MANUAL_REVIEW the sign-up goes through with the same validations, and the response says so:
{
"success": true,
"data": {
"leadId": "6acd72072f1c8219496270ea",
"businessId": "6acd72072f1c8219496270eb",
"invitationCode": "B9B7D57",
"reused": false,
"identityInReview": true
}
}
5. Registration and Login
Registration with the invitationCode of a verified sign-up does not change: the verification photos are attached as the user's document photos. The login (POST /users/login) adds manualReview, always present:
{
"success": true,
"data": {
"status": "PendingVerify",
"hasUploadedIdDocument": true,
"manualReview": true
}
}
| manualReview | When |
|---|---|
| true | The person registered with the identity under review, and the review is still open or ended declined |
| false | The review ended approved, or the person registered with an already approved verification or through another path |
It is informational: it does not change the account status or its permissions. The token refresh does not carry it; read it from the login.
If the Person Already Had an Invitation Code
If the person already had an invitation code and your app used the SDK to verify their identity:
- Open the session with expectedDocumentNumber set to the lead's document.
- Send the verificationId in the registration (POST /users), along with the invitationCode. The verification can be approved or under review.
The photos are attached as the document photos and the login tells you whether the identity went to review. If the merchant has document matching enabled and the verification is for another document, the registration responds 422 with 8121 and does not create the account.
If the registration already happened without the verificationId, link the verification afterwards instead of uploading the photos:
curl -X POST https://api.ali.app/rest/users/<authUserId>/id-document/from-verification \
-H "Authorization: Bearer <token>" \
-H "x-user-token: <user-token>" \
-H "Content-Type: application/json" \
-d '{ "verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21", "type": "DPI" }'
It responds 201 with the URLs of the attached photos. When it cannot link:
| Response | When |
|---|---|
| 400 with 7000 | The verificationId is not a UUID or type is missing |
| 403 with 7144 | The session belongs to another user |
| 404 with 8115 or 8118 | The verification does not exist, or belongs to another merchant |
| 404 with 7102 | The user has no document of that type |
| 409 with 8114 | The verification is not approved, for example because it is still under review |
| 422 with 8119 | The verification is for another document |
Image-Based Verification
| Step | Endpoint | What it does |
|---|---|---|
| 1 | POST /onboarding/ocr | Extracts the document data and opens the verification |
| 2 | POST /onboarding/liveness | Liveness check on a selfie (and, when the merchant asks for it, a match against the document portrait) |
| 3 | POST /leads with the verificationId header | Creates the lead and the business, and returns the invitation code |
The three steps are chained by the verificationId returned in step 1. The check is server-side: step 3 only creates the lead if the verification was approved. Skipping steps 1 and 2 from the client achieves nothing.
Authentication
You use the same access token as any other call, the one returned by POST /auth/login:
curl -X POST https://api.ali.app/rest/auth/login \
-H "Content-Type: application/json" \
-d '{ "merchant": "<merchant>", "signature": "<signature>" }'
The client behind that token needs these permissions:
| Permission | What for |
|---|---|
| onboarding:ocr | Opening the SDK session, reading the result and, in image-based verification, the document step |
| onboarding:liveness | The liveness check of image-based verification |
| leads:create | Creating the lead, same as in the regular sign-up |
In a verified sign-up, the merchant and the client are taken from the token. The x-merchant-id header is ignored, and a clientId in the body is replaced with the one from the token. partner, sdk, country and paymentMethods are taken from the merchant's configuration —the ones step 1 returns as DERIVED— and replace those in the body. You still have to send a valid partner, because the body goes through the same validations as the regular sign-up.
Reading the Responses
Every response uses the same envelope. A successful response has success set to true and the result in data; an error has success set to false and an errors list, each entry with a stable code and a readable message:
{
"success": false,
"errors": [
{ "code": "8116", "message": "Identity verification has expired." }
]
}
Always decide on the code and the HTTP status, never on the message text.
1. Verify the Document
Multipart with the front image (required) and the back image (optional). JPEG or PNG only, up to 5 MB per image. Text fields are not accepted: an extra field returns 422.
curl -X POST https://api.ali.app/rest/onboarding/ocr \
-H "Authorization: Bearer <token>" \
-F "dpiFront=@dpi-front.jpg;type=image/jpeg" \
-F "dpiBack=@dpi-back.jpg;type=image/jpeg"
{
"success": true,
"data": {
"verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21",
"status": "OCR_APPROVED",
"fields": [
{ "key": "documentNumber", "value": "1234567890101", "source": "OCR", "required": true },
{ "key": "firstName", "value": "ANA MARIA", "source": "OCR", "required": true },
{ "key": "expirationDate", "value": "2031-04-12", "source": "OCR", "required": true },
{ "key": "countryOfBirth", "source": "MANUAL", "required": true },
{ "key": "partner", "value": "migo", "source": "DERIVED", "required": true }
],
"blockingFields": [],
"requiredMethods": ["OCR", "LIVENESS"],
"paymentMethods": [{ "slug": "card", "acquirerSlug": "neonet" }],
"expiresAt": "2026-09-01T18:30:00.000Z"
}
}
What status means:
| status | What to do |
|---|---|
| OCR_APPROVED | Continue to step 2 with that verificationId |
| DECLINED | The document could not be approved. Ask for a new capture and call this step again |
A declined document comes back with HTTP 200 and status DECLINED, not as an error. This response does not include the reason for the decline.
The fields list carries the identity data with its origin:
| source | Meaning |
|---|---|
| OCR | Read from the document: prefill it in the form |
| MANUAL | Not on the document: ask the person for it |
| DERIVED | Value configured for the merchant (partner, sdk, country). It is the one the lead uses, even if you send another in step 3 |
Among those fields is expirationDate, the document expiry date, which the lead created in step 3 requires. When the document does not yield it and the merchant does not allow capturing it manually, it comes back in blockingFields and the verification stays DECLINED at this step.
Use that list to build the form: do not hardcode it, because which fields can be entered by hand depends on the merchant's configuration. blockingFields lists the fields the document did not resolve and the merchant does not allow entering by hand; if it has any, the verification is DECLINED. The country of birth never comes from the document, so it always shows up as MANUAL.
2. Liveness Check
curl -X POST https://api.ali.app/rest/onboarding/liveness \
-H "Authorization: Bearer <token>" \
-H "verificationId: 2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21" \
-F "selfie=@selfie.jpg;type=image/jpeg"
{
"success": true,
"data": {
"verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21",
"status": "APPROVED",
"liveness": { "status": "APPROVED", "score": 99, "warnings": [] }
}
}
- score ranges from 0 to 100.
- When the merchant asks to match the selfie against the document portrait, the response also carries faceMatch, with the same shape as liveness.
- With status APPROVED the verification unlocks step 3.
- With status MANUAL_REVIEW the attempts ran out and the verification went to review by a person: see Attempts.
There are two ways this can fail to approve, and they are handled differently:
| What happened | Response | What to do |
|---|---|---|
| The selfie was evaluated and declined | 200 with status DECLINED and the reason in liveness.warnings (or faceMatch.warnings) | The verification stays open: ask for another selfie and send it to this step with the same verificationId. Each decline uses one attempt; if it was the last one, this same call responds 403 with 8120, or 200 with status MANUAL_REVIEW if the merchant routes to review (see Attempts) |
| The verification could not be completed | 422 with 8112 or 503 with 8113 | The verification stays open: the selfie can be sent again. A 422 for a malformed image or verificationId uses no attempt; a failure on the verification side does |
3. Create the Lead
It is POST /leads with the same body as the regular sign-up, plus the verificationId header, the Idempotency-Key header and the two consent fields:
curl -X POST https://api.ali.app/rest/leads \
-H "Authorization: Bearer <token>" \
-H "verificationId: 2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21" \
-H "Idempotency-Key: onboarding-lead-001" \
-H "Content-Type: application/json" \
-d '{
"cui": "1234567890101",
"firstName": "ANA MARIA",
"lastName": "LOPEZ GARCIA",
"dateOfBirth": "1990-04-12",
"expirationDate": "2031-04-12",
"nationality": "GTM",
"countryOfBirth": "GTM",
"gender": "F",
"maritalStatus": "soltero",
"commercialName": "Tienda Ana",
"businessName": "Tienda Ana",
"nit": "1234567",
"address": "4a calle 5-30 zona 1",
"phone": "50255551234",
"taxRegime": "pequeño contribuyente",
"rtuType": "SERVICIO",
"canInvoice": true,
"partner": "migo",
"sdk": "MIGO_PAY",
"country": "GTM",
"paymentMethods": [{ "slug": "akisiQR", "acquirerSlug": "akisiQR" }],
"consentVersion": "v1",
"consentAcceptedAt": "2026-09-01T18:05:00.000Z"
}'
| What | Rule | Otherwise |
|---|---|---|
| Body | The same validations as the regular sign-up | 400 |
| verificationId | The verification from step 1, approved in step 2 | 400 with 7000 if it is not a UUID; 404 with 8115 if it does not exist or with 8118 if it belongs to another merchant; 410 with 8116 if it expired; 403 with 8120 if it ran out of attempts; 409 with 8114 if it is not approved |
| Idempotency-Key | Required, up to 255 characters | 400 with 7000 |
| consentVersion and consentAcceptedAt | The version of the consent the person accepted —it must be the one configured for the merchant; ask your Migo contact for it— and the ISO 8601 date it was accepted | 400 with 7000 |
| Identity data: cui, firstName, lastName, dateOfBirth, expirationDate, nationality, countryOfBirth, placeOfBirth, gender, maritalStatus | Must match the verified document, except the fields the merchant allows editing. Send them as step 1 returned them | 422 with 8119 |
| nit | Required in a verified sign-up | 422 with 8119 |
{
"success": true,
"data": {
"leadId": "000000000000000000000001",
"businessId": "000000000000000000000002",
"invitationCode": "A1B2C3",
"reused": false
}
}
The person continues the rest of the sign-up with that invitationCode, without having to type it. reused set to true means a lead with that document already existed for the merchant; if that lead already completed its registration, the response is 409 with 7121.
Retrying with the same key, while the verification has not expired, returns the original result without creating another lead, even if the data changes (the body must still be valid). Using another key on a verification that already created its lead, or while another request is creating it, returns 409 with 8117. Generate one key per sign-up.
Why It Was Declined
When the liveness check or the face match does not approve, the step 2 response carries warnings, and each one has a code from Migo's catalog. Map that code to your own copy: the catalog stays stable even if the verification technology behind it changes, so your integration does not notice.
The step 1 response does not carry the reason for a declined document. If you need it, read GET /onboarding/verifications/{verificationId} with the verificationId of that response: it carries reasonCode when the decline has an identified one.
| Code | What happened |
|---|---|
| DOCUMENT_EXPIRED | The document has expired |
| DOCUMENT_NOT_RECOGNIZED | The document could not be validated |
| DOCUMENT_TYPE_NOT_SUPPORTED | Document type not supported |
| DOCUMENT_TAMPERED | Tampering detected |
| DOCUMENT_PORTRAIT_MISSING | The document has no portrait |
| DOCUMENT_IN_BLOCKLIST | Document in a blocklist |
| PUBLIC_DOCUMENT_IMAGE | Known public image from the internet |
| DOCUMENT_DATA_UNREADABLE | The data could not be read |
| DOCUMENT_DATA_MISMATCH | The data is inconsistent or does not match what was declared |
| DOCUMENT_NUMBER_MISMATCH | The document is not the expected one. Only with expectedDocumentNumber and document matching enabled |
| IMAGE_TOO_BLURRY | Blurry image |
| IMAGE_LOW_QUALITY | Image too dark or too bright |
| SCREEN_CAPTURE_DETECTED | Photo of a screen |
| PRINTED_COPY_DETECTED | Photocopy |
| MINIMUM_AGE_NOT_MET, MAXIMUM_AGE_EXCEEDED, AGE_NOT_DETECTED | Age out of range or undeterminable |
| DUPLICATE_USER | Possible duplicate user |
| NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED | No face, or more than one |
| LOW_LIVENESS_SCORE, LIVENESS_ATTACK_DETECTED | The liveness check did not pass |
| FACE_QUALITY_TOO_LOW | Selfie quality too low |
| FACE_MISMATCH | The face does not match the document |
| FACE_IN_BLOCKLIST | Face in a blocklist |
| UNMAPPED | A reason the catalog does not cover yet |
Attempts
Every result that does not approve — a declined selfie, or a verification that could not be completed — uses one attempt of the verification. Migo sets the limit per merchant; the default is 3, and the budget is per verification.
Each call to step 1 opens a new verification, and a declined document closes it. What gets retried on the same verification is step 2.
When the attempts run out, one of two things happens, depending on the merchant's configuration:
| Configuration | What happens |
|---|---|
| Without review | Step 2 responds 403 with 8120, and from then on step 2 and the sign-up also respond 8120. Offer support instead of another retry |
| With review | Step 2 responds 200 with status MANUAL_REVIEW: the verification waits for a person's decision and its expiresAt is extended. The sign-up responds 403 with 8120 until that review approves it. Read the status until it becomes APPROVED or DECLINED |
Reading the status is not cut off by the attempts: it always returns the latest status.
Errors
| Code | HTTP | When |
|---|---|---|
| 7000 | 400 | Invalid parameters: malformed verificationId, Idempotency-Key, consent, or type when linking a verification |
| 7102 | 404 | When linking a verification, the user has no document of that type |
| 7121 | 409 | The lead for that document already completed its registration |
| 7144 | 403 | When linking a verification, the session belongs to another user |
| 7615 | 403 | The client behind the token lacks the permission for the route |
| 8110 | 403 | The flow is not enabled for the merchant |
| 8111 | 403 | The merchant has no valid verification configuration, or does not have the SDK mode enabled |
| 8112 | 422 | Invalid, missing or larger than 5 MB image, a malformed verificationId in step 2, or the verification could not be completed. It is not a declined document: that is 200 with status DECLINED |
| 8113 | 503 | The verification service did not respond |
| 8114 | 409 | The verification is not in the state the step needs, for example a selfie on an already declined verification |
| 8115 | 404 | The verificationId does not exist |
| 8116 | 410 | The verification expired; start again |
| 8117 | 409 | The verification already created its lead with another Idempotency-Key, or another creation is in progress |
| 8118 | 404 | The verification belongs to another merchant |
| 8119 | 422 | nit is missing, or an identity field does not match the verified document |
| 8120 | 403 | The verification ran out of attempts |
| 8121 | 422 | When registering with verificationId, the verification is for a different document than the lead's |
A verification from another merchant returns 404, not 403: the platform does not confirm the existence of other merchants' resources.
Related
- SDK Install — what comes after the sign-up
- API Reference — full request and response schemas