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

> The real-world identity behind your wallets and agents

A party (`pty_*`) is Natural's representation of a real-world identity. It ties together your [Agents](/guides/concepts/agents), [Wallets](/guides/concepts/wallets), and the authorization you grant through [Connect](/guides/products/connect). An [external party](/guides/concepts/external-parties) (`epty_*`) is a counterparty not on Natural; a party is on Natural. Read yours with [`GET /parties/me`](/api-reference/parties/get-party).

There are two types of party: individuals and businesses. Most developers sign up as a business so they can invite teammates.

Every party clears [Compliance](/guides/overview/compliance) (KYB for businesses, KYC for individuals).

## Handles

Every party can claim a **handle**, the `@name` other parties use to pay or request money from you without knowing an email, phone number, or party ID. Agents get composed handles under their party (`@acme-support`), so a handle also names who an agent acts for.

Claim or rename your handle in the dashboard, or with [`PUT /parties/me/handle`](/api-reference/parties/set-party-handle). Handles cannot be cleared: every party keeps one once claimed. A signed-in user or the party's API key can change a handle; agent keys cannot, and an unverified party gets `party_not_verified`. Renaming releases the previous name into a 14-day hold, during which only your party can take it back.

## Brand color

A brand color belongs to the party. Business owners and admins can edit it in Settings, and API callers can use [`GET /parties/{partyId}/branding`](/api-reference/parties/get-party-branding) and [`PATCH /parties/{partyId}/branding`](/api-reference/parties/update-party-branding).

Reads require `party.read`; updates require `party.update`. To act for another party, pass its ID using a credential authorized by an active delegation with the required permission. Agent-bound credentials must also have the required agent permissions.

Send `brandColor` inside `data.attributes` as `#RGB` or `#RRGGBB`. Responses use uppercase, six-digit hex. Send `null` to reset to the default. Updates require an `Idempotency-Key` header; reuse it only when retrying the same update. Branding is stored separately in each product environment.

## Business profile photos

The branding endpoint also manages a business party's profile photo. Authorized API keys and agents can change it on the business's behalf using `party.update` permission. Personal-party photo changes are not supported by this endpoint.

1. Call [`POST /parties/{partyId}/branding/photo-uploads`](/api-reference/parties/create-branding-photo-upload) with `contentType` and `sizeBytes` inside `data.attributes`. JPEG, PNG, and WebP files up to 5 MB are supported.
2. POST multipart form data to the returned `uploadUrl`, including every returned `uploadFields` value and the image as the final `file` field. Upload URLs expire; request a new upload if needed.
3. Call [`PATCH /parties/{partyId}/branding`](/api-reference/parties/update-party-branding) with the returned `objectKey` as `avatarObjectKey` inside `data.attributes` and an `Idempotency-Key` header.

Omitted fields stay unchanged. Send `avatarObjectKey: null` to remove the photo, or include `brandColor` to update both together. Photo and color changes in a combined request are saved atomically. Reads return the public photo in `avatarUrl`.

Business profile photos are managed in Live and reflected in Sandbox through identity synchronization. Sandbox cannot create photo uploads or change the shared photo. Brand color remains local to each environment.

## Canonical examples

These docs use three parties as running examples:

### Kendall Developer (business party)

Kendall is an agent developer who has integrated Natural into his AI property management platform. He:

* Uses agents to automate vendor and contractor payments
* Uses Natural to allow his agents to pay his customers

### Eric Customer (business party)

Eric runs a property management company and uses Kendall's agents. He:

* Onboards as Kendall's customer through [Connect](/guides/products/connect) and authorizes Kendall's agents to pay on his behalf
* Uses Kendall's agents to pay vendors and contractors automatically

### Klaire Contractor (individual party)

Klaire is a plumber who receives payments from businesses. She:

* Is sent money by Kendall's agents on behalf of Eric
* Signs up to claim her first payment from Eric


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