> ## 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.

# Overview

> Third parties you transact with over Direct, and their banking details

<Note>
  Direct is in early access and subject to change. To request Direct access, contact [hi@natural.com](mailto:hi@natural.com).
</Note>

An external party (`epty_*`) is an individual or business not on Natural — a [party](/guides/concepts/parties) (`pty_*`) is on Natural, an external party is not. An external party account (`epa_*`) stores an external party's banking details and is the destination of [ACH](/guides/concepts/ach), [realtime](/guides/concepts/realtime), and [wire](/guides/concepts/wire) payments.

| | |
| - | - |
| API | [External party endpoints](/api-reference/external-parties/create-external-party) · [Account endpoints](/api-reference/external-party-accounts/store-banking-details-for-an-external-party) · [Errors](/api-reference/errors/external-parties) · [Account errors](/api-reference/errors/external-party-accounts) |
| Headers | `Idempotency-Key` required on create; `X-Instance-ID` for [agent](/guides/concepts/agents) calls |
| Connect | Pass `customerPartyId` on party or account create for a connected customer — both require the `external_parties.create` grant |
| Money in | Store the account first, then pay it with [ACH](/guides/concepts/ach), [realtime](/guides/concepts/realtime), or [wire](/guides/concepts/wire) |

## External parties

Create one with [`POST /external-parties`](/api-reference/external-parties/create-external-party):

```json theme={null}
{
  "data": {
    "attributes": {
      "kind": "individual",
      "name": "Jordan Rivera",
      "email": "jordan@example.com",
      "address": {
        "line1": "123 Market St",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "countryCode": "US"
      }
    }
  }
}
```

* `kind` and `name` are required. An individual's `name` must include first and last name. `email`, `phone`, and `address` are optional; phone numbers are normalized to E.164.
* A supplied `address` must be complete: `line1`, `city`, and an ISO two-letter `countryCode`; US addresses also require `state` and `postalCode`.
* Natural screens every external party and reports `screeningStatus` as `clear`, `under_review`, or `rejected`. A `rejected` party cannot have accounts stored.
* Fedwire requires a complete beneficiary address. If a [wire](/guides/concepts/wire) create returns `400 wire.beneficiary_address_required`, read the party's `addressVersion` and call [`PATCH /external-parties/{externalPartyId}/address`](/api-reference/external-parties/correct-an-external-party-address) with the complete address and `expectedAddressVersion`, then retry with the same IDs.
* Address completeness and bank wire eligibility are separate requirements — an account that supports ACH does not necessarily support wires.

## External party accounts

Store one with [`POST /external-party-accounts`](/api-reference/external-party-accounts/store-banking-details-for-an-external-party), sending the `accountDetails` for its type. A US bank account takes the account type plus the account and routing numbers:

```json theme={null}
{
  "data": {
    "attributes": {
      "externalPartyId": "epty_019cd1798d8d6873421613705e3c1415",
      "accountDetails": {
        "type": "us_bank_account",
        "accountType": "checking",
        "accountNumber": "123456786789",
        "routingNumber": "121000358"
      }
    }
  }
}
```

* Responses identify the account by its last four digits and a masked form; the full numbers are stored securely and never returned.
* `supportedRails` lists the rails the account is expected to accept — one or more of `ach`, `realtime`, and `wire`. It is advisory and refreshed periodically from the payment network; the authoritative check runs when you create a payment.

**Validation** — Natural validates the account at creation and reports the outcome in `validationState`. An account that cannot be validated immediately is `pending` and resolves asynchronously to `validated` or `failed`; the `external_party_account.validated` [event](/guides/concepts/events) fires when it validates. If validation fails at creation, the request returns `external_party_account.validation_failed` and nothing is stored. ACH credits work while validation is `pending`. A `failed` account cannot be used — store a new one.


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