Skip to main content
All Natural API resources use prefixed IDs. These combine a type prefix with a UUID, making IDs both human-readable and type-safe.

​
Format

{prefix}_{uuid_hex}
Example: pty_019cd34e27bf78399b4e75b327d2ab25
  • Prefix: 2-4 character type indicator (e.g., pty_ for party)
  • UUID: 32 hexadecimal characters (no hyphens)

​
ID types

PrefixResourceDescription
pty_PartyBusiness or individual entity on the platform
usr_UserPerson who logs into a party
agt_AgentAPI client that acts on behalf of a party
dlg_DelegationPermission grant between two parties
adl_Agent DelegationLinks an agent to a delegation
din_Delegation InvitationPending invitation to create a delegation
dlk_Delegation LinkShareable URL to accept a delegation
mbr_Party MembershipA user’s membership in a party
ses_SessionAuthenticated user session
apy_API KeyCredential for API access
wal_WalletHolds funds for a party
eac_External AccountLinked bank account for deposits and withdrawals
pay_PaymentA payment between two parties
prq_Payment RequestA request for a payment from another party
trf_TransferA deposit or withdrawal between a wallet and a bank account
mmr_Money Movement RequestFund movement between wallets
txn_TransactionLedger entry returned by GET /transactions
inv_Party InvitationPending invitation for a party to join the platform
apr_Approval RequestA payment awaiting approval
req_RequestPer-request correlation ID, returned as meta.supportId on errors
whk_WebhookWebhook configuration
evt_EventWebhook event payload
ins_InstanceAgent session, uses UUIDv7

​
Working with IDs

​
API requests

Always use the full prefixed ID in API requests: 
{
  "data": {
    "attributes": {
      "amount": 500000,
      "counterparty": "pty_019cd1798d617f65a79cb965dda9eac3",
      "customerPartyId": "pty_019cd34e27bf78399b4e75b327d2ab25"
    }
  }
}

​
Validation

IDs are validated on every request. An invalid ID is rejected with an invalid_value error: 
{
  "errors": [
    {
      "code": "invalid_value",
      "status": "422",
      "detail": "Invalid pty ID format",
      "source": { "pointer": "/data/attributes/counterparty" }
    }
  ]
}
  • Parties - Primary business entity using pty_ IDs
  • Users - Human users with usr_ IDs
  • Agents - AI agents with agt_ IDs