Skip to main content
Migo Docs

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.

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" }
]
}'
FieldTypeRequiredNotes
firstNamestringyesFirst name
lastNamestringyesLast name
addressstringyesResidential address
countryOfBirthCountry enumyesISO alpha-3 code (e.g. GTM). Alpha-2 input is normalized to alpha-3 by the gateway
placeOfBirthstringyesFree text
genderGender enumyesM, F or OTHER
phoneNumberstringyesPhone number in international format
dateOfBirthstringyesYYYY-MM-DD
identificationDocumentsarrayyesArray of { documentNumber, documentType } (both strings, e.g. documentType: "DPI")
usernamestring (email)noEmail address used as the username
maritalStatusMaritalStatus enumnosoltero, casado, viudo, divorciado or separado
neighborhoodstringnoNeighborhood or district
termsAndConditionsAcceptedbooleannoWhether terms and conditions were accepted
additionalDataobjectnoAdditional 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 parameterTypeRequiredNotes
documentNumberstringyesDocument number, 1 to 50 characters
documentTypeenum DocumentTypenoDPI (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​

HTTPCodeWhenWhat to do
4007000documentNumber is missing or documentType is invalidFix the parameters
4017606Missing or invalid tokenGet a new token
4037615The application lacks the findByDocument permissionRequest it from Migo
4047100No cardholder of your application holds that documentRegister the cardholder with POST /users
4097186More than one cardholder of your application holds that documentContact support; neither one is picked
5007106Lookup errorRetry; 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)TypeNotes
firstNamestring1 to 100 characters
lastNamestring1 to 100 characters
birthdatestring (ISO 8601 date)Cannot be in the future
maritalStatusstringsingle, married, divorced, widowed or separated; Spanish is accepted too (soltero/a, casado/a, divorciado/a, viudo/a, separado/a)
genderenumF, M or OTHER
addressstring1 to 255 characters
neighborhoodstring1 to 100 characters
placeBirthstring1 to 100 characters
phoneNumberstringDigits only, 7 to 15, no + or spaces. Requires phoneVerification. See Change the phone number
phoneVerificationobjectRequired 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​

HTTPCodeWhenWhat to do
4007000No 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 countryFix the body; for the phone number, verify the number again
4007127The userId is an administrative account, which holds no personal dataUse the cardholder's userId
4017602 / 7606Missing or invalid tokenGet a new token
4037615The application lacks the updateUserByIntegrator permissionRequest it from Migo
4047100The userId does not exist or is not a cardholder of your applicationCheck the userId with Find a cardholder by document
4097189phoneNumber was sent and the cardholder also has an account in another Migo applicationThe phone number cannot be changed through this route; the cardholder must contact support
5007169Save errorRetry; if it persists, contact support

Account states​

The auth_user.status values are:

StateMeaning
PendingAccount created, not yet activated
ActiveFully onboarded
InactiveDeactivated
BlockedDisabled (fraud, KYC issue, customer request)
PasswordResetRequiredMust 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": [] }'