Resources - Natural API

All Natural API responses follow the JSON:API specification. Each resource has a type, id, attributes, and optionally relationships.

Agent

Represents an autonomous agent that can make payments on behalf of a party.

Field	Type	Description
`type`	`"agent"`	Resource type
`id`	string	Agent ID (`agt_*` format)

Attributes

Field	Type	Required	Description
`name`	string	Yes	Human-readable name for the agent
`description`	string \| null	No	Description of the agent’s purpose
`status`	`ACTIVE`, `REVOKED`	Yes	Agent status
`createdAt`	string (datetime)	No	Creation timestamp
`createdBy`	string \| null	No	User who created the agent
`updatedAt`	string (datetime)	No	Last update timestamp
`updatedBy`	string \| null	No	User who last updated the agent

Relationships

Field	Type	Description
`party`	ToOneRelationship	Party that owns the agent

Example

{
  "type": "agent",
  "id": "agt_019cd1798d637a4da75dce386343931d",
  "attributes": {
    "name": "Carrier Payment Agent v2.1",
    "description": "Autonomous agent that pays delivery carriers",
    "status": "ACTIVE",
    "createdAt": "2026-01-04T15:30:00Z",
    "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0",
    "updatedAt": "2026-01-04T15:30:00Z",
    "updatedBy": "usr_019cd1798d657de5b5fed4198cb9fac0"
  },
  "relationships": {
    "party": {
      "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" }
    }
  }
}

Transaction

Represents a financial transaction (payment or transfer) with enriched display data.

Field	Type	Description
`type`	`"transaction"`	Resource type
`id`	string	Transaction ID (`txn_*` format)

Attributes

Field	Type	Required	Description
`amount`	number	Yes	Amount in minor units (cents)
`currency`	string	Yes	Currency code
`status`	string	Yes	Transfer status
`createdAt`	string	Yes	Creation timestamp
`isDelegated`	boolean	Yes	True if this is a delegated customer payment
`transactionType`	`payment`, `transfer`	Yes	Transaction type
`category`	`sent`, `received`, `deposit`, `withdrawal`	Yes	Category
`direction`	`INBOUND`, `OUTBOUND`	Yes	Direction
`description`	string \| null	No	Transfer description
`memo`	string \| null	No	Transfer memo
`updatedAt`	string \| null	No	Last update timestamp
`customerName`	string \| null	No	Customer name if delegated
`customerAgentId`	string \| null	No	Customer agent ID if delegated
`senderName`	string \| null	No	Sender display name
`recipientName`	string \| null	No	Recipient display name

Relationships

Field	Type	Description
`sourceParty`	NullableToOneRelationship	Source party
`destinationParty`	NullableToOneRelationship	Destination party
`sourceWallet`	NullableToOneRelationship	Source wallet
`destinationWallet`	NullableToOneRelationship	Destination wallet

Example

{
  "type": "transaction",
  "id": "txn_019cd36da26d75cd9b4923f83e80a90b",
  "attributes": {
    "amount": 100000,
    "currency": "USD",
    "status": "COMPLETED",
    "createdAt": "2026-01-04T15:30:00Z",
    "updatedAt": "2026-01-04T15:31:00Z",
    "isDelegated": false,
    "transactionType": "payment",
    "category": "sent",
    "direction": "OUTBOUND",
    "description": "Invoice payment",
    "memo": null,
    "customerName": null,
    "customerAgentId": null,
    "senderName": "Natural",
    "recipientName": "Walt's Business"
  },
  "relationships": {
    "sourceParty": {
      "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" }
    },
    "destinationParty": {
      "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" }
    },
    "sourceWallet": {
      "data": { "type": "wallet", "id": "wal_019cd3444a6f73db8ef1f4afd074c166" }
    },
    "destinationWallet": {
      "data": null
    }
  }
}

Counterparty

Aggregated counterparty data for a party you’ve transacted with.

Field	Type	Description
`type`	`"party"`	Resource type
`id`	string	Party ID or synthetic key

Attributes

Field	Type	Required	Description
`totalAmountMinor`	number	Yes	Total amount in minor units (cents)
`transactionCount`	number	Yes	Total number of payments
`firstAt`	string (datetime)	Yes	Timestamp of first payment
`counterpartyPartyId`	string \| null	No	Party ID (`pty_*`)
`partyName`	string \| null	No	Counterparty display name
`partyEmail`	string \| null	No	Counterparty primary email
`partyStatus`	string \| null	No	Counterparty party status

Example

{
  "type": "party",
  "id": "pty_019cd3444a6b7afe95c91cfdc74a46eb",
  "attributes": {
    "totalAmountMinor": 500000,
    "transactionCount": 5,
    "firstAt": "2026-01-04T15:30:00Z",
    "counterpartyPartyId": "pty_019cd3444a6b7afe95c91cfdc74a46eb",
    "partyName": "Velocity Logistics",
    "partyEmail": "billing@velocitylogistics.com",
    "partyStatus": "ACTIVE"
  }
}

Customer

Represents a party who has delegated access to you, or a pending delegation invitation. The data array may contain two resource types:

CustomerPartyResource (type: "party") — Active delegations
CustomerInvitationResource (type: "delegationInvitation") — Pending invitations

Attributes (shared)

Field	Type	Required	Description
`status`	string	Yes	Status (ACTIVE, PENDING, etc.)
`permissions`	string[]	Yes	Granted permissions
`createdAt`	string (datetime)	Yes	When the item was created
`email`	string \| null	No	Email for pending invitations
`party`	CustomerParty \| null	No	Party info (null for pending invitations)
`walletAvailableMinor`	number \| null	No	Available wallet balance in cents
`walletAccess`	`granted`, `denied`, `noWallet`	No	Wallet access status

Example (active delegation)

{
  "type": "party",
  "id": "dlg_550e8400e29b41d4a716446655440002",
  "attributes": {
    "status": "ACTIVE",
    "permissions": ["payments.read", "wallets.read"],
    "createdAt": "2026-01-10T12:00:00.000Z",
    "party": {
      "id": "pty_4a8c9823f39c42a5b817556766551112",
      "name": "Alice Customer",
      "email": "alice@example.com"
    },
    "walletAvailableMinor": 12500,
    "walletAccess": "granted"
  }
}

Example (pending invitation)

{
  "type": "delegationInvitation",
  "id": "din_550e8400e29b41d4a716446655440003",
  "attributes": {
    "status": "PENDING",
    "permissions": ["payments.read"],
    "createdAt": "2026-01-11T08:30:00.000Z",
    "email": "pending@example.com",
    "party": null,
    "walletAvailableMinor": null,
    "walletAccess": "denied"
  }
}

AgentDelegation

Represents an agent’s authorization to act within a delegation.

Field	Type	Description
`type`	`"agentDelegation"`	Resource type
`id`	string	Agent delegation ID (`adl_*` format)

Attributes

Field	Type	Required	Description
`permissions`	string[]	Yes	Granted permissions (empty = revoked)
`createdAt`	string (datetime)	Yes	Creation timestamp
`updatedAt`	string (datetime)	Yes	Last update timestamp
`agentName`	string \| null	No	Agent display name/label
`limits`	TransactionLimits \| null	No	Transaction limits in cents
`expiresAt`	string (datetime) \| null	No	Expiration timestamp
`createdBy`	string \| null	No	User who created (`usr_*`)
`delegatingPartyName`	string \| null	No	Customer party display name
`delegatedPartyName`	string \| null	No	Developer party display name

Relationships

Field	Type	Required	Description
`delegation`	ToOneRelationship	Yes	Parent party delegation
`agent`	ToOneRelationship	Yes	Agent granted access
`delegatingParty`	NullableToOneRelationship	No	Customer party granting access
`delegatedParty`	NullableToOneRelationship	No	Developer party receiving access

Example

{
  "type": "agentDelegation",
  "id": "adl_550e8400e29b41d4a716446655440000",
  "attributes": {
    "permissions": ["payments.create", "payments.read"],
    "createdAt": "2026-01-04T15:30:00Z",
    "updatedAt": "2026-01-04T15:30:00Z",
    "agentName": null,
    "limits": null,
    "expiresAt": "2027-01-04T15:30:00Z",
    "createdBy": "usr_550e8400e29b41d4a716446655440000"
  },
  "relationships": {
    "delegation": {
      "data": { "type": "delegation", "id": "dlg_550e8400e29b41d4a716446655440000" }
    },
    "agent": {
      "data": { "type": "agent", "id": "agt_3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r" }
    },
    "delegatingParty": {
      "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" }
    },
    "delegatedParty": {
      "data": null
    }
  }
}

DelegationInvitation

Represents an invitation for a customer to delegate access to a developer.

Field	Type	Description
`type`	`"delegationInvitation"`	Resource type
`id`	string	Invitation ID (`din_*` format)

Attributes

Field	Type	Required	Description
`customerEmail`	string	Yes	Email of the invited customer
`status`	`PENDING`, `ACCEPTED`, `REVOKED`, `EXPIRED`	Yes	Invitation status
`permissions`	string[]	Yes	Permissions requested
`expiresAt`	string	Yes	ISO 8601 expiration timestamp
`createdAt`	string	Yes	ISO 8601 creation timestamp
`token`	string \| null	No	Magic link token (only on create)
`magicLink`	string \| null	No	Full URL for customer (only on create)

Relationships

Field	Type	Description
`delegatedParty`	NullableToOneRelationship	Developer party that created this invitation
`delegatingParty`	NullableToOneRelationship	Customer party (populated after acceptance)

Example

{
  "type": "delegationInvitation",
  "id": "din_550e8400e29b41d4a716446655440000",
  "attributes": {
    "customerEmail": "customer@example.com",
    "status": "PENDING",
    "permissions": ["payments.create", "wallets.read"],
    "expiresAt": "2026-01-11T15:30:00Z",
    "createdAt": "2026-01-04T15:30:00Z",
    "token": null,
    "magicLink": null
  },
  "relationships": {
    "delegatedParty": {
      "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440002" }
    },
    "delegatingParty": {
      "data": null
    }
  }
}

DelegationLink

Represents a shareable link for establishing delegations.

Field	Type	Description
`type`	`"delegationLink"`	Resource type
`id`	string	Link ID (`dlk_*` format)

Attributes

Field	Type	Required	Description
`permissions`	string[]	Yes	Permissions granted by this link
`proposedAgents`	ProposedAgent[]	Yes	Agents proposed for authorization
`status`	`ACTIVE`, `REVOKED`	Yes	Link status
`createdAt`	string	Yes	Creation timestamp (ISO 8601)
`name`	string	Yes	Label for this link
`expiresAt`	string \| null	Yes	Expiration timestamp
`token`	string	Yes	Token for URL
`url`	string	Yes	Full shareable URL

Relationships

Field	Type	Description
`delegatedParty`	NullableToOneRelationship	Developer party that created this link

Example

{
  "type": "delegationLink",
  "id": "dlk_550e8400e29b41d4a716446655440000",
  "attributes": {
    "permissions": ["payments.create", "payments.read"],
    "proposedAgents": [
      {
        "agentId": "agt_3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r",
        "permissions": ["payments.create"],
        "limits": null
      }
    ],
    "status": "ACTIVE",
    "createdAt": "2026-01-04T15:30:00Z",
    "name": "Carrier Payment Integration",
    "expiresAt": null,
    "token": "lnk_abc123def456",
    "url": "https://app.natural.co/delegation-links/use/lnk_abc123def456"
  },
  "relationships": {
    "delegatedParty": {
      "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440002" }
    }
  }
}

Party

Represents a business or individual on the Natural platform.

Field	Type	Description
`type`	`"party"`	Resource type
`id`	string	Party ID (`pty_*` format)

Attributes

Field	Type	Required	Description
`partyType`	`PERSON`, `ORG`	Yes	Party type
`legalName`	string	Yes	Legal name of the party
`status`	`PROVISIONAL`, `ACTIVE`, `SUSPENDED`, `INACTIVE`	Yes	Party status
`kycStatus`	`PENDING`, `IN_PROGRESS`, `VERIFIED`, `REJECTED`	Yes	KYC verification status
`createdAt`	string (datetime)	Yes	When the party was created
`updatedAt`	string (datetime)	Yes	When the party was last updated
`displayName`	string \| null	No	Display name
`kycVerifiedAt`	string (datetime) \| null	No	When KYC was verified
`primaryEmail`	string \| null	No	Primary contact email
`primaryPhone`	string \| null	No	Primary phone number
`addressLine1`	string \| null	No	Street address
`addressCity`	string \| null	No	City
`addressState`	string \| null	No	State or province
`addressPostalCode`	string \| null	No	Postal code
`addressCountry`	string \| null	No	Country code (e.g., US)
`createdBy`	string \| null	No	User ID who created this party

Example

{
  "type": "party",
  "id": "pty_019cd1798d617f65a79cb965dda9eac3",
  "attributes": {
    "partyType": "ORG",
    "legalName": "Natural AI, Inc",
    "displayName": "Natural",
    "status": "ACTIVE",
    "kycStatus": "VERIFIED",
    "kycVerifiedAt": "2024-01-15T10:30:00Z",
    "primaryEmail": "contact@natural.co",
    "primaryPhone": "+1-555-555-0100",
    "addressLine1": "123 Main Street",
    "addressCity": "San Francisco",
    "addressState": "CA",
    "addressPostalCode": "94105",
    "addressCountry": "US",
    "createdBy": null,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

WalletBalance

Represents a party’s wallet balance with detailed breakdown.

Field	Type	Description
`type`	`"walletBalance"`	Resource type
`id`	string	Wallet ID (`wal_*` format)

Attributes

Field	Type	Required	Description
`breakdown`	BalanceBreakdown	Yes	Balance breakdown across all assets
`available`	BalanceAmount	Yes	Available balance
`pendingClaimAmountMinor`	number \| null	No	Pending incoming claim amounts (cents)
`pendingClaimCount`	number \| null	No	Number of pending incoming claims

Relationships

Field	Type	Description
`party`	ToOneRelationship	Party that owns the wallet

BalanceAmount

Field	Type	Description
`amountMinor`	number	Amount in minor units (cents)

BalanceBreakdown

Field	Type	Description
`operatingFunded`	BalanceAmount	Operating funded balance
`operatingAdvanced`	BalanceAmount	Operating advanced balance
`escrowFundedSettled`	BalanceAmount	Settled escrow funds
`escrowAdvanced`	BalanceAmount	Escrow advanced balance
`holdsOutbound`	BalanceAmount	Outbound holds

Example

{
  "type": "walletBalance",
  "id": "wal_019cd3444a6f73db8ef1f4afd074c166",
  "attributes": {
    "breakdown": {
      "operatingFunded": { "amountMinor": 1000000 },
      "operatingAdvanced": { "amountMinor": 0 },
      "escrowFundedSettled": { "amountMinor": 0 },
      "escrowAdvanced": { "amountMinor": 0 },
      "holdsOutbound": { "amountMinor": 50000 }
    },
    "available": { "amountMinor": 950000 },
    "pendingClaimAmountMinor": 0,
    "pendingClaimCount": 0
  },
  "relationships": {
    "party": {
      "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" }
    }
  }
}

ExternalFundingSource

Represents a linked bank account used for deposits and withdrawals.

Field	Type	Description
`type`	`"externalFundingSource"`	Resource type
`id`	string	Funding source ID (`efs_*` format)

Attributes

Field	Type	Required	Description
`lastFour`	string	Yes	Last 4 digits of account
`status`	`new`, `active`, `disabled`, `deleted`, `unknown`	Yes	Status
`createdAt`	string (datetime)	Yes	When the funding source was linked
`bankName`	string \| null	No	Bank institution name
`accountName`	string \| null	No	Account display name
`accountType`	`checking`, `savings`, `unknown` \| null	No	Account type
`verificationState`	string \| null	No	Verification state

Relationships

Field	Type	Description
`party`	ToOneRelationship	Party that owns the funding source

Example

{
  "type": "externalFundingSource",
  "id": "efs_019cd3444a77776dadda2c30ff23706d",
  "attributes": {
    "bankName": "Chase",
    "accountName": "Business Checking",
    "accountType": "checking",
    "lastFour": "6789",
    "verificationState": "verifiedInstantAuth",
    "status": "active",
    "createdAt": "2026-01-04T15:30:00Z"
  },
  "relationships": {
    "party": {
      "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" }
    }
  }
}

ApiKey

Represents an API key for programmatic access.

Field	Type	Description
`type`	`"apiKey"`	Resource type
`id`	string	API key ID (`key_*` format)

Attributes

Field	Type	Required	Description
`apiKeyPrefix`	string	Yes	First 16 chars of API key
`name`	string	Yes	Human-readable name
`scopes`	string[]	Yes	Authorized scopes
`environment`	`development`, `production`	Yes	Environment
`status`	`ACTIVE`, `REVOKED`	Yes	Status
`createdAt`	string (datetime)	Yes	Creation timestamp
`expiresAt`	string (datetime)	Yes	Expiration timestamp
`lastUsedAt`	string (datetime) \| null	No	Last used timestamp
`revokedAt`	string (datetime) \| null	No	Revocation timestamp
`createdBy`	string \| null	No	Creator user ID (`usr_*`)
`revokedBy`	string \| null	No	Revoker user ID (`usr_*`)

Relationships

Field	Type	Description
`party`	ToOneRelationship	Party that owns the API key

When an API key is first created, the response includes the full apiKey secret in the attributes. This is the only time the secret is shown — store it securely.

Example

{
  "type": "apiKey",
  "id": "key_019cd3604fd67bf5a3b5821ca7836c14",
  "attributes": {
    "apiKeyPrefix": "nat_live_abc12345",
    "name": "Production Backend",
    "scopes": ["payments.read", "payments.create"],
    "environment": "production",
    "status": "ACTIVE",
    "createdAt": "2026-01-04T15:30:00Z",
    "expiresAt": "2026-04-04T15:30:00Z",
    "lastUsedAt": null,
    "revokedAt": null,
    "createdBy": null,
    "revokedBy": null
  },
  "relationships": {
    "party": {
      "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" }
    }
  }
}

Invitation

Represents a party membership invitation.

Field	Type	Description
`type`	`"invitation"`	Resource type
`id`	string	Invitation ID (`inv_*` format)

Attributes

Field	Type	Required	Description
`email`	string	Yes	Invitee email address
`role`	`OWNER`, `ADMIN`, `MEMBER`	Yes	Role assigned on acceptance
`status`	`PENDING`, `ACCEPTED`, `REVOKED`	Yes	Invitation status
`expiresAt`	string	Yes	ISO 8601 expiration timestamp
`createdAt`	string	Yes	ISO 8601 creation timestamp
`acceptedAt`	string \| null	No	Timestamp when accepted

Example

{
  "type": "invitation",
  "id": "inv_019cd4a832f37c4b8a1d63e94b7c8d12",
  "attributes": {
    "email": "engineer@velocitylogistics.com",
    "role": "MEMBER",
    "status": "PENDING",
    "expiresAt": "2026-01-11T15:30:00Z",
    "createdAt": "2026-01-04T15:30:00Z",
    "acceptedAt": null
  }
}

Overview

Agents

Customers

Counterparties

Payments

Delegations

Parties

Wallet

API keys

Errors

​Agent

​Attributes

​Relationships

​Transaction

​Attributes

​Relationships

​Counterparty

​Attributes

​Customer

​Attributes (shared)

​AgentDelegation

​Attributes

​Relationships

​DelegationInvitation

​Attributes

​Relationships

​DelegationLink

​Attributes

​Relationships

​Party

​Attributes

​WalletBalance

​Attributes

​Relationships

​BalanceAmount

​BalanceBreakdown

​ExternalFundingSource

​Attributes

​Relationships

​ApiKey

​Attributes

​Relationships

​Invitation

​Attributes

Agent

Attributes

Relationships

Transaction

Attributes

Relationships

Counterparty

Attributes

Customer

Attributes (shared)

AgentDelegation

Attributes

Relationships

DelegationInvitation

Attributes

Relationships

DelegationLink

Attributes

Relationships

Party

Attributes

WalletBalance

Attributes

Relationships

BalanceAmount

BalanceBreakdown

ExternalFundingSource

Attributes

Relationships

ApiKey

Attributes

Relationships

Invitation

Attributes