Cardholder Management
A cardholder is a user who owns a Migo card. This page is the canonical reference for registering and managing cardholders on the Wallet Gateway.
- Register a cardholder β create the user (
POST /users). - Find a cardholder by document β retrieve their account and userId from the DPI (GET /users/by-document).
- Update a cardholder's data β keep their personal data in sync (PATCH /users/{userId}/personal-data).
- Manage a cardholder β find, profile, roles, states, and step-up verification.
All endpoints require a valid JWT (Authorization: Bearer <token>).
Register a cardholderβ
POST /users registers a new cardholder with their personal information. It requires the USER_REGISTRATION application permission.
Only the Authorization header is required.
curl -X POST https://api.ali.app/rest/users \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Example",
"lastName": "User",
"address": "Example address",
"countryOfBirth": "GTM",
"placeOfBirth": "Example City",
"gender": "M",
"maritalStatus": "soltero",
"phoneNumber": "+50200000000",
"username": "user@example.com",
"dateOfBirth": "1990-01-01",
"termsAndConditionsAccepted": true,
"identificationDocuments": [
{ "documentNumber": "XXXXXXXXXXXXX", "documentType": "DPI" }
]
}'
| Field | Type | Required | Notes |
|---|---|---|---|
firstName | string | yes | First name |
lastName | string | yes | Last name |
address | string | yes | Residential address |
countryOfBirth | Country enum | yes | ISO alpha-3 code (e.g. GTM). Alpha-2 input is normalized to alpha-3 by the gateway |
placeOfBirth | string | yes | Free text |
gender | Gender enum | yes | M, F or OTHER |
phoneNumber | string | yes | Phone number in international format |
dateOfBirth | string | yes | YYYY-MM-DD |
identificationDocuments | array | yes | Array of { documentNumber, documentType } (both strings, e.g. documentType: "DPI") |
username | string (email) | no | Email address used as the username |
maritalStatus | MaritalStatus enum | no | soltero, casado, viudo, divorciado or separado |
neighborhood | string | no | Neighborhood or district |
termsAndConditionsAccepted | boolean | no | Whether terms and conditions were accepted |
additionalData | object | no | Additional user metadata |
There is no top-level email / documentId / birthDate β the email is username, and identity documents live in identificationDocuments.
Responseβ
Returns the standard response envelope; on success the created user is returned under data:
{ "success": true, "data": { } }
On error, success is false and errors carries the detail. The envelope fields are success (boolean), optional message, optional data, and optional errors (array of { message, code }).
Manage a cardholderβ
Find a cardholderβ
GET /users retrieves a single user filtered by either id (numeric) or username (email) β at least one is required:
curl "https://api.ali.app/rest/users?username=user@example.com" \
-H "Authorization: Bearer <token>" \
-H "x-application-id: YOUR_APP_ID"
Find a cardholder by documentβ
GET /users/by-document returns the account a cardholder already has in your application, looked up by their identification document. The response includes the userId accepted by the /users/{userId}/... routes (cards, profile). Use it to link an existing user on your side βfor example, before assigning them a cardβ instead of registering them again.
Requires the findByDocument application permission (resource users). Only the Authorization header is sent; no user token is needed.
curl "https://api.ali.app/rest/users/by-document?documentNumber=XXXXXXXXXXXXX&documentType=DPI" \
-H "Authorization: Bearer <token>"
| Query parameter | Type | Required | Notes |
|---|---|---|---|
| documentNumber | string | yes | Document number, 1 to 50 characters |
| documentType | enum DocumentType | no | DPI (default), NIT, PASSPORT, LEGAL_ID, PERSONAL_ID or RESIDENCE_ID |
The document number travels in the URL: avoid storing the full URL in your own logs.
Responseβ
{
"success": true,
"message": "User found",
"data": {
"userId": 123,
"firstName": "Example",
"lastName": "User",
"address": "Example address",
"countryOfBirth": "GTM",
"placeOfBirth": "Example City",
"gender": "M",
"maritalStatus": "soltero",
"neighborhood": "Example neighborhood",
"phoneNumber": "+50200000000",
"username": "user@example.com",
"dateOfBirth": "1990-01-01",
"identificationDocuments": [
{ "documentNumber": "XXXXXXXXXXXXX", "documentType": "DPI" }
],
"termsAndConditionsAccepted": true
}
}
The fields are the same ones you send when registering a cardholder, plus userId:
- userId is the identifier taken by the /users/{userId}/... routes.
- countryOfBirth is returned as ISO alpha-3 and maritalStatus in Spanish, as on registration.
- Optional fields the cardholder does not have come back as null.
- additionalData is not returned.
Only your application's cardholdersβ
The lookup is limited to the token's application. A document registered only under another application answers 404, the same as one that does not exist. A merchant in the query is ignored.
Errorsβ
| HTTP | Code | When | What to do |
|---|---|---|---|
| 400 | 7000 | documentNumber is missing or documentType is invalid | Fix the parameters |
| 401 | 7606 | Missing or invalid token | Get a new token |
| 403 | 7615 | The application lacks the findByDocument permission | Request it from Migo |
| 404 | 7100 | No cardholder of your application holds that document | Register the cardholder with POST /users |
| 409 | 7186 | More than one cardholder of your application holds that document | Contact support; neither one is picked |
| 500 | 7106 | Lookup error | Retry; if it persists, contact support |
Update a cardholder's dataβ
PATCH /users/{userId}/personal-data updates the personal data of a cardholder of your application. Use it to keep Migo in sync when the cardholder changes their data on your platform. The userId is the one returned by Find a cardholder by document.
It requires the application permission updateUserByIntegrator (resource users). Only the Authorization header is sent; no user token is needed.
curl -X PATCH "https://api.ali.app/rest/users/123/personal-data" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "address": "Example address 2", "neighborhood": "Example neighborhood 2" }'
| Field (body) | Type | Notes |
|---|---|---|
| firstName | string | 1 to 100 characters |
| lastName | string | 1 to 100 characters |
| birthdate | string (ISO 8601 date) | Cannot be in the future |
| maritalStatus | string | single, married, divorced, widowed or separated; Spanish is accepted too (soltero/a, casado/a, divorciado/a, viudo/a, separado/a) |
| gender | enum | F, M or OTHER |
| address | string | 1 to 255 characters |
| neighborhood | string | 1 to 100 characters |
| placeBirth | string | 1 to 100 characters |
| phoneNumber | string | Digits only, 7 to 15, no + or spaces. Requires phoneVerification. See Change the phone number |
| phoneVerification | object | Required with phoneNumber, and only accepted with it: verifiedAt (ISO 8601 date-time) and reference (1 to 100 characters) |
Every field is optional, but at least one must be sent:
- Only the fields you send are evaluated, and only the ones that change are saved.
- A field can be replaced but not cleared: null or an empty string is rejected.
- Any other field in the body rejects the whole request with 400, and nothing is saved. Email and document number are not updated through this route.
- Personal data belongs to the person, not to the application: if the cardholder also has an account in another Migo application, the change shows there too.
Change the phone numberβ
The phone number is the channel where the cardholder receives Migo's verification codes (OTP), for example to recover their password. That is why changing it has its own rules:
- You verify the new number. Before calling this route, send your own OTP to the new number and confirm the cardholder received it. Sending it, and its cost, are on your side. In phoneVerification you state when it was verified (verifiedAt) and the identifier of that verification in your system (reference); Migo keeps both in its audit trail.
- The verification must be recent: within the last hour and not in the future. Otherwise the request is rejected with 400.
- How to recognize an expired verification: the 400 comes with code 7000 and the generic message Check the parameters provided., without the field name. The same happens when the number is not valid for the cardholder's country. If the body has the right shape and you still get that error, check that verifiedAt is within the last hour and includes the time zone (for example, ending in Z for UTC), and that the number has the right length for the country.
- The number must be valid for the cardholder's country.
- Only for cardholders exclusive to your application. If the cardholder also has an account in another Migo application, the phone number is not changed and the response is 409: the number belongs to the person, and changing it would affect the codes they receive in those other applications.
- Migo notifies the cardholder by email that their number changed, showing the new number masked.
- The phone number is not returned in the response; updatedFields tells you whether it changed.
curl -X PATCH "https://api.ali.app/rest/users/123/personal-data" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "50212345678",
"phoneVerification": { "verifiedAt": "2026-11-03T15:04:05Z", "reference": "otp-7f3a2c" }
}'
Responseβ
{
"success": true,
"message": "User data updated successfully",
"data": {
"userId": 123,
"updatedFields": ["address", "neighborhood"],
"firstName": "Example",
"lastName": "User",
"birthdate": "1990-01-01T00:00:00.000Z",
"maritalStatus": "single",
"gender": "M",
"address": "Example address 2",
"neighborhood": "Example neighborhood 2",
"placeBirth": "Example City"
}
}
- updatedFields lists the fields that changed. When everything you sent was already stored, it is empty and the message is User data is already up to date.
- The rest of data holds the current values after the update; maritalStatus comes back in English (single, married, ...).
Errorsβ
| HTTP | Code | When | What to do |
|---|---|---|---|
| 400 | 7000 | No field was sent, a field is not allowed, empty or invalid, birthdate is in the future, or phoneNumber comes without a recent verification or is not valid for the cardholder's country | Fix the body; for the phone number, verify the number again |
| 400 | 7127 | The userId is an administrative account, which holds no personal data | Use the cardholder's userId |
| 401 | 7602 / 7606 | Missing or invalid token | Get a new token |
| 403 | 7615 | The application lacks the updateUserByIntegrator permission | Request it from Migo |
| 404 | 7100 | The userId does not exist or is not a cardholder of your application | Check the userId with Find a cardholder by document |
| 409 | 7189 | phoneNumber was sent and the cardholder also has an account in another Migo application | The phone number cannot be changed through this route; the cardholder must contact support |
| 500 | 7169 | Save error | Retry; if it persists, contact support |
Account statesβ
The auth_user.status values are:
| State | Meaning |
|---|---|
Pending | Account created, not yet activated |
Active | Fully onboarded |
Inactive | Deactivated |
Blocked | Disabled (fraud, KYC issue, customer request) |
PasswordResetRequired | Must reset password before continuing |
There is no profile-update PATCH endpoint; card status changes go through the card block/unblock endpoints (see Card Lifecycle).
Verify a passwordβ
POST /users/{userId}/auth validates a password against the user's credentials β used for step-up confirmation before sensitive actions:
curl -X POST "https://api.ali.app/rest/users/{userId}/auth" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "password": "<password>" }'
Profile imageβ
PUT /users/{userId}/profile-image accepts a multipart/form-data upload with the field profileImage (max 5 MB; png, jpeg, jpg):
curl -X PUT "https://api.ali.app/rest/users/{userId}/profile-image" \
-H "Authorization: Bearer <token>" \
-F "profileImage=@avatar.jpg"
Push notification tokensβ
Register and remove the cardholder's FCM (Firebase Cloud Messaging) token so the platform can deliver push notifications:
# Register
curl -X POST "https://api.ali.app/rest/users/fcm-tokens" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "token": "fcm-token-abc123xyz" }'
# Remove (on logout / token rotation) β returns 204 No Content
curl -X DELETE "https://api.ali.app/rest/users/fcm-tokens/{token}" \
-H "Authorization: Bearer <token>"
Rolesβ
List the available roles and add/remove roles for a user:
# List roles
curl https://api.ali.app/rest/users/roles \
-H "Authorization: Bearer <token>"
# Add / remove roles for a user
curl -X PATCH https://api.ali.app/rest/users/{id}/roles \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "addRoles": ["SHOP_ADMIN"], "removeRoles": [] }'