Leads

A lead is the very first prospect in onboarding — someone who wants to start using Migo products. Creating a lead doesn't grant any capabilities on its own; it captures the person and their business so the rest of the onboarding chain can run.

During this onboarding, a lead signs up for the Migo product set:

• Physical cards — the cardholder program tied to the merchant.

• The Wallet app — the end-user wallet experience.

• Alternative payments inside the wallet — additional in-wallet payment rails, declared through paymentMethods and sdk.

• Base URL: https://api.ali.app/rest

• Auth: Authorization: Bearer <token> (merchant token)

Create a lead

POST /leads

curl -X POST https://api.ali.app/rest/leads \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "gender": "F",
    "cui": "XXXXXXXXX",
    "expirationDate": "2030-12-31",
    "commercialName": "Example Store",
    "partner": "your-partner-slug",
    "phone": "00000000",
    "address": "Example Avenue 12-34, Zone 1",
    "businessName": "Example Store",
    "nationality": "GTM",
    "countryOfBirth": "GTM",
    "country": "GTM",
    "dateOfBirth": "1990-01-15",
    "placeOfBirth": "Example City",
    "neighborhood": "Example District",
    "maritalStatus": "soltero",
    "economicActivity": "Retail sales",
    "canInvoice": true,
    "taxRegime": "general",
    "nit": "XXXXXXXXX",
    "rtuType": "standard",
    "email": "jane@example.com",
    "paymentMethods": [
      { "slug": "akisiQR", "acquirerSlug": "akisi" },
      { "slug": "td/tc", "acquirerSlug": "neonet" }
    ],
    "sdk": "MIGO_LINK_USD"
  }'

An optional x-merchant-id header can be sent to associate the lead with a specific merchant.

Request body

Field	Type	Required	Notes
firstName	string	✅
lastName	string	✅
gender	enum	✅	One of F, M, OTHER
cui	string	✅	Personal identification number
expirationDate	string	✅	Document expiration, YYYY-MM-DD
commercialName	string	✅	Trade name
partner	enum	✅	Partner the lead is associated with
phone	string	✅	International format
address	string	✅	Physical address
nationality	enum (country)	—	Accepts alpha-2 or alpha-3, normalized to alpha-3. Defaults to GTM
countryOfBirth	enum (country)	—	Accepts alpha-2 or alpha-3, normalized to alpha-3
country	enum (country)	—	Accepts alpha-2 or alpha-3, normalized to alpha-3
dateOfBirth	string	—	YYYY-MM-DD
placeOfBirth	string	—
neighborhood	string	—
maritalStatus	enum	—	One of soltero, casado, viudo, divorciado, separado
serialNumber	string	—
taxRegime	enum	—	Defaults to NA (none)
nit	string	—	Tax identification number
businessName	string	—	Legal name; defaults to commercialName if omitted
economicActivity	string	—
canInvoice	boolean	—	Defaults to false
rtuType	string	—
lastRtuUpdateDate	string	conditional	YYYY-MM-DD. Required only when partner is the Tributax partner
location	object	—	{ region?, administrativeAreaLevel1?, administrativeAreaLevel2? }
email	string	—	Valid email address
clientId	string	—
sdk	string	—	Wallet SDK profile the lead signs up for (see below)
paymentMethods	array	—	Alternative payment methods enabled in the wallet (see below)
documents	array	—	{ url, type?, provider? } supporting documents
currencies	number[]	—

Any field not listed above is rejected by validation.

Products: paymentMethods and sdk

These two fields declare which Migo products the lead is onboarding into:

• paymentMethods enables the alternative payments offered inside the wallet. Each item is an object describing the method and its acquirer:

  { "slug": "akisiQR", "acquirerSlug": "akisi" }

  • slug — the payment method (for example a QR rail or a card rail).
  • acquirerSlug — the acquirer that processes that method.

  Send one item per method you want enabled in the wallet.

• sdk selects the Wallet app SDK profile the lead signs up for (for example MIGO_LINK_USD). It drives which wallet experience and currency the prospect is provisioned with.

The physical cards product is part of the same onboarding and is provisioned for the lead once it is promoted into a business and a cardholder is registered — see What's next.

Country normalization

nationality, countryOfBirth, and country accept ISO 3166 alpha-2 or alpha-3 on input and are normalized to alpha-3 before the lead is stored (GT → GTM). All subsequent responses return alpha-3.

Response

The created lead is returned with its invitationCode — use it directly to register the owner (no separate code-generation step):

{
  "success": true,
  "data": {
    "_id": "...",
    "invitationCode": "25DC4D1"
  }
}

On failure, success is false and errors carries { message, code } entries. You can also resolve a lead later with the get-by-code call below.

Get a lead by invitation code

GET /leads/{code}

Resolves the lead linked to a public invitation code. Used during onboarding to rehydrate everything captured for the prospect.

curl https://api.ali.app/rest/leads/25DC4D1 \
  -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "_id": "...",
    "invitationCode": "25DC4D1",
    "firstName": "Jane",
    "lastName": "Doe",
    "nationality": "GTM",
    "gender": "F",
    "dateOfBirth": "1990-01-15",
    "countryOfBirth": "GTM",
    "placeOfBirth": "Example City",
    "neighborhood": "Example District",
    "maritalStatus": "soltero",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "cui": "XXXXXXXXX",
    "expirationDate": "2030-12-31",
    "commercialName": "Example Store",
    "businessName": "Example Store",
    "phone": "00000000",
    "address": "Example Avenue 12-34, Zone 1",
    "taxRegime": "general",
    "canInvoice": true,
    "hasRegime": true,
    "partner": "your-partner-slug",
    "nit": "XXXXXXXXX",
    "clientId": "",
    "country": "GTM",
    "sdk": "MIGO_LINK_USD",
    "paymentMethods": [
      { "slug": "akisiQR", "acquirerSlug": "akisi" },
      { "slug": "td/tc", "acquirerSlug": "neonet" }
    ],
    "payoutAccountNumber": null
  }
}

The data object merges the lead's personal fields with the onboarding fields of its first business (commercial/business name, phone, address, tax data, partner, nit, country, sdk, and paymentMethods). When no lead matches the code, data is undefined.

Lead documents

Files captured for a lead are read back through POST /leads/files/upload/{fileName}, where {fileName} is the stored file name. This is part of the lead/business document flow — see Lead & Business Files for the full file lifecycle.

What's next

The lead is the entry point of the onboarding chain:

1. Create the lead (this page) — capture the prospect and the products they sign up for.
2. Branch invitation — a branch is provisioned with an invitation code, resolved through GET /leads/{code}; see Terminals for terminal/branch onboarding.
3. User registration — the prospect becomes a wallet user and cardholder; see Cardholder Management.

Errors

Code	Name	Meaning
7105	ERROR_CREATE_LEAD	The lead could not be created
7121	LEAD_ALREADY_REGISTERED	The lead has already been registered
7130	LEAD_NOT_FOUND	Unknown invitation code