> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# IDs

> Prefixed identifiers for type safety and readability

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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "errors": [
    {
      "code": "invalid_value",
      "status": "422",
      "detail": "Invalid pty ID format",
      "source": { "pointer": "/data/attributes/counterparty" }
    }
  ]
}
```

## Related

* [Parties](/guides/concepts/parties): Primary business entity using `pty_` IDs
* [Agents](/guides/concepts/agents): Agents with `agt_` IDs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.