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 to 4 lowercase letters naming the type (e.g., pty_ for party)
UUID: 32 lowercase hexadecimal characters (no hyphens)

ID types

Prefix	Resource	Description
`pty_`	Party	Business or individual entity on Natural
`usr_`	User	Person who logs into a party
`agt_`	Agent	An actor that moves money for a party
`agk_`	Agent key	Credential bound to one agent
`apy_`	API key	Credential for API access
`dlg_`	Delegation	Permission grant between two parties
`adl_`	Agent delegation	Links an agent to a delegation
`adi_`	Customer invitation	Invitation for a customer to authorize an agent
`ivl_`	Invitation link	Reusable link a customer opens to authorize your agents
`inv_`	Party invitation	Pending invitation for a party to join Natural
`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, withdrawal, or transfer between wallets
`txn_`	Transaction	Ledger entry returned by GET /transactions
`apr_`	Approval	A money movement awaiting approval
`epty_`	External party	A party outside Natural that you pay with Direct
`epa_`	External party account	Bank account of an external party
`ach_`	ACH payment	ACH credit from a wallet to an external party account
`mdt_`	Mandate	Authorization a payer grants for future card charges
`amd_`	Agentic mandate	Budget an agent may spend against on a saved card
`apm_`	Agentic payment method	A saved card enrolled for agentic payments that mandates spend against
`apu_`	Agentic purchase	One purchase an agent makes under a mandate
`cpc_`	Compliance case	A compliance review on a party, returned by the party compliance endpoint
`wire_`	Wire	Domestic USD wire from a wallet to an external party account
`rt_`	Realtime payment	RTP or FedNow credit from a wallet to an external party account
`pmi_`	Payment intent	Amount to collect by card, with a checkout link
`pli_`	Line item	One line on a payment intent
`cpy_`	Card payment	One attempt to pay a payment intent
`rfd_`	Refund	Return of a card payment to the card that paid
`vos_`	Voice session	One phone call that collects a payment intent
`cbk_`	Chargeback	A challenge to a card payment you received
`evf_`	Chargeback evidence file	A file uploaded as evidence for a chargeback
`pcd_`	Agent card	A stand-in card credential issued to an agent for checkout
`cit_`	Card transaction	One authorization or settlement on an agent card
`csn_`	Card session	A short-lived grant for an agent’s browser to use one card at checkout
`whk_`	Webhook	Webhook configuration
`evt_`	Event	Webhook event payload
`rdy_`	Redelivery	Manual redelivery of an event to a webhook
`req_`	Request	Correlation ID for one request, returned as `meta.supportId` on errors. Natural mints `req_` plus 12 hex characters unless you send your own `X-Request-ID` (up to 128 characters of letters, digits, `_`, and `-`), which is echoed back instead

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: Agents with agt_ IDs

Overview

Agents

Customers

Payments

Transactions

Transfers

Payment Requests

Payment Intents

Plans

Card Payments

Voice Sessions

Refunds

Chargebacks

Approvals

Limits

Parties

Party Invitations

Wallets

Wallet Access

External Accounts

Cards

Agent checkout

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