Accounts

There is no separate "accounts" service in the API — every endpoint below operates on the current authenticated user, identified by the Bearer token. Lumeo does not currently support organization or team accounts; each user has exactly one profile, one KYC record, and any number of linked wallets.

If you're integrating on behalf of multiple users (e.g. a platform building on top of Lumeo), each of your end users needs their own API session and their own profile — there is no shared org-level account to attach them to.

Profile

Get profile

GET /api/v1/profile

Returns the current user's profile summary.

curl https://api.lumeo.co.in/api/v1/profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const res = await fetch("https://api.lumeo.co.in/api/v1/profile", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { profile } = await res.json();

Response — 200 OK

{
  "success": true,
  "profile": {
    "id": "user_01j4abc",
    "email": "[email protected]",
    "name": "Aditi Rao",
    "phone": "+919876543210",
    "createdAt": "2026-01-14T10:02:11.000Z"
  }
}

Returns 404 with code ERR_PROFILE_NOT_FOUND if the user has never completed profile setup.

Get full profile (with vaults)

GET /api/v1/profile/full

Same as above, plus the user's vaults (funding wallets used for payouts — see Create Payout).

This endpoint returns raw database field names (display_name, full_name, created_at) rather than the camelCase shape used by GET /profile. Don't assume the two responses are interchangeable.

{
  "success": true,
  "profile": {
    "id": "user_01j4abc",
    "email": "[email protected]",
    "display_name": "Aditi",
    "full_name": "Aditi Rao",
    "phone": "+919876543210",
    "created_at": "2026-01-14T10:02:11.000Z",
    "vaults": [
      {
        "id": "vault_01j4xyz",
        "name": "Primary",
        "vault_type": "SETTLEMENT",
        "balance": "184200.50",
        "currency": "INR",
        "created_at": "2026-01-14T10:03:02.000Z"
      }
    ]
  }
}

Update profile

PATCH /api/v1/profile

All fields are optional — send only what you're changing.

Field	Type	Notes
`name`	`string`	Max 100 characters.
`email`	`string`	Must be a valid email, max 254 characters.
`phone`	`string`	Max 30 characters.
`countryCode`	`string`	Exactly 2 characters (ISO 3166-1 alpha-2).
`homeCurrency`	`string`	Exactly 3 characters (ISO 4217).

curl -X PATCH https://api.lumeo.co.in/api/v1/profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Aditi Rao", "homeCurrency": "INR" }'

Unlike GET /profile, the response here is the raw updated record — it is not wrapped in { success, profile }.

Wallet

Get linked wallet address

GET /api/v1/profile/wallet

Returns the wallet address linked to the profile, or 404 if none is linked yet.

{
  "walletAddress": "GADQVQHX...REDACTED...56CHARS",
  "provider": "lumenVault"
}

Link a wallet

PATCH /api/v1/profile/link-wallet

Field	Type	Required	Notes
`walletAddress`	`string`	Yes	—
`provider`	`string`	No	Defaults to `"lumenVault"`.

Returns { "success": true } on success.

KYC status

GET /api/v1/kyc/status

{
  "userId": "user_01j4abc",
  "status": "APPROVED",
  "allowedTransitions": []
}

status is one of PENDING, IN_PROGRESS, DOCS_SUBMITTED, UNDER_REVIEW, APPROVED, REJECTED. allowedTransitions lists which states the account can move to next — useful for deciding whether to show a "Start verification" or "Resubmit documents" prompt in your UI.

KYC must reach APPROVED before cross-border payouts are allowed. Check this status before calling POST /payments/initiate for a new user rather than relying on the initiate call to fail.

Start KYC

POST /api/v1/kyc/start

No request body. Moves the user into IN_PROGRESS and returns a redirect URL to the hosted verification flow.

{
  "success": true,
  "sessionId": "user_01j4abc",
  "status": "IN_PROGRESS",
  "redirectUrl": "https://verify.didit.me/session/...",
  "message": "Verification session created"
}

If the user is already APPROVED, this returns { "success": false, "status": "APPROVED", ... } instead of erroring.

Wallets (linked accounts)

GET /api/v1/wallets

Lists all wallets linked to the current user (a user can have more than one — e.g. separate vaults for INR settlement and USD holding).

GET /api/v1/wallets/summary

Returns an aggregate view — total balance across all linked wallets, useful for a dashboard summary rather than iterating the full list.

GET /api/v1/wallets/:id

Fetch a single wallet by its ID.

Next steps

Payments — create and track payouts against a linked wallet.
The ledger model — how wallet balances relate to the underlying ledger.

On this page