UUIDs and integer IDs in APIs

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.

The rule of thumb

Think of the UUID as the address on the envelope. The integer is the row number in the filing cabinet.

Merchants

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)

Public merchant API

GET /api/merchants/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response 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 portal URLs

Admin routes use the same UUID in the browser:

https://admin.example.com/merchants/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Team management APIs follow the same pattern:

GET  /api/admin/merchants/{merchantUuid}/team
POST /api/admin/merchants/{merchantUuid}/team

Payment workflows

When 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-ef1234567890

Customers

End-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}/activity

What stays numeric

These are commonly still integers by design:

Merchant team endpoints often use UUID for the merchant and integer for the user:

POST /api/admin/merchants/{merchantUuid}/team/{userId}/resend-invite

Integration tips

1. List merchants and copy merchant_uuid from the JSON — do not assume sequential integers like 1, 2, 3.

2. Treat UUIDs as opaque strings; validate format (uuid) but do not parse meaning from them.

3. OpenAPI specs usually mark UUID path params with format: uuid.

Summary

• 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.