
@tosinolugbenga
UUIDs and integer IDs
Many platforms use two kinds of identifiers on purpose. Public surfaces use UUIDs so resources are hard to guess. Inside the database, integer keys stay for fast joins and legacy compatibility.
This guide explains which one to use when you build dashboards, integrations, or admin workflows.
Use this | When |
|---|---|
UUID ( | URLs, shareable links, public |
Integer ( | Staff accounts, agents, payment cases, audit rows, and anything already keyed by legacy numeric IDs |
Think of the UUID as the address on the envelope. The integer is the row number in the filing cabinet.
Every merchant (tenant on the platform) typically has:
merchant_uuid — exposed in API responses and used in routes
internal numeric id — used only inside the database (often omitted from public payloads)
GET /api/merchants/a1b2c3d4-e5f6-7890-abcd-ef1234567890Response includes merchant_uuid, not a numeric merchant id.
{
"merchant_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Acme Payments Ltd",
"city": "London",
"country": "GB"
}Do not call /api/merchants/1 — numeric paths should be rejected (400). Use the UUID from list, search, or onboarding responses.
Admin routes use the same UUID in the browser:
https://admin.example.com/merchants/a1b2c3d4-e5f6-7890-abcd-ef1234567890Team management APIs follow the same pattern:
GET /api/admin/merchants/{merchantUuid}/team
POST /api/admin/merchants/{merchantUuid}/teamWhen creating or updating a case (e.g. onboarding, dispute, payout review), pass the merchant UUID in the body:
{
"merchant_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}Filter lists with the same field:
GET /api/cases?merchant_uuid=a1b2c3d4-e5f6-7890-abcd-ef1234567890End-customers often expose:
customer_uuid — preferred for customer portals and account APIs
customer_reference — human-readable support/search reference (e.g. CUS-10482)
internal numeric id — only for privileged ops or compliance roles
Customer-facing session responses may emphasize UUID + reference and hide the internal id where policy requires it.
GET /api/accounts/{customer_uuid}/activityThese are commonly still integers by design:
Resource | Example field | Typical use |
|---|---|---|
Portal user |
| Login, team invites, impersonation |
Agent |
| Assignments, queues, performance views |
Payment case | case | Case detail, escrow, status transitions |
Merchant team |
| Resend invite, update team member |
Merchant team endpoints often use UUID for the merchant and integer for the user:
POST /api/admin/merchants/{merchantUuid}/team/{userId}/resend-inviteList merchants and copy merchant_uuid from the JSON — do not assume sequential integers like 1, 2, 3.
Treat UUIDs as opaque strings; validate format (uuid) but do not parse meaning from them.
OpenAPI specs usually mark UUID path params with format: uuid.
UUID = safe, stable, public identifier for merchants and customers.
Integer = internal and legacy identifiers for users, agents, and cases.
Merchant routes and admin URLs should use UUID; numeric merchant paths are intentionally blocked.
When in doubt, use the UUID in anything a user could bookmark, share, or scrape from a URL bar.
Other articles you might enjoy