Upsert user
Look up an Uptop user by `email` and create it if it doesn't exist. A Market Money wallet is provisioned automatically on creation. Cache the returned `id` — it's the only key the rest of the API takes.
/v1/users:upsertRequest body
| Field | Type | Required | Description |
|---|---|---|---|
| string (email) | required | Primary identifier. Upsert is idempotent on this. | |
| phoneNumber | string (E.164) | — | User's phone number in E.164 format, e.g. `+12125550123`. Optional. The wallet provider checks that it is a real, reachable number and that no other customer already uses it, so send each customer's own number rather than a placeholder. Kept in sync — re-upsert with a new value to update it. |
| externalUserId | string | — | Your partner-side identifier for this user. Optional. When supplied it's linked to the matched/created record so subsequent partner lookups by it work too. |
| firstName | string | — | User's first name. Kept in sync on every upsert. |
| lastName | string | — | User's last name. Kept in sync on every upsert. |
{
"email": "customer@example.com",
"externalUserId": "partner-user-001",
"firstName": "Taylor",
"lastName": "Reyes"
}Response — 200
{
"id": "65f3a91d6f3a4b0012ab34cd",
"email": "customer@example.com",
"externalUserId": "partner-user-001",
"firstName": "Taylor",
"lastName": "Reyes",
"createdAt": "2026-05-22T15:00:00.000Z"
}Errors
- UNAUTHORIZED— Missing or invalid `Api-Key`.
- VALIDATION_ERROR— `email` missing or malformed, or `phoneNumber` supplied but not valid E.164. Also returned, with the provider's reason as the message, when the wallet provider rejects the phone number.
Notes
- **No formal KYC is performed.** Uptop does not run identity verification or background checks on this information. Wallets are capped at $1,000, which falls below the threshold that would require KYC.
Try it (curl)
$UPTOP_API_KEY in the curl will be substituted for it on send.Edit anything above, then send through the local proxy.