Natural AI External Accounts API
Linked external bank accounts
OpenAPI Specification
openapi: 3.1.1
info:
title: Natural Agent Keys External Accounts API
version: 0.2.0
description: 'Natural''s payments API for autonomous agents.
**Base URL:** `https://api.natural.com`
AI agents, including coding agents, should prefer the hosted MCP server at `https://mcp.natural.com` when an MCP-aware host runs the agent, the Natural CLI for terminal/CI workflows, and the official SDKs for application runtimes they own. Use direct HTTP only for explicit low-level integrations, unsupported SDK gaps, or infrastructure work where REST is required.
For support: support@natural.com'
servers:
- url: https://api.natural.com
description: Production
tags:
- name: External Accounts
description: Linked external bank accounts
paths:
/external-accounts/processor-token:
post:
operationId: externalAccounts.createFromProcessorToken
summary: Link external account
description: Link or refresh a bank account using a Plaid processor token
tags:
- External Accounts
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
partyId:
type: string
pattern: ^pty_[0-9a-f]{32}$
description: Party that will own the account.
processorToken:
type: string
minLength: 1
maxLength: 256
description: Plaid processor token created for Natural and scoped to one account.
institutionName:
anyOf:
- type: string
maxLength: 100
- type: 'null'
description: Institution display name to store with the linked external account.
required:
- partyId
- processorToken
additionalProperties: false
required:
- attributes
additionalProperties: false
required:
- data
additionalProperties: false
examples:
default:
summary: Default
value:
data:
attributes:
partyId: pty_7c9e6679e29b41d4a716446655440001
processorToken: processor-sandbox-abc123
institutionName: Chase
responses:
'201':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
type:
type: string
enum:
- externalAccount
id:
type: string
pattern: ^eac_[0-9a-f]{32}$
description: External account ID (eac_*).
attributes:
type: object
properties:
lastFour:
type: string
description: Last four digits of the external bank account.
status:
enum:
- pending
- new
- active
- disabled
- deleted
- unknown
type: string
description: Lifecycle status of the external account.
connectionStatus:
enum:
- active
- login_required
- disconnected
type: string
description: Provider connection health for this external account.
createdAt:
type: string
format: date-time
description: Time when the external account was linked.
bankName:
anyOf:
- type: string
- type: 'null'
description: Bank institution name, when available.
accountName:
anyOf:
- type: string
- type: 'null'
description: Bank account display name, when available.
accountType:
anyOf:
- enum:
- checking
- savings
- unknown
type: string
- type: 'null'
description: Bank account type, when available.
required:
- lastFour
- status
- connectionStatus
- createdAt
- bankName
- accountName
- accountType
additionalProperties: false
title: ExternalAccountAttributes
relationships:
type: object
properties:
party:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum:
- party
id:
type: string
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
required:
- data
additionalProperties: false
title: ToOneRelationship
description: Party that owns the external account.
required:
- party
additionalProperties: false
title: ExternalAccountRelationships
required:
- type
- id
- attributes
- relationships
additionalProperties: false
title: ExternalAccountResource
description: External accounts linked or refreshed by the request.
meta:
type: object
properties:
pagination:
type: object
properties:
hasMore:
type: boolean
description: Whether more results are available.
nextCursor:
anyOf:
- type: string
- type: 'null'
description: Cursor for the next page, or null when there are no more results.
required:
- hasMore
- nextCursor
additionalProperties: false
title: PaginationMeta
rejectedAccounts:
type: array
items:
type: object
properties:
accountId:
type: string
description: Provider account identifier for the rejected account.
accountName:
anyOf:
- type: string
- type: 'null'
description: Display name of the rejected account.
accountMask:
anyOf:
- type: string
- type: 'null'
description: Last-four mask of the rejected account.
reason:
enum:
- profile_identity_missing
- bank_identity_unavailable
- bank_account_name_mismatch
- bank_account_address_mismatch
- bank_account_ownership_mismatch
- bank_account_verification_failed
type: string
description: Reason code explaining why the account was not linked.
required:
- accountId
- accountName
- accountMask
- reason
additionalProperties: false
title: ExternalAccountRejectedAccount
description: Accounts reviewed during linking but not linked.
required:
- pagination
- rejectedAccounts
additionalProperties: false
required:
- data
- meta
additionalProperties: false
title: ExternalAccountListWithRejectedAccountsResponse
examples:
default:
summary: Default
value:
data:
- type: externalAccount
id: eac_550e8400e29b41d4a716446655440000
attributes:
bankName: Chase
accountName: Plaid Checking
accountType: checking
lastFour: '0000'
status: active
connectionStatus: active
createdAt: '2026-01-04T15:30:00Z'
relationships:
party:
data:
type: party
id: pty_7c9e6679e29b41d4a716446655440001
meta:
pagination:
hasMore: false
nextCursor: null
rejectedAccounts: []
headers:
X-RateLimit-Limit:
description: Maximum requests allowed per window.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp when rate limit resets.
schema:
type: integer
'400':
description: Validation Error
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: invalid_value
detail: The information you entered isn't valid. Please check it and try again.
status: '400'
meta:
supportId: req_a1b2c3d4e5f6
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: unauthenticated
detail: Authentication is required.
status: '401'
meta:
supportId: req_a1b2c3d4e5f6
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: forbidden
detail: You do not have permission to perform this action.
status: '403'
meta:
supportId: req_a1b2c3d4e5f6
'404':
description: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: not_found
detail: The requested resource was not found.
status: '404'
meta:
supportId: req_a1b2c3d4e5f6
'409':
description: Conflict
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
# --- truncated at 32 KB (236 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/natural-ai/refs/heads/main/openapi/natural-ai-external-accounts-api-openapi.yml