​
Overview

Every resource in the OpenFX v1 API has a globally unique, typed identifier. Resource IDs are designed for instant recognition — you can tell what kind of resource an ID refers to just by looking at the prefix. 
pmt_01953e1a5f4b7005
^^^                    prefix — identifies the resource type (Payment)
   ^^^^^^^^^^^^^^^^^^  suffix — UUIDv7 (time-ordered, globally unique)

​
Format

All resource IDs follow the pattern: 
{prefix}{uuidv7_hex}
  • Prefix: A short, lowercase string ending with an underscore (_) that identifies the resource type.
  • Suffix: A UUIDv7 value encoded as a lowercase hexadecimal string (no dashes).
UUIDv7 embeds a millisecond-precision timestamp, which means IDs are chronologically sortable. Resources created later always have lexicographically greater IDs. This is what powers cursor-based pagination.

​
Prefix Reference

Every resource type has a unique prefix. Use this table to identify any ID you encounter in API responses, webhook payloads, or logs.
PrefixResourceExample
ent_Entityent_01953e1a5f4b7100
erel_Entity Relationshiperel_01953e1a5f4b7101
doc_Documentdoc_01953e1a5f4b7102
cus_Customercus_01953e1a5f4b7000
onb_Onboardingonb_01953e1a5f4b7800
acc_Accountacc_01953e1a5f4b7002
an_Account Numberan_01953e1a5f4b7200
ba_Blockchain Addressba_01953e1a5f4b7201
srt_Settlement Routesrt_01953e1a5f4b7900
cpt_Counterpartycpt_01953e1a5f4b7004
pm_Payment Methodpm_01953e1a5f4b7300
pmt_Paymentpmt_01953e1a5f4b7005
qte_FX Quoteqte_01953e1a5f4b7006
pqt_Payment Quotepqt_01953e1a5f4b7012
pte_Payment Estimatepte_01953e1a5f4b7400
cnv_Conversioncnv_01953e1a5f4b7007
trf_Transfertrf_01953e1a5f4b7008
rfd_Refundrfd_01953e1a5f4b7020
col_Collectioncol_01953e1a5f4b7a00
ipmt_Inbound Paymentipmt_01953e1a5f4b7500
txn_Transactiontxn_01953e1a5f4b7600
evt_Eventevt_01953e1a5f4b7009
wsub_Webhook Subscriptionwsub_01953e1a5f4b700a
whd_Webhook Deliverywhd_01953e1a5f4b7100
req_RFI / Requestreq_01953e1a5f4b7700

​
Validation Pattern

Each resource ID matches the regex pattern: 
^{prefix}[A-Za-z0-9]+$
For example, to validate a Payment ID: 
import re

PAYMENT_ID_PATTERN = re.compile(r"^pmt_[A-Za-z0-9]+$")

def is_valid_payment_id(id: str) -> bool:
    return bool(PAYMENT_ID_PATTERN.match(id))

# Examples
is_valid_payment_id("pmt_01953e1a5f4b7005")  # True
is_valid_payment_id("acc_01953e1a5f4b7002")  # False — wrong prefix
is_valid_payment_id("01953e1a5f4b7005")      # False — no prefix

​
Time Ordering

Because the suffix is a UUIDv7, IDs are monotonically increasing over time. This means:
  • Resources created later always have IDs that sort after earlier resources.
  • You can use ID comparison to determine relative creation order.
  • Cursor-based pagination relies on this ordering — starting_after and ending_before parameters accept resource IDs.
// These IDs are in creation order (earliest to latest):
"pmt_01953e1a5f4b7001"
"pmt_01953e1a5f4b7005"
"pmt_01953e1a5f4b7012"

​
Best Practices

Store IDs as strings. Resource IDs are always strings. Never cast them to integers or UUIDs — the prefix makes them non-standard UUID format.
Use IDs for log correlation. When logging API interactions, include the resource ID. The typed prefix makes it easy to search logs for all operations on a specific resource type (e.g., grep for pmt_ to find all payment-related log entries).
Use the prefix for quick debugging. If you see cpt_01953e1a5f4b7004 in a webhook payload, you immediately know it refers to a Counterparty without checking any documentation.
Do not parse the suffix. The internal format of the suffix (UUIDv7 hex encoding) is an implementation detail. Do not extract timestamps or other data from the suffix — use the createdAt field on the resource instead. The suffix format may change in future versions.
Do not construct IDs. Resource IDs are always server-generated. Never attempt to construct an ID by combining a prefix with a UUID — always use the ID returned by the API.

​
Cross-Resource References

Resources reference each other by ID. The prefix makes it clear what type of resource is being referenced: 
{
  "id": "pmt_01953e1a5f4b7005",
  "customerId": "cus_01953e1a5f4b7000",
  "sourceAccountId": "acc_01953e1a5f4b7002",
  "counterpartyId": "cpt_01953e1a5f4b7004",
  "paymentMethodId": "pm_01953e1a5f4b7300",
  "quoteId": "qte_01953e1a5f4b7006"
}
Every foreign-key field in the API follows this pattern. If you see a field ending in Id, its value will always carry the prefix of the referenced resource type.
  • Pagination — how resource IDs power cursor-based pagination
  • Error Handling — requestId in error responses uses the req_ prefix
  • API Reference — see typed IDs in every endpoint’s response schema