Skip to main content
A party (pty_*) is Natural’s representation of a real-world identity. It ties together your Agents, Wallets, and the authorization you grant through Connect. An external party (epty_*) is a counterparty not on Natural; a party is on Natural. Read yours with GET /parties/me. 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 (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. 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 and PATCH /parties/{partyId}/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 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 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 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