IDs

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-3 character type indicator (e.g., pty_ for party)
UUID: 32 hexadecimal characters (no hyphens)

ID types

Prefix	Resource	Description
`pty_`	Party	Business or individual entity on the platform
`usr_`	User	Person who logs into a party
`agt_`	Agent	API client that acts on behalf of a party
`dlg_`	Delegation	Permission grant between two parties
`adl_`	Agent Delegation	Links an agent to a delegation
`adi_`	Agent Delegation Invitation	Invitation for a customer to authorize an agent
`apy_`	API Key	Credential for API access
`agk_`	Agent Key	Credential bound to one agent
`wal_`	Wallet	Holds funds for a party
`eac_`	External Account	Linked bank account for deposits and withdrawals
`pay_`	Payment	A payment between two parties
`prq_`	Payment Request	A request for a payment from another party
`trf_`	Transfer	A deposit or withdrawal between a wallet and a bank account
`txn_`	Transaction	Ledger entry returned by GET /transactions
`inv_`	Party Invitation	Pending invitation for a party to join the platform
`apr_`	Approval Request	A payment awaiting approval
`req_`	Request	Per-request correlation ID (`req_` plus 12 hex characters), returned as `meta.supportId` on errors
`whk_`	Webhook	Webhook configuration
`evt_`	Event	Webhook event payload

Working with IDs

API requests

Always use the full prefixed ID in API requests:

{
  "data": {
    "attributes": {
      "amount": 500000,
      "counterparty": { "type": "party_id", "value": "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
Agents — AI agents with agt_ IDs

⌘I

Overview

Agents

Customers

Payments

Transactions

Transfers

Payment Requests

Approvals

Limits

Parties

Party Invitations

Wallets

Wallet Access

External Accounts

Direct

API keys

Agent keys

Webhooks

Events

Errors

Format

ID types

Working with IDs

API requests

Validation

​Format

​ID types

​Working with IDs

​API requests

​Validation

​Related

Format

ID types

Working with IDs

API requests

Validation

Related