Skip to main content
Migo Docs

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:

ModeWho captures the photosWhen to use it
Migo verification SDK (recommended)The SDK, with its own guided capture experienceMobile and web apps. Better approval rate, and you do not build the capture yourself
Image-based verificationYour app, which uploads the document and selfie photosWhen 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.

Availability

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​

StepEndpointWhat it does
1POST /onboarding/sessionsOpens the verification and returns the session token for the SDK
2(in your app)The person completes the verification inside the SDK
3GET /onboarding/verifications/{verificationId}You read the result until it is no longer PENDING; it carries the data and the photos
4POST /leads with the verificationId headerCreates the lead and the business, and returns the invitation code
5Registration and POST /users/loginThe login tells you whether the identity is under review
SDK availability

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" }]
}
}
statusWhat to do
PENDINGThe result has not arrived yet. Read it again in a few seconds
OCR_APPROVEDThe document is already approved and the rest of the verification is still pending. Keep reading it as with PENDING
APPROVEDShow the fields so the person confirms their data, and move on to step 4
MANUAL_REVIEWThe 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
DECLINEDThe 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
CONSUMINGThe lead is being created right now. Read it again in a few seconds
CONSUMEDThe 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>"
}
}
}
KeyWhat it is
documentFrontFront of the document
documentBackBack of the document
documentPortraitThe person's photo cropped from the document
selfieThe face captured in the liveness check
expiresAtValidity 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 session expires

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
}
}
manualReviewWhen
trueThe person registered with the identity under review, and the review is still open or ended declined
falseThe 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:

  1. Open the session with expectedDocumentNumber set to the lead's document.
  2. 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:

ResponseWhen
400 with 7000The verificationId is not a UUID or type is missing
403 with 7144The session belongs to another user
404 with 8115 or 8118The verification does not exist, or belongs to another merchant
404 with 7102The user has no document of that type
409 with 8114The verification is not approved, for example because it is still under review
422 with 8119The verification is for another document

Image-Based Verification​

StepEndpointWhat it does
1POST /onboarding/ocrExtracts the document data and opens the verification
2POST /onboarding/livenessLiveness check on a selfie (and, when the merchant asks for it, a match against the document portrait)
3POST /leads with the verificationId headerCreates 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:

PermissionWhat for
onboarding:ocrOpening the SDK session, reading the result and, in image-based verification, the document step
onboarding:livenessThe liveness check of image-based verification
leads:createCreating the lead, same as in the regular sign-up
The merchant comes from the token

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:

statusWhat to do
OCR_APPROVEDContinue to step 2 with that verificationId
DECLINEDThe 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:

sourceMeaning
OCRRead from the document: prefill it in the form
MANUALNot on the document: ask the person for it
DERIVEDValue 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 happenedResponseWhat to do
The selfie was evaluated and declined200 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 completed422 with 8112 or 503 with 8113The 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"
}'
WhatRuleOtherwise
BodyThe same validations as the regular sign-up400
verificationIdThe verification from step 1, approved in step 2400 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-KeyRequired, up to 255 characters400 with 7000
consentVersion and consentAcceptedAtThe 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 accepted400 with 7000
Identity data: cui, firstName, lastName, dateOfBirth, expirationDate, nationality, countryOfBirth, placeOfBirth, gender, maritalStatusMust match the verified document, except the fields the merchant allows editing. Send them as step 1 returned them422 with 8119
nitRequired in a verified sign-up422 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.

The Idempotency-Key is required

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.

CodeWhat happened
DOCUMENT_EXPIREDThe document has expired
DOCUMENT_NOT_RECOGNIZEDThe document could not be validated
DOCUMENT_TYPE_NOT_SUPPORTEDDocument type not supported
DOCUMENT_TAMPEREDTampering detected
DOCUMENT_PORTRAIT_MISSINGThe document has no portrait
DOCUMENT_IN_BLOCKLISTDocument in a blocklist
PUBLIC_DOCUMENT_IMAGEKnown public image from the internet
DOCUMENT_DATA_UNREADABLEThe data could not be read
DOCUMENT_DATA_MISMATCHThe data is inconsistent or does not match what was declared
DOCUMENT_NUMBER_MISMATCHThe document is not the expected one. Only with expectedDocumentNumber and document matching enabled
IMAGE_TOO_BLURRYBlurry image
IMAGE_LOW_QUALITYImage too dark or too bright
SCREEN_CAPTURE_DETECTEDPhoto of a screen
PRINTED_COPY_DETECTEDPhotocopy
MINIMUM_AGE_NOT_MET, MAXIMUM_AGE_EXCEEDED, AGE_NOT_DETECTEDAge out of range or undeterminable
DUPLICATE_USERPossible duplicate user
NO_FACE_DETECTED, MULTIPLE_FACES_DETECTEDNo face, or more than one
LOW_LIVENESS_SCORE, LIVENESS_ATTACK_DETECTEDThe liveness check did not pass
FACE_QUALITY_TOO_LOWSelfie quality too low
FACE_MISMATCHThe face does not match the document
FACE_IN_BLOCKLISTFace in a blocklist
UNMAPPEDA 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:

ConfigurationWhat happens
Without reviewStep 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 reviewStep 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​

CodeHTTPWhen
7000400Invalid parameters: malformed verificationId, Idempotency-Key, consent, or type when linking a verification
7102404When linking a verification, the user has no document of that type
7121409The lead for that document already completed its registration
7144403When linking a verification, the session belongs to another user
7615403The client behind the token lacks the permission for the route
8110403The flow is not enabled for the merchant
8111403The merchant has no valid verification configuration, or does not have the SDK mode enabled
8112422Invalid, 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
8113503The verification service did not respond
8114409The verification is not in the state the step needs, for example a selfie on an already declined verification
8115404The verificationId does not exist
8116410The verification expired; start again
8117409The verification already created its lead with another Idempotency-Key, or another creation is in progress
8118404The verification belongs to another merchant
8119422nit is missing, or an identity field does not match the verified document
8120403The verification ran out of attempts
8121422When 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.