{ "servers": [ { "url": "https://api.natural.com", "description": "Production" } ], "components": { "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer", "description": "Bearer authentication: send your API key, agent key, or OAuth access token as `Authorization: Bearer `." } }, "schemas": { "ComplianceSessionStatusResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Compliance verification session ID." }, "type": { "type": "string", "enum": [ "complianceSessionStatus" ] }, "attributes": { "type": "object", "properties": { "programId": { "type": "string", "description": "Compliance program identifier." }, "programVersionId": { "type": "string", "description": "Compliance program version identifier." }, "status": { "enum": [ "UNSPECIFIED", "NOT_READY", "READY", "PENDING", "MET", "DENIED", "ACTION_NEEDED", "DEPRECATED" ], "type": "string", "description": "Current compliance case status." }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique requirement identifier." }, "key": { "type": "string", "description": "Stable requirement key." }, "description": { "type": "string", "description": "Requirement description." } }, "required": [ "id", "key", "description" ], "additionalProperties": false }, "description": "Requirements currently attached to this compliance case." } }, "required": [ "programId", "programVersionId", "status", "requirements" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "PartyComplianceStatusResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*) being verified." }, "type": { "type": "string", "enum": [ "partyComplianceStatus" ] }, "attributes": { "type": "object", "properties": { "programCode": { "type": "string", "description": "Compliance program code." }, "caseStatus": { "enum": [ "UNSPECIFIED", "NOT_READY", "READY", "PENDING", "MET", "DENIED", "ACTION_NEEDED", "DEPRECATED" ], "type": "string", "description": "Current compliance case status." }, "displayState": { "enum": [ "verified", "underReview", "inProgress", "documentsRequired", "rejected" ], "type": "string", "description": "Customer-facing verification state." }, "title": { "type": "string", "description": "User-friendly title for the current state." }, "message": { "type": "string", "description": "User-friendly message explaining the current state." }, "canProceed": { "type": "boolean", "description": "Whether the party can proceed with platform features." }, "requirementsDue": { "type": "array", "items": { "type": "string" }, "description": "Requirement keys that still need user action or review." } }, "required": [ "programCode", "caseStatus", "displayState", "title", "message", "canProceed", "requirementsDue" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "TransactionLimits": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "TransactionLimits" } } }, "info": { "title": "Natural API", "version": "0.2.0", "description": "Natural's payments API for autonomous agents.\n\n**Base URL:** `https://api.natural.com`\n\nAI 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.\n\nFor support: support@natural.com" }, "openapi": "3.1.1", "paths": { "/agents": { "post": { "operationId": "agents.create", "summary": "Create agent", "description": "Create an agent", "tags": [ "Agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Agent display name." }, "description": { "type": "string", "maxLength": 100, "description": "Agent description." }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._]{1,28}[a-z0-9]$", "description": "Agent-specific part of the handle, such as support in @acme-support." }, "limits": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "description": "Agent spending limits. Agent credentials cannot set them." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet the agent is granted access to. Defaults to the party's default wallet when omitted." } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "name": "Carrier Payment Agent v2.1", "description": "Autonomous agent that pays delivery carriers", "slug": "carrier_payments", "limits": { "perTransaction": 100000 } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null if none is configured." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this agent was created." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent last authenticated, or null if it has never authenticated." } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "attributes": { "name": "Carrier Payment Agent v2.1", "description": "Autonomous agent that pays delivery carriers", "handle": "@natural-carrier_payments", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "lastActiveAt": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "agents.list", "summary": "List agents", "description": "List agents", "tags": [ "Agents" ], "parameters": [ { "name": "status", "in": "query", "schema": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Filter by status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null if none is configured." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this agent was created." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent last authenticated, or null if it has never authenticated." } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "attributes": { "name": "Carrier Payment Agent v2.1", "description": "Autonomous agent that pays delivery carriers", "handle": "@natural-carrier_payments", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "lastActiveAt": "2026-01-05T09:12:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agents/{agentId}": { "get": { "operationId": "agents.get", "summary": "Get agent", "description": "Get an agent", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null if none is configured." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this agent was created." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent last authenticated, or null if it has never authenticated." } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "attributes": { "name": "Carrier Payment Agent v2.1", "description": "Autonomous agent that pays delivery carriers", "handle": "@natural-carrier_payments", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "lastActiveAt": "2026-01-05T09:12:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "patch": { "operationId": "agents.update", "summary": "Update agent", "description": "Update an agent's mutable fields; a slug renames the handle and can never be cleared", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ], "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "Agent description." }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._]{1,28}[a-z0-9]$", "description": "Agent-specific part of the handle, such as support in @acme-support. Renames the handle; omission leaves it unchanged. Handles cannot be cleared." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Agent spending limits. Null clears all limits; omission leaves them unchanged. Within the object, a null or omitted window clears that limit." } }, "additionalProperties": false, "title": "AgentUpdateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentUpdateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "name": "Carrier Payment Agent v3.0", "description": "Autonomous agent that pays delivery carriers with enhanced fraud detection" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null if none is configured." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this agent was created." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent last authenticated, or null if it has never authenticated." } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "attributes": { "name": "Carrier Payment Agent v3.0", "description": "Autonomous agent that pays delivery carriers with enhanced fraud detection", "handle": "@natural-carrier_payments", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "lastActiveAt": "2026-01-05T09:12:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "delete": { "operationId": "agents.remove", "summary": "Delete agent", "description": "Delete an agent and revoke its active customer authorizations and pending invitations", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null if none is configured." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this agent was created." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent last authenticated, or null if it has never authenticated." } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "attributes": { "name": "Carrier Payment Agent v2.1", "description": "Autonomous agent that pays delivery carriers", "handle": "@natural-carrier_payments", "status": "REVOKED", "limits": null, "createdAt": "2026-01-04T15:30:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "lastActiveAt": "2026-01-05T09:12:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, "meta": { "deleted": true } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/customers": { "get": { "operationId": "customers.list", "summary": "List customers", "description": "List customers who have authorized an agent to act for them", "tags": [ "Customers" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "active", "revoked", "all" ], "type": "string", "default": "active", "description": "Filter by connection state. Active returns any non-revoked connection (including suspended and expired). Revoked returns customers whose access was revoked. All returns both." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null if none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the customer was created." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Delegation status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Granted permissions." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the customer was connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When access was revoked, or null if not revoked." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's composed public handle (@namespace-slug), or null when it has none." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions this agent holds." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CustomerListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "id": "pty_4a8c9823f39c42a5b817556766551112", "type": "customer", "attributes": { "name": "Acme Co", "email": "ops@acme.com", "avatarUrl": "https://static.natural.com/avatars/acme-co.png", "createdAt": "2026-01-04T15:30:00.000Z", "delegation": { "id": "dlg_550e8400e29b41d4a716446655440000", "status": "ACTIVE", "permissions": [ "payments.read" ], "createdAt": "2026-01-10T12:00:00.000Z", "revokedAt": null }, "agents": [ { "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "name": "Invoice Agent", "handle": "@acme-invoice", "status": "ACTIVE", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000, "perDay": 500000, "perMonth": 2000000 } } ] } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/customers/{customerId}": { "get": { "operationId": "customers.get", "summary": "Get customer", "description": "Get a customer who has authorized an agent", "tags": [ "Customers" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null if none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the customer was created." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Delegation status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Granted permissions." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the customer was connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When access was revoked, or null if not revoked." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's composed public handle (@namespace-slug), or null when it has none." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions this agent holds." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." } }, "required": [ "data" ], "additionalProperties": false, "title": "CustomerResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_4a8c9823f39c42a5b817556766551112", "type": "customer", "attributes": { "name": "Acme Co", "email": "ops@acme.com", "avatarUrl": "https://static.natural.com/avatars/acme-co.png", "createdAt": "2026-01-04T15:30:00.000Z", "delegation": { "id": "dlg_550e8400e29b41d4a716446655440000", "status": "ACTIVE", "permissions": [ "payments.read" ], "createdAt": "2026-01-10T12:00:00.000Z", "revokedAt": null }, "agents": [ { "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "name": "Invoice Agent", "handle": "@acme-invoice", "status": "ACTIVE", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000, "perDay": 500000, "perMonth": 2000000 } } ] } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/customers/invitations": { "get": { "operationId": "customers.listInvitations", "summary": "List customer invitations", "description": "List pending customer invitations", "tags": [ "Customers" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "customerInvitation" ] }, "id": { "type": "string", "description": "Recipient email." }, "attributes": { "type": "object", "properties": { "status": { "type": "string", "description": "Invitation status." }, "party": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null if none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the customer was created." } }, "required": [ "id", "name", "email", "avatarUrl", "createdAt" ], "additionalProperties": false, "title": "CustomerParty" }, { "type": "null" } ], "description": "Customer party, or null if they haven't signed up yet." }, "email": { "type": "string", "description": "Recipient email." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the invitation was created." }, "agentInvitations": { "type": "array", "items": { "type": "object", "properties": { "invitationId": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." }, "agent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's composed public handle (@namespace-slug), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false, "title": "CustomerAgent", "description": "Invited agent." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions requested for this agent." }, "url": { "type": "string", "format": "uri", "description": "Invitation URL. Natural sends it automatically for email invitations; deliver it yourself for phone invitations." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the invitation was created." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the invitation expires, or null if it does not expire." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." } }, "required": [ "invitationId", "agent", "permissions", "url", "createdAt", "expiresAt", "tags" ], "additionalProperties": false, "title": "AgentInvitation" }, "description": "Agent invitations sent to this recipient." } }, "required": [ "status", "party", "email", "createdAt", "agentInvitations" ], "additionalProperties": false, "title": "CustomerInvitationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerInvitationResource", "description": "Pending customer invitation grouped by recipient." } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PendingInvitationListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "customerInvitation", "id": "ops@acme.com", "attributes": { "status": "PENDING", "party": null, "email": "ops@acme.com", "createdAt": "2026-01-05T10:15:00.000Z", "agentInvitations": [ { "invitationId": "adi_550e8400e29b41d4a716446655440000", "agent": { "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "name": "Invoice Agent", "handle": "@acme-invoice" }, "permissions": [ "payments.read" ], "url": "https://www.natural.com/connect/adi_550e8400e29b41d4a716446655440000", "createdAt": "2026-01-05T10:15:00.000Z", "expiresAt": "2026-01-12T10:15:00.000Z", "tags": { "campaign": "q3_reactivation" } }, { "invitationId": "adi_660f9500f30c52e5b827557766551111", "agent": { "id": "agt_4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a", "name": "Refunds Agent", "handle": "@acme-refunds" }, "permissions": [ "payments.create", "payments.read" ], "url": "https://www.natural.com/connect/adi_660f9500f30c52e5b827557766551111", "createdAt": "2026-01-05T10:15:00.000Z", "expiresAt": "2026-01-12T10:15:00.000Z", "tags": { "campaign": "q3_reactivation" } } ] } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "operationId": "customers.createInvitations", "summary": "Invite customers", "description": "Invite customers to connect with an agent", "tags": [ "Customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "recipients": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "maxLength": 254, "format": "email", "description": "Email address." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "maxLength": 16, "description": "Phone number." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)." } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "CustomerInvitationRecipient" }, "description": "Recipients to invite." }, "agents": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "permissions": { "type": "array", "minItems": 1, "items": { "enum": [ "payments.read", "payments.create", "external_accounts.create", "wallets.read", "wallets.update", "party.read", "party.update" ], "type": "string" }, "description": "Permissions to grant this agent." }, "limits": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction cap in integer cents (USD)." } }, "additionalProperties": false, "description": "Transaction limits for this agent." } }, "required": [ "agentId", "permissions" ], "additionalProperties": false, "title": "CustomerInvitationAgentSpec" }, "description": "Agents to grant access to. Each recipient receives an invitation for every agent listed." }, "expiresAt": { "type": "string", "maxLength": 64, "format": "date-time", "description": "When the invitation expires. Defaults to 30 days from now, up to a 90-day maximum." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Tags applied to each invitation." } }, "required": [ "recipients", "agents" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "CustomerInvitationCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "recipients": [ { "type": "email", "value": "ops@acme.com" } ], "agents": [ { "agentId": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000 } } ], "expiresAt": "2026-01-12T10:15:00.000Z", "tags": { "campaign": "q3_reactivation" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agentDelegationInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." }, "attributes": { "type": "object", "properties": { "developerName": { "type": "string", "description": "Developer name." }, "email": { "type": "string", "description": "Recipient email." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone." }, "url": { "type": "string", "format": "uri", "description": "Invitation URL. Natural sends it automatically for email invitations; deliver it yourself for phone invitations." }, "agentName": { "type": "string", "description": "Agent name." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted on accept." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Transaction limits." }, "status": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Invitation status." }, "effectiveStatus": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Resolved status." }, "expiresAt": { "type": "string", "description": "When the invitation expires." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was accepted." }, "declinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was declined." }, "cancelReason": { "anyOf": [ { "enum": [ "AGENT_RETIRED", "DEVELOPER_RETIRED", "DEVELOPER_REVOKED" ], "type": "string" }, { "type": "null" } ], "description": "Reason for cancellation." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "description": "When the invitation was created." }, "updatedAt": { "type": "string", "description": "When the invitation was last updated." } }, "required": [ "developerName", "email", "phone", "url", "agentName", "permissions", "limits", "status", "effectiveStatus", "expiresAt", "acceptedAt", "declinedAt", "cancelReason", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentDelegationInvitationAttributes", "description": "Invitation details." }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The invited agent." }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party that accepted the invitation, or null until acceptance." } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "description": "Related resources." } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentDelegationInvitationResource" }, "description": "Created invitations." }, "meta": { "type": "object", "properties": { "failedRecipients": { "type": "array", "items": { "type": "object", "properties": { "recipient": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "maxLength": 254, "format": "email", "description": "Email address." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "maxLength": 16, "description": "Phone number." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)." } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "CustomerInvitationRecipient", "description": "Recipient that failed." }, "reason": { "type": "string", "description": "Why this recipient's invitations failed." } }, "required": [ "recipient", "reason" ], "additionalProperties": false }, "description": "Recipients whose invitations could not be created." } }, "required": [ "failedRecipients" ], "additionalProperties": false, "description": "Metadata about the batch." } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CustomerInvitationCreateResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agentDelegationInvitation", "id": "adi_550e8400e29b41d4a716446655440000", "attributes": { "developerName": "Acme Co", "email": "ops@acme.com", "phone": null, "url": "https://www.natural.com/connect/adi_550e8400e29b41d4a716446655440000", "agentName": "Invoice Agent", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000 }, "status": "PENDING", "effectiveStatus": "PENDING", "expiresAt": "2026-01-12T10:15:00.000Z", "acceptedAt": null, "declinedAt": null, "cancelReason": null, "tags": { "campaign": "q3_reactivation" }, "createdAt": "2026-01-05T10:15:00.000Z", "updatedAt": "2026-01-05T10:15:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f" } }, "customerParty": { "data": null } } } ], "meta": { "failedRecipients": [] } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] } }, "/customers/invitations/{invitationId}": { "delete": { "operationId": "customers.revokeInvitation", "summary": "Revoke customer invitation", "description": "Revoke a pending customer invitation", "tags": [ "Customers" ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agentDelegationInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." }, "attributes": { "type": "object", "properties": { "developerName": { "type": "string", "description": "Developer name." }, "email": { "type": "string", "description": "Recipient email." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone." }, "url": { "type": "string", "format": "uri", "description": "Invitation URL. Natural sends it automatically for email invitations; deliver it yourself for phone invitations." }, "agentName": { "type": "string", "description": "Agent name." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted on accept." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Transaction limits." }, "status": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Invitation status." }, "effectiveStatus": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Resolved status." }, "expiresAt": { "type": "string", "description": "When the invitation expires." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was accepted." }, "declinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was declined." }, "cancelReason": { "anyOf": [ { "enum": [ "AGENT_RETIRED", "DEVELOPER_RETIRED", "DEVELOPER_REVOKED" ], "type": "string" }, { "type": "null" } ], "description": "Reason for cancellation." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "description": "When the invitation was created." }, "updatedAt": { "type": "string", "description": "When the invitation was last updated." } }, "required": [ "developerName", "email", "phone", "url", "agentName", "permissions", "limits", "status", "effectiveStatus", "expiresAt", "acceptedAt", "declinedAt", "cancelReason", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentDelegationInvitationAttributes", "description": "Invitation details." }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The invited agent." }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party that accepted the invitation, or null until acceptance." } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "description": "Related resources." } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentDelegationInvitationResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CustomerInvitationSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentDelegationInvitation", "id": "adi_550e8400e29b41d4a716446655440000", "attributes": { "developerName": "Acme Co", "email": "ops@acme.com", "phone": null, "url": "https://www.natural.com/connect/adi_550e8400e29b41d4a716446655440000", "agentName": "Invoice Agent", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000 }, "status": "CANCELED", "effectiveStatus": "CANCELED", "expiresAt": "2026-01-12T10:15:00.000Z", "acceptedAt": null, "declinedAt": null, "cancelReason": "DEVELOPER_REVOKED", "tags": { "campaign": "q3_reactivation" }, "createdAt": "2026-01-05T10:15:00.000Z", "updatedAt": "2026-01-05T10:20:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f" } }, "customerParty": { "data": null } } }, "meta": { "deleted": true } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/customers/{customerId}/agents/{agentId}": { "delete": { "operationId": "customers.revokeAgent", "summary": "Revoke agent access", "description": "Remove an agent's access to a customer", "tags": [ "Customers" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null if none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the customer was created." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Delegation status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Granted permissions." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the customer was connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When access was revoked, or null if not revoked." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's composed public handle (@namespace-slug), or null when it has none." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions this agent holds." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." } }, "required": [ "data" ], "additionalProperties": false, "title": "CustomerResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null if none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the customer was created." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Delegation status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Granted permissions." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the customer was connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When access was revoked, or null if not revoked." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's composed public handle (@namespace-slug), or null when it has none." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions this agent holds." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false } ], "title": "CustomerAgentRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_4a8c9823f39c42a5b817556766551112", "type": "customer", "attributes": { "name": "Acme Co", "email": "ops@acme.com", "avatarUrl": "https://static.natural.com/avatars/acme-co.png", "createdAt": "2026-01-04T15:30:00.000Z", "delegation": { "id": "dlg_550e8400e29b41d4a716446655440000", "status": "ACTIVE", "permissions": [ "payments.read" ], "createdAt": "2026-01-10T12:00:00.000Z", "revokedAt": null }, "agents": [ { "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "name": "Invoice Agent", "handle": "@acme-invoice", "status": "ACTIVE", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000, "perDay": 500000, "perMonth": 2000000 } } ] } }, "meta": { "deleted": true } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payments": { "post": { "operationId": "payments.create", "summary": "Create payment", "description": "Create a payment", "tags": [ "Payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "maxLength": 254, "format": "email", "description": "Email address." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "maxLength": 16, "description": "Phone number." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent_id" ] }, "value": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Natural agent ID (agt_*)." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "handle" ] }, "value": { "type": "string", "maxLength": 62, "description": "Natural handle (@handle or @handle-slug)." } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "PaymentRecipientCounterparty", "description": "Payment recipient. Agent recipients use their preferred wallet or their party's default wallet." }, "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Sender party ID (pty_*). Omit to send from your own wallet; provide for delegated payments on behalf of a customer." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency code." }, "description": { "type": "string", "maxLength": 80, "description": "Payment description. Maximum 80 characters." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Source wallet ID (wal_*). Omit to pay from the sender party's default wallet." } }, "required": [ "amount", "counterparty" ], "additionalProperties": false, "title": "PaymentCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 500000, "currency": "USD", "counterparty": { "type": "party_id", "value": "pty_019cd1798d627ad9bc302511c4f2c115" }, "customerPartyId": "pty_019cd1798d617f65a79cb965dda9eac3", "description": "Payment for Q4 2025 development work" } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "createdAt": { "type": "string", "description": "When this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this payment was last updated." } }, "required": [ "amount", "currency", "status", "description", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "senderAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sending agent, or null when the payment was not sent by an agent." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "senderAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500000, "currency": "USD", "status": "PROCESSING", "description": "Payment for Q4 2025 development work", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "sender": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "senderAgent": { "data": null }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } }, "paymentRequest": { "data": null } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "payments.list", "summary": "List payments", "description": "List sent payments", "tags": [ "Payments" ], "parameters": [ { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "createdAt": { "type": "string", "description": "When this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this payment was last updated." } }, "required": [ "amount", "currency", "status", "description", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "senderAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sending agent, or null when the payment was not sent by an agent." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "senderAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PaymentListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500000, "currency": "USD", "status": "PROCESSING", "description": "Payment for Q4 2025 development work", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "sender": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "senderAgent": { "data": null }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } }, "paymentRequest": { "data": null } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payments/{paymentId}": { "get": { "operationId": "payments.get", "summary": "Get payment", "description": "Get a sent payment", "tags": [ "Payments" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." } }, { "name": "partyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "createdAt": { "type": "string", "description": "When this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this payment was last updated." } }, "required": [ "amount", "currency", "status", "description", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "senderAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sending agent, or null when the payment was not sent by an agent." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "senderAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500000, "currency": "USD", "status": "PROCESSING", "description": "Payment for Q4 2025 development work", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "sender": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "senderAgent": { "data": null }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } }, "paymentRequest": { "data": null } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payments/{paymentId}/cancel": { "post": { "operationId": "payments.cancel", "summary": "Cancel payment", "description": "Cancel a payment before the recipient begins claiming it", "tags": [ "Payments" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "createdAt": { "type": "string", "description": "When this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this payment was last updated." } }, "required": [ "amount", "currency", "status", "description", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "senderAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sending agent, or null when the payment was not sent by an agent." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "senderAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500000, "currency": "USD", "status": "CANCELED", "description": "Payment for Q4 2025 development work", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:35:00Z" }, "relationships": { "sender": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "senderAgent": { "data": null }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } }, "paymentRequest": { "data": null } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/transactions": { "get": { "operationId": "transactions.list", "summary": "List transactions", "description": "List transactions", "tags": [ "Transactions" ], "parameters": [ { "name": "type", "in": "query", "schema": { "enum": [ "payment", "transfer", "all" ], "type": "string", "default": "all", "description": "Filter by transaction type." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "counterpartyPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Restrict results to transactions whose payment counterparty is this party." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "walletId", "in": "query", "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Restrict results to transactions visible through this wallet." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Restrict results to delegated activity performed for this customer, not activity involving it as a payment counterparty." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "delegated", "in": "query", "schema": { "type": "boolean", "description": "When true, return only transactions executed through an agent delegation (your connection-scoped feed)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string", "pattern": "^txn_[0-9a-f]{32}$", "description": "Transaction ID (txn_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "type": "string", "description": "Transaction status." }, "createdAt": { "type": "string", "description": "When this transaction was created." }, "transactionType": { "enum": [ "payment", "transfer" ], "type": "string", "description": "Transaction type." }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Direction relative to your party." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transaction description." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transaction was last updated." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Projected funds-available time, or null for payments and transfers without a projection." } }, "required": [ "amount", "currency", "status", "createdAt", "transactionType", "direction", "description", "updatedAt", "expectedAvailableAt" ], "additionalProperties": false, "title": "TransactionAttributes" }, "relationships": { "type": "object", "properties": { "sourceParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Source party." }, "destinationParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination party." }, "payment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related payment, when accessible." }, "transfer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related transfer, when accessible." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Wallet through which this transaction is visible." } }, "required": [ "sourceParty", "destinationParty" ], "additionalProperties": false, "title": "TransactionRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransactionResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "TransactionListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "transaction", "id": "txn_650e8400e29b41d4a716446655440000", "attributes": { "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Cash in", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:31:00Z", "transactionType": "transfer", "direction": "INBOUND", "expectedAvailableAt": null }, "relationships": { "sourceParty": { "data": null }, "destinationParty": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "transfer": { "data": { "type": "transfer", "id": "trf_650e8400e29b41d4a716446655440000" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/transactions/{transactionId}": { "get": { "operationId": "transactions.get", "summary": "Get transaction", "description": "Get a transaction", "tags": [ "Transactions" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^txn_[0-9a-f]{32}$", "description": "Transaction ID (txn_*)." } }, { "name": "partyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string", "pattern": "^txn_[0-9a-f]{32}$", "description": "Transaction ID (txn_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "type": "string", "description": "Transaction status." }, "createdAt": { "type": "string", "description": "When this transaction was created." }, "transactionType": { "enum": [ "payment", "transfer" ], "type": "string", "description": "Transaction type." }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Direction relative to your party." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transaction description." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transaction was last updated." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Projected funds-available time, or null for payments and transfers without a projection." } }, "required": [ "amount", "currency", "status", "createdAt", "transactionType", "direction", "description", "updatedAt", "expectedAvailableAt" ], "additionalProperties": false, "title": "TransactionAttributes" }, "relationships": { "type": "object", "properties": { "sourceParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Source party." }, "destinationParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination party." }, "payment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related payment, when accessible." }, "transfer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related transfer, when accessible." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Wallet through which this transaction is visible." } }, "required": [ "sourceParty", "destinationParty" ], "additionalProperties": false, "title": "TransactionRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransactionResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "TransactionSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000", "attributes": { "amount": 100000, "currency": "USD", "status": "COMPLETED", "description": "Invoice payment", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:31:00Z", "transactionType": "payment", "direction": "OUTBOUND", "expectedAvailableAt": null }, "relationships": { "sourceParty": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "destinationParty": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440002" } }, "payment": { "data": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/transfers/deposit": { "post": { "operationId": "transfers.initiateDeposit", "summary": "Initiate deposit", "description": "Move funds from a linked bank account into a wallet", "tags": [ "Transfers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 100, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Three-letter currency code. Currently USD." }, "externalAccountId": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Target wallet for the deposit. Defaults to your party's default wallet when omitted." }, "description": { "type": "string", "maxLength": 80, "description": "Memo for the deposit." } }, "required": [ "amount", "externalAccountId" ], "additionalProperties": false, "title": "DepositCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "DepositCreateData" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 50000, "currency": "USD", "externalAccountId": "eac_550e8400e29b41d4a716446655440000", "description": "Wallet top-up" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type." }, "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description." }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account number." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Expected availability time, when known." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available." }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer returned." } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was submitted." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer settled." }, "createdAt": { "type": "string", "description": "When this transfer was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was last updated." } }, "required": [ "type", "amount", "currency", "status", "description", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the transfer." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet for this transfer." }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction for this transfer, when available." } }, "required": [ "party", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_550e8400e29b41d4a716446655440000", "attributes": { "type": "deposit", "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Wallet top-up", "externalAccountDisplayMask": null, "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000" } }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] } }, "/transfers/withdraw": { "post": { "operationId": "transfers.initiateWithdrawal", "summary": "Initiate withdrawal", "description": "Move funds from a wallet to a linked bank account", "tags": [ "Transfers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Three-letter currency code. Currently USD." }, "externalAccountId": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Source wallet for the withdrawal. Defaults to your party's default wallet when omitted." }, "description": { "type": "string", "maxLength": 80, "description": "Memo for the withdrawal." } }, "required": [ "amount", "externalAccountId" ], "additionalProperties": false, "title": "WithdrawCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WithdrawCreateData" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 12500, "currency": "USD", "externalAccountId": "eac_550e8400e29b41d4a716446655440000", "description": "Payout transfer" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type." }, "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description." }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account number." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Expected availability time, when known." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available." }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer returned." } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was submitted." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer settled." }, "createdAt": { "type": "string", "description": "When this transfer was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was last updated." } }, "required": [ "type", "amount", "currency", "status", "description", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the transfer." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet for this transfer." }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction for this transfer, when available." } }, "required": [ "party", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_650e8400e29b41d4a716446655440000", "attributes": { "type": "withdrawal", "amount": 12500, "currency": "USD", "status": "PROCESSING", "description": "Payout transfer", "externalAccountDisplayMask": null, "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000" } }, "transaction": { "data": { "type": "transaction", "id": "txn_650e8400e29b41d4a716446655440000" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] } }, "/transfers/internal": { "post": { "operationId": "transfers.initiateInternal", "summary": "Initiate internal transfer", "description": "Move funds between two wallets", "tags": [ "Transfers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "sourceWalletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Source wallet ID (wal_*)." }, "destWalletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Destination wallet ID (wal_*)." }, "description": { "type": "string", "maxLength": 80, "description": "Transfer description." } }, "required": [ "amount", "sourceWalletId", "destWalletId" ], "additionalProperties": false, "title": "InternalTransferCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "InternalTransferCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "InternalTransferCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 5000, "sourceWalletId": "wal_550e8400e29b41d4a716446655440000", "destWalletId": "wal_7c9e6679e29b41d4a716446655440002", "description": "Sweep to vault" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type." }, "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description." }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account number." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Expected availability time, when known." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available." }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer returned." } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was submitted." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer settled." }, "createdAt": { "type": "string", "description": "When this transfer was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was last updated." } }, "required": [ "type", "amount", "currency", "status", "description", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the transfer." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet for this transfer." }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction for this transfer, when available." } }, "required": [ "party", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "InternalTransferResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_550e8400e29b41d4a716446655440000", "attributes": { "type": "internal", "amount": 5000, "currency": "USD", "status": "PROCESSING", "description": "Sweep to vault", "externalAccountDisplayMask": null, "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": null, "settledAt": null, "createdAt": "2026-01-04T15:30:00Z", "updatedAt": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "externalAccount": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } }, "destWallet": { "data": { "type": "wallet", "id": "wal_7c9e6679e29b41d4a716446655440002" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] } }, "/transfers": { "get": { "operationId": "transfers.list", "summary": "List transfers", "description": "List transfers", "tags": [ "Transfers" ], "parameters": [ { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type." }, "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description." }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account number." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Expected availability time, when known." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available." }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer returned." } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was submitted." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer settled." }, "createdAt": { "type": "string", "description": "When this transfer was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was last updated." } }, "required": [ "type", "amount", "currency", "status", "description", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the transfer." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet for this transfer." }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction for this transfer, when available." } }, "required": [ "party", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "TransferListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "transfer", "id": "trf_550e8400e29b41d4a716446655440000", "attributes": { "type": "deposit", "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Wallet top-up", "externalAccountDisplayMask": null, "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000" } }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/transfers/{transferId}": { "get": { "operationId": "transfers.get", "summary": "Get transfer", "description": "Get a transfer", "tags": [ "Transfers" ], "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$", "description": "Transfer ID (trf_*)." } }, { "name": "partyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type." }, "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description." }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account number." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Expected availability time, when known." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available." }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer returned." } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was submitted." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer settled." }, "createdAt": { "type": "string", "description": "When this transfer was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was last updated." } }, "required": [ "type", "amount", "currency", "status", "description", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the transfer." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet for this transfer." }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction for this transfer, when available." } }, "required": [ "party", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "TransferResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_550e8400e29b41d4a716446655440000", "attributes": { "type": "deposit", "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Wallet top-up", "externalAccountDisplayMask": null, "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000" } }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payment-requests": { "post": { "operationId": "paymentRequests.create", "summary": "Create payment request", "description": "Create a payment request", "tags": [ "PaymentRequests" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Requester party ID (pty_*). Omit to request into your own wallet; provide for delegated payment requests on behalf of a customer." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet (wal_*) that should receive the funds. Omit to use the requester party's default wallet." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency code (currently only USD)." }, "description": { "type": "string", "maxLength": 80, "description": "Free-form description shown to the payer. Maximum 80 characters." }, "payerName": { "type": "string", "maxLength": 32, "description": "Display name of the payer. Maximum 32 characters." }, "payer": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "maxLength": 254, "format": "email", "description": "Email address." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "maxLength": 16, "description": "Phone number." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent_id" ] }, "value": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Natural agent ID (agt_*)." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "handle" ] }, "value": { "type": "string", "maxLength": 62, "description": "Natural handle (@handle or @handle-slug)." } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "PaymentRequestPayer", "description": "Who pays: exactly one typed email, phone, party ID, agent ID, or handle value." } }, "required": [ "amount", "payer" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 2500, "currency": "USD", "description": "Invoice 7", "payerName": "Ada Lovelace", "payer": { "type": "email", "value": "ada@example.com" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The initiating party's composed public handle (@namespace), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "initiatorAgent": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's composed public handle (@namespace-slug), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "Agent that created this payment request, when one did. Otherwise null." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the transaction created by the most recent payment attempt, or null if no attempt yet." }, "createdAt": { "type": "string", "description": "When the payment request was created." }, "updatedAt": { "type": "string", "description": "When the payment request was last updated." } }, "required": [ "amount", "currency", "status", "description", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "initiatorAgent", "paymentLinkUrl", "transactionId", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." } }, "required": [ "requesterParty", "payerParty" ], "additionalProperties": false, "title": "PaymentRequestCreateRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestCreateResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000", "attributes": { "amount": 2500, "currency": "USD", "status": "OPEN", "description": "Invoice 7", "requesterName": null, "requesterEmail": null, "requesterAvatarUrl": null, "requesterHandle": null, "walletName": "Main wallet", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": null, "payerAvatarUrl": null, "payerHandle": null, "payerPartyId": null, "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "initiatorParty": null, "initiatorAgent": null, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "payerParty": { "data": null } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "paymentRequests.list", "summary": "List payment requests", "description": "List outgoing payment requests", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Effective party ID (pty_*) for delegated payment request access." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeCompleted", "in": "query", "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": true, "description": "Whether to include completed payment requests." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeCanceled", "in": "query", "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": false, "description": "Whether to include canceled payment requests." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The initiating party's composed public handle (@namespace), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "initiatorAgent": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's composed public handle (@namespace-slug), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "Agent that created this payment request, when one did. Otherwise null." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the transaction created by the most recent payment attempt, or null if no attempt yet." }, "createdAt": { "type": "string", "description": "When the payment request was created." }, "updatedAt": { "type": "string", "description": "When the payment request was last updated." } }, "required": [ "amount", "currency", "status", "description", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "initiatorAgent", "paymentLinkUrl", "transactionId", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet that receives the funds." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payer agent, or null unless addressed by agent ID or agent handle." }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "requesterParty", "wallet", "payerParty", "payerAgent", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PaymentRequestListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000", "attributes": { "amount": 2500, "currency": "USD", "status": "OPEN", "description": "Invoice 7", "requesterName": "Acme Payments", "requesterEmail": "billing@acmepayments.com", "requesterAvatarUrl": "https://static.natural.com/avatars/acme-payments.png", "requesterHandle": "@acme-payments", "walletName": "Main wallet", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": null, "payerAvatarUrl": null, "payerHandle": null, "payerPartyId": null, "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "initiatorParty": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "name": "Acme Payments", "handle": "@acme-payments" }, "initiatorAgent": { "id": "agt_019cd1798d627ad9bc302511c4f2c115", "name": "Billing Bot", "handle": "@acme-billing" }, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "payerParty": { "data": null }, "payerAgent": { "data": null }, "payment": { "data": null } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payment-requests/incoming": { "get": { "operationId": "paymentRequests.listIncoming", "summary": "List incoming payment requests", "description": "List incoming payment requests", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Effective party ID (pty_*) for delegated payment request access." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The initiating party's composed public handle (@namespace), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "initiatorAgent": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's composed public handle (@namespace-slug), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "Agent that created this payment request, when one did. Otherwise null." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the transaction created by the most recent payment attempt, or null if no attempt yet." }, "createdAt": { "type": "string", "description": "When the payment request was created." }, "updatedAt": { "type": "string", "description": "When the payment request was last updated." } }, "required": [ "amount", "currency", "status", "description", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "initiatorAgent", "paymentLinkUrl", "transactionId", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet that receives the funds." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payer agent, or null unless addressed by agent ID or agent handle." }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "requesterParty", "wallet", "payerParty", "payerAgent", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PaymentRequestListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500, "currency": "USD", "status": "OPEN", "requesterName": "Natural Coffee", "requesterEmail": "billing@natural.test", "requesterAvatarUrl": "https://static.natural.com/avatars/natural-coffee.png", "requesterHandle": "@natural-coffee", "walletName": null, "description": "Invoice 7", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png", "payerHandle": "@ada-lovelace", "payerPartyId": "pty_550e8400e29b41d4a716446655440000", "payerIdentifierType": "party_id", "payerIdentifier": "pty_550e8400e29b41d4a716446655440000", "initiatorParty": null, "initiatorAgent": null, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "payerParty": { "data": { "type": "party", "id": "pty_550e8400e29b41d4a716446655440000" } }, "payerAgent": { "data": null }, "payment": { "data": null } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payment-requests/{paymentRequestId}": { "get": { "operationId": "paymentRequests.get", "summary": "Get payment request", "description": "Get a payment request", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." } }, { "name": "partyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Effective party ID (pty_*) for delegated payment request access." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The initiating party's composed public handle (@namespace), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "initiatorAgent": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's composed public handle (@namespace-slug), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "Agent that created this payment request, when one did. Otherwise null." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the transaction created by the most recent payment attempt, or null if no attempt yet." }, "createdAt": { "type": "string", "description": "When the payment request was created." }, "updatedAt": { "type": "string", "description": "When the payment request was last updated." } }, "required": [ "amount", "currency", "status", "description", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "initiatorAgent", "paymentLinkUrl", "transactionId", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet that receives the funds." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payer agent, or null unless addressed by agent ID or agent handle." }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "requesterParty", "wallet", "payerParty", "payerAgent", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000", "attributes": { "amount": 2500, "currency": "USD", "status": "OPEN", "description": "Invoice 7", "requesterName": "Acme Payments", "requesterEmail": "billing@acmepayments.com", "requesterAvatarUrl": "https://static.natural.com/avatars/acme-payments.png", "requesterHandle": "@acme-payments", "walletName": "Main wallet", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": null, "payerAvatarUrl": null, "payerHandle": null, "payerPartyId": null, "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "initiatorParty": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "name": "Acme Payments", "handle": "@acme-payments" }, "initiatorAgent": { "id": "agt_019cd1798d627ad9bc302511c4f2c115", "name": "Billing Bot", "handle": "@acme-billing" }, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "payerParty": { "data": null }, "payerAgent": { "data": null }, "payment": { "data": null } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payment-requests/{paymentRequestId}/fulfill": { "post": { "operationId": "paymentRequests.fulfill", "summary": "Fulfill payment request", "description": "Fulfill an open payment request from a wallet or a verified linked bank account", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Effective payer party ID (pty_*) for delegated payment request fulfillment." }, "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "paymentSource": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet used to pay." } }, "required": [ "type", "walletId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "external_account" ] }, "externalAccountId": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "Verified linked bank account used to pay." } }, "required": [ "type", "externalAccountId" ], "additionalProperties": false } ], "description": "Source of funds for the payment." } }, "required": [ "paymentSource" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "paymentSource": { "type": "wallet", "walletId": "wal_550e8400e29b41d4a716446655440000" } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "createdAt": { "type": "string", "description": "When this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this payment was last updated." } }, "required": [ "amount", "currency", "status", "description", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "senderAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sending agent, or null when the payment was not sent by an agent." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "senderAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000", "attributes": { "amount": 2500, "currency": "USD", "status": "PROCESSING", "description": "Invoice 7", "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "sender": { "data": { "type": "party", "id": "pty_550e8400e29b41d4a716446655440000" } }, "senderAgent": { "data": null }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "recipientAgent": { "data": null }, "transaction": { "data": null }, "paymentRequest": { "data": { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payment-requests/{paymentRequestId}/decline": { "post": { "operationId": "paymentRequests.decline", "summary": "Decline payment request", "description": "Decline an open incoming payment request", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The initiating party's composed public handle (@namespace), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "initiatorAgent": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's composed public handle (@namespace-slug), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "Agent that created this payment request, when one did. Otherwise null." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the transaction created by the most recent payment attempt, or null if no attempt yet." }, "createdAt": { "type": "string", "description": "When the payment request was created." }, "updatedAt": { "type": "string", "description": "When the payment request was last updated." } }, "required": [ "amount", "currency", "status", "description", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "initiatorAgent", "paymentLinkUrl", "transactionId", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet that receives the funds." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payer agent, or null unless addressed by agent ID or agent handle." }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "requesterParty", "wallet", "payerParty", "payerAgent", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500, "currency": "USD", "status": "DECLINED", "requesterName": "Natural Coffee", "requesterEmail": "billing@natural.test", "requesterAvatarUrl": "https://static.natural.com/avatars/natural-coffee.png", "requesterHandle": "@natural-coffee", "walletName": null, "description": "Invoice 7", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png", "payerHandle": "@ada-lovelace", "payerPartyId": "pty_550e8400e29b41d4a716446655440000", "payerIdentifierType": "party_id", "payerIdentifier": "pty_550e8400e29b41d4a716446655440000", "initiatorParty": null, "initiatorAgent": null, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "payerParty": { "data": { "type": "party", "id": "pty_550e8400e29b41d4a716446655440000" } }, "payerAgent": { "data": null }, "payment": { "data": null } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payment-requests/{paymentRequestId}/cancel": { "post": { "operationId": "paymentRequests.cancel", "summary": "Cancel payment request", "description": "Cancel an open outgoing payment request", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The initiating party's composed public handle (@namespace), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "initiatorAgent": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, "name": { "type": "string" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent's composed public handle (@namespace-slug), or null when it has none." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "Agent that created this payment request, when one did. Otherwise null." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the transaction created by the most recent payment attempt, or null if no attempt yet." }, "createdAt": { "type": "string", "description": "When the payment request was created." }, "updatedAt": { "type": "string", "description": "When the payment request was last updated." } }, "required": [ "amount", "currency", "status", "description", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "initiatorAgent", "paymentLinkUrl", "transactionId", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet that receives the funds." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payer agent, or null unless addressed by agent ID or agent handle." }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "requesterParty", "wallet", "payerParty", "payerAgent", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500, "currency": "USD", "status": "CANCELED", "requesterName": "Natural Coffee", "requesterEmail": "billing@natural.test", "requesterAvatarUrl": "https://static.natural.com/avatars/natural-coffee.png", "requesterHandle": "@natural-coffee", "walletName": "Main wallet", "description": "Invoice 7", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png", "payerHandle": "@ada-lovelace", "payerPartyId": "pty_550e8400e29b41d4a716446655440000", "payerIdentifierType": "party_id", "payerIdentifier": "pty_550e8400e29b41d4a716446655440000", "initiatorParty": null, "initiatorAgent": null, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "payerParty": { "data": { "type": "party", "id": "pty_550e8400e29b41d4a716446655440000" } }, "payerAgent": { "data": null }, "payment": { "data": null } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/approvals": { "get": { "operationId": "approvals.list", "summary": "List approvals", "description": "List approvals", "tags": [ "Approvals" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string", "description": "Approval status to filter by. Defaults to pending." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID (apr_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string", "description": "Approval status." }, "target": { "type": "object", "properties": { "type": { "enum": [ "payment", "deposit", "withdrawal" ], "type": "string", "description": "Type of operation under approval." }, "id": { "type": "string", "description": "ID of the operation under approval." } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Operation that needs approval." }, "payment": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "amount", "currency" ], "additionalProperties": false }, { "type": "null" } ], "description": "Amount of the operation under review. Null when the underlying amount is unavailable." }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Type of limit that was exceeded." }, "limitAmount": { "type": "integer", "description": "Configured limit amount in cents." }, "actualAmount": { "type": "integer", "description": "Amount that exceeded the limit, in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review." }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party (pty_*) whose wallet a delegated payment spends from." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the customer party, or null when unresolved." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Customer the agent is spending on behalf of, or null when the approval isn't a delegated payment." }, "createdAt": { "type": "string", "description": "When the approval was created." }, "updatedAt": { "type": "string", "description": "When the approval was last updated." }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the approval was resolved." } }, "required": [ "status", "target", "payment", "reasons", "customer", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "approval", "id": "apr_550e8400e29b41d4a716446655440000", "attributes": { "status": "pending", "target": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440001" }, "payment": { "amount": 500000, "currency": "USD" }, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "customer": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z", "resolvedAt": null } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/approvals/{approvalId}": { "get": { "operationId": "approvals.get", "summary": "Get approval", "description": "Get an approval", "tags": [ "Approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apr_[0-9a-f]{32}$", "description": "Approval ID (apr_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID (apr_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string", "description": "Approval status." }, "target": { "type": "object", "properties": { "type": { "enum": [ "payment", "deposit", "withdrawal" ], "type": "string", "description": "Type of operation under approval." }, "id": { "type": "string", "description": "ID of the operation under approval." } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Operation that needs approval." }, "payment": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "amount", "currency" ], "additionalProperties": false }, { "type": "null" } ], "description": "Amount of the operation under review. Null when the underlying amount is unavailable." }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Type of limit that was exceeded." }, "limitAmount": { "type": "integer", "description": "Configured limit amount in cents." }, "actualAmount": { "type": "integer", "description": "Amount that exceeded the limit, in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review." }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party (pty_*) whose wallet a delegated payment spends from." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the customer party, or null when unresolved." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Customer the agent is spending on behalf of, or null when the approval isn't a delegated payment." }, "createdAt": { "type": "string", "description": "When the approval was created." }, "updatedAt": { "type": "string", "description": "When the approval was last updated." }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the approval was resolved." } }, "required": [ "status", "target", "payment", "reasons", "customer", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "approval", "id": "apr_550e8400e29b41d4a716446655440000", "attributes": { "status": "pending", "target": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440001" }, "payment": { "amount": 500000, "currency": "USD" }, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "customer": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z", "resolvedAt": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/approvals/{approvalId}/approve": { "post": { "operationId": "approvals.approve", "summary": "Approve payment or transfer", "description": "Approve the payment or transfer under review", "tags": [ "Approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apr_[0-9a-f]{32}$", "description": "Approval ID (apr_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID (apr_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string", "description": "Approval status." }, "target": { "type": "object", "properties": { "type": { "enum": [ "payment", "deposit", "withdrawal" ], "type": "string", "description": "Type of operation under approval." }, "id": { "type": "string", "description": "ID of the operation under approval." } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Operation that needs approval." }, "payment": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "amount", "currency" ], "additionalProperties": false }, { "type": "null" } ], "description": "Amount of the operation under review. Null when the underlying amount is unavailable." }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Type of limit that was exceeded." }, "limitAmount": { "type": "integer", "description": "Configured limit amount in cents." }, "actualAmount": { "type": "integer", "description": "Amount that exceeded the limit, in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review." }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party (pty_*) whose wallet a delegated payment spends from." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the customer party, or null when unresolved." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Customer the agent is spending on behalf of, or null when the approval isn't a delegated payment." }, "createdAt": { "type": "string", "description": "When the approval was created." }, "updatedAt": { "type": "string", "description": "When the approval was last updated." }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the approval was resolved." } }, "required": [ "status", "target", "payment", "reasons", "customer", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "approval", "id": "apr_550e8400e29b41d4a716446655440000", "attributes": { "status": "approved", "target": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440001" }, "payment": { "amount": 500000, "currency": "USD" }, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "customer": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:45:00.000Z", "resolvedAt": "2026-01-04T15:45:00.000Z" } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/approvals/{approvalId}/deny": { "post": { "operationId": "approvals.deny", "summary": "Deny payment or transfer", "description": "Deny the payment or transfer under review", "tags": [ "Approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apr_[0-9a-f]{32}$", "description": "Approval ID (apr_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID (apr_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string", "description": "Approval status." }, "target": { "type": "object", "properties": { "type": { "enum": [ "payment", "deposit", "withdrawal" ], "type": "string", "description": "Type of operation under approval." }, "id": { "type": "string", "description": "ID of the operation under approval." } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Operation that needs approval." }, "payment": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "amount", "currency" ], "additionalProperties": false }, { "type": "null" } ], "description": "Amount of the operation under review. Null when the underlying amount is unavailable." }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Type of limit that was exceeded." }, "limitAmount": { "type": "integer", "description": "Configured limit amount in cents." }, "actualAmount": { "type": "integer", "description": "Amount that exceeded the limit, in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review." }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party (pty_*) whose wallet a delegated payment spends from." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the customer party, or null when unresolved." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Customer the agent is spending on behalf of, or null when the approval isn't a delegated payment." }, "createdAt": { "type": "string", "description": "When the approval was created." }, "updatedAt": { "type": "string", "description": "When the approval was last updated." }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the approval was resolved." } }, "required": [ "status", "target", "payment", "reasons", "customer", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "approval", "id": "apr_550e8400e29b41d4a716446655440000", "attributes": { "status": "denied", "target": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440001" }, "payment": { "amount": 500000, "currency": "USD" }, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "customer": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:45:00.000Z", "resolvedAt": "2026-01-04T15:45:00.000Z" } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/party-invitations": { "post": { "operationId": "invitations.create", "summary": "Create party invitations", "description": "Invite people to join the party. Available for business parties.", "tags": [ "Invitations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "invitations": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 80, "format": "email", "description": "Email address to invite." }, "role": { "enum": [ "ADMIN", "MEMBER" ], "type": "string", "description": "Role to assign on acceptance." } }, "required": [ "email", "role" ], "additionalProperties": false, "title": "InvitationItem", "description": "Single invitation in batch request." }, "description": "List of invitations to create (max 100)." } }, "required": [ "invitations" ], "additionalProperties": false, "title": "InvitationCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "InvitationCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateInvitationsInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "invitations": [ { "email": "engineer@velocitylogistics.com", "role": "MEMBER" }, { "email": "cfo@velocitylogistics.com", "role": "ADMIN" } ] } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invitation" ] }, "id": { "type": "string", "pattern": "^inv_[0-9a-f]{32}$", "description": "Invitation ID (inv_*)." }, "attributes": { "type": "object", "properties": { "email": { "type": "string", "description": "Invitee email address." }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER" ], "type": "string", "description": "Role assigned on acceptance." }, "status": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Invitation status." }, "expiresAt": { "type": "string", "description": "When this invitation expires." }, "createdAt": { "type": "string", "description": "When this invitation was created." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this invitation was accepted." } }, "required": [ "email", "role", "status", "expiresAt", "createdAt", "acceptedAt" ], "additionalProperties": false, "title": "InvitationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "InvitationResource" }, "description": "Successfully created invitation resources." }, "meta": { "type": "object", "properties": { "failed": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address that could not be invited." }, "error": { "type": "string", "description": "Reason the invitation failed." } }, "required": [ "email", "error" ], "additionalProperties": false, "title": "InvitationResult", "description": "Failed invitation result." }, "description": "Failed invitation attempts with error details." } }, "required": [ "failed" ], "additionalProperties": false, "title": "CreateInvitationsMeta", "description": "Batch invitation metadata." } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CreateInvitationsOutput" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "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 } } ], "meta": { "failed": [ { "email": "cfo@velocitylogistics.com", "error": "User is already a member of this party" } ] } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "invitations.list", "summary": "List party invitations", "description": "List party invitations", "tags": [ "Invitations" ], "parameters": [ { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party to filter by; only your own party is accepted." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "email", "in": "query", "schema": { "type": "string", "maxLength": 254, "description": "Filter by email." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Filter by status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invitation" ] }, "id": { "type": "string", "pattern": "^inv_[0-9a-f]{32}$", "description": "Invitation ID (inv_*)." }, "attributes": { "type": "object", "properties": { "email": { "type": "string", "description": "Invitee email address." }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER" ], "type": "string", "description": "Role assigned on acceptance." }, "status": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Invitation status." }, "expiresAt": { "type": "string", "description": "When this invitation expires." }, "createdAt": { "type": "string", "description": "When this invitation was created." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this invitation was accepted." } }, "required": [ "email", "role", "status", "expiresAt", "createdAt", "acceptedAt" ], "additionalProperties": false, "title": "InvitationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "InvitationResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "InvitationListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "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 } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/party-invitations/{invitationId}": { "delete": { "operationId": "invitations.revoke", "summary": "Revoke party invitation", "description": "Revoke a pending party invitation", "tags": [ "Invitations" ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "description": "Invitation ID (inv_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invitation" ] }, "id": { "type": "string", "pattern": "^inv_[0-9a-f]{32}$", "description": "Invitation ID (inv_*)." }, "attributes": { "type": "object", "properties": { "email": { "type": "string", "description": "Invitee email address." }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER" ], "type": "string", "description": "Role assigned on acceptance." }, "status": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Invitation status." }, "expiresAt": { "type": "string", "description": "When this invitation expires." }, "createdAt": { "type": "string", "description": "When this invitation was created." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this invitation was accepted." } }, "required": [ "email", "role", "status", "expiresAt", "createdAt", "acceptedAt" ], "additionalProperties": false, "title": "InvitationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "InvitationResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "InvitationRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "invitation", "id": "inv_019cd4a832f37c4b8a1d63e94b7c8d12", "attributes": { "email": "engineer@velocitylogistics.com", "role": "MEMBER", "status": "REVOKED", "expiresAt": "2026-01-11T15:30:00Z", "createdAt": "2026-01-04T15:30:00Z", "acceptedAt": null } }, "meta": { "deleted": true } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/parties/me": { "get": { "operationId": "parties.get", "summary": "Get party", "description": "Get the current party", "tags": [ "Parties" ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "type": { "type": "string", "enum": [ "party" ] }, "attributes": { "type": "object", "properties": { "partyType": { "enum": [ "PERSON", "ORG" ], "type": "string", "description": "Party type." }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal business name for `ORG` parties." }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal first name for `PERSON` parties." }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal last name for `PERSON` parties." }, "status": { "enum": [ "PROVISIONAL", "ACTIVE", "SUSPENDED", "INACTIVE" ], "type": "string", "description": "Party status." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the party was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the party was last updated." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for the party." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle (e.g. \"@acme\"), or null when the party has not claimed one." }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public URL of the party's avatar image, or null when none is set." }, "persona": { "anyOf": [ { "enum": [ "INDIVIDUAL", "DEVELOPER" ], "type": "string" }, { "type": "null" } ], "description": "Party persona, when available." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary contact email." }, "primaryPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary phone number." }, "addressLine1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Street address line 1." }, "addressCity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City." }, "addressState": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province." }, "addressPostalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Postal or ZIP code." }, "addressCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code (e.g., US)." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this party (usr_*)." } }, "required": [ "partyType", "legalName", "firstName", "lastName", "status", "createdAt", "updatedAt", "displayName", "handle", "avatarUrl", "persona", "email", "primaryPhone", "addressLine1", "addressCity", "addressState", "addressPostalCode", "addressCountry", "createdBy" ], "additionalProperties": false, "title": "PartyAttributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false, "title": "PartyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "type": "party", "attributes": { "partyType": "ORG", "legalName": "Natural AI, Inc", "firstName": null, "lastName": null, "status": "ACTIVE", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "displayName": "Natural", "handle": "@natural", "avatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2024-01-15_ab12cd34ef56ab90.webp", "persona": "DEVELOPER", "email": "contact@natural.com", "primaryPhone": "+1-555-555-0100", "addressLine1": "123 Main Street", "addressCity": "San Francisco", "addressState": "CA", "addressPostalCode": "94105", "addressCountry": "US", "createdBy": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "patch": { "operationId": "parties.update", "summary": "Update party", "description": "Update the current party", "tags": [ "Parties" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "displayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ], "description": "New display name. For person parties the display name is derived from the legal name and this field is ignored. Pass null to clear it." } }, "additionalProperties": false, "title": "PartyUpdateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "PartyUpdateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "UpdateOwnPartyInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "displayName": "Natural Inc." } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "type": { "type": "string", "enum": [ "party" ] }, "attributes": { "type": "object", "properties": { "partyType": { "enum": [ "PERSON", "ORG" ], "type": "string", "description": "Party type." }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal business name for `ORG` parties." }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal first name for `PERSON` parties." }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal last name for `PERSON` parties." }, "status": { "enum": [ "PROVISIONAL", "ACTIVE", "SUSPENDED", "INACTIVE" ], "type": "string", "description": "Party status." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the party was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the party was last updated." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for the party." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle (e.g. \"@acme\"), or null when the party has not claimed one." }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public URL of the party's avatar image, or null when none is set." }, "persona": { "anyOf": [ { "enum": [ "INDIVIDUAL", "DEVELOPER" ], "type": "string" }, { "type": "null" } ], "description": "Party persona, when available." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary contact email." }, "primaryPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary phone number." }, "addressLine1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Street address line 1." }, "addressCity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City." }, "addressState": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province." }, "addressPostalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Postal or ZIP code." }, "addressCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code (e.g., US)." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this party (usr_*)." } }, "required": [ "partyType", "legalName", "firstName", "lastName", "status", "createdAt", "updatedAt", "displayName", "handle", "avatarUrl", "persona", "email", "primaryPhone", "addressLine1", "addressCity", "addressState", "addressPostalCode", "addressCountry", "createdBy" ], "additionalProperties": false, "title": "PartyAttributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false, "title": "PartyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "type": "party", "attributes": { "partyType": "ORG", "legalName": "Natural AI, Inc", "firstName": null, "lastName": null, "status": "ACTIVE", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "displayName": "Natural Inc.", "handle": "@natural", "avatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2024-01-15_ab12cd34ef56ab90.webp", "persona": "DEVELOPER", "email": "contact@natural.com", "primaryPhone": "+1-555-555-0100", "addressLine1": "123 Main Street", "addressCity": "San Francisco", "addressState": "CA", "addressPostalCode": "94105", "addressCountry": "US", "createdBy": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] } }, "/parties/me/members": { "get": { "operationId": "parties.listMembers", "summary": "List party members", "description": "List active members of the party. Available for business parties.", "tags": [ "Parties" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "pattern": "^usr_[0-9a-f]{32}$", "description": "User ID (usr_*)." }, "attributes": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "ID of the party this membership belongs to." }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER" ], "type": "string", "description": "User's role in the party." }, "status": { "enum": [ "ACTIVE", "REVOKED", "DELETED" ], "type": "string", "description": "Membership status." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the membership was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the membership was last updated. Currently mirrors createdAt." }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name of the user." }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name of the user." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address of the user." } }, "required": [ "partyId", "role", "status", "createdAt", "updatedAt", "firstName", "lastName", "email" ], "title": "UserMemberAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "UserMemberResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PartyMembersListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "user", "id": "usr_019cd1798d657de5b5fed4198cb9fac0", "attributes": { "partyId": "pty_019cd1798d617f65a79cb965dda9eac3", "role": "MEMBER", "status": "ACTIVE", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z", "firstName": "Eric", "lastName": "Smith", "email": "eric@natural.com" } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/parties/{partyId}/compliance": { "get": { "operationId": "parties.getCompliance", "summary": "Get party compliance", "description": "Get a party's current compliance status", "tags": [ "Parties" ], "parameters": [ { "name": "partyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Compliance case ID." }, "type": { "type": "string", "enum": [ "compliance_case" ] }, "attributes": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party this compliance status applies to." }, "status": { "enum": [ "preparingSubmission", "submitted", "actionRequired", "approved", "rejected" ], "type": "string", "description": "Current compliance status." } }, "required": [ "partyId", "status" ], "additionalProperties": false, "title": "ComplianceCaseAttributes" }, "version": { "type": "integer", "description": "Version of the compliance case." } }, "required": [ "id", "type", "attributes", "version" ], "additionalProperties": false, "title": "ComplianceCaseResource" }, { "type": "null" } ], "description": "Current canonical compliance case, or null when no current case exists." } }, "required": [ "data" ], "additionalProperties": false, "title": "PartyComplianceResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "cpc_00000000000000000000000000000001", "type": "compliance_case", "attributes": { "partyId": "pty_019cd1798d617f65a79cb965dda9eac3", "status": "approved" }, "version": 7 } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/parties/me/handle": { "put": { "operationId": "parties.setHandle", "summary": "Set party handle", "description": "Set or rename your party's handle; it can never be cleared", "tags": [ "Parties" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "handle": { "type": "string", "maxLength": 30, "pattern": "^[a-z0-9][a-z0-9._]{1,28}[a-z0-9]$", "description": "Party handle without the \"@\" prefix, such as \"acme\". Renames the handle; it cannot be cleared. For 14 days after a rename, only the same party can reclaim the released name." } }, "required": [ "handle" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "SetPartyHandleInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "handle": "natural" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "type": { "type": "string", "enum": [ "party" ] }, "attributes": { "type": "object", "properties": { "partyType": { "enum": [ "PERSON", "ORG" ], "type": "string", "description": "Party type." }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal business name for `ORG` parties." }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal first name for `PERSON` parties." }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal last name for `PERSON` parties." }, "status": { "enum": [ "PROVISIONAL", "ACTIVE", "SUSPENDED", "INACTIVE" ], "type": "string", "description": "Party status." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the party was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the party was last updated." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for the party." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle (e.g. \"@acme\"), or null when the party has not claimed one." }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public URL of the party's avatar image, or null when none is set." }, "persona": { "anyOf": [ { "enum": [ "INDIVIDUAL", "DEVELOPER" ], "type": "string" }, { "type": "null" } ], "description": "Party persona, when available." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary contact email." }, "primaryPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary phone number." }, "addressLine1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Street address line 1." }, "addressCity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City." }, "addressState": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province." }, "addressPostalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Postal or ZIP code." }, "addressCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code (e.g., US)." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this party (usr_*)." } }, "required": [ "partyType", "legalName", "firstName", "lastName", "status", "createdAt", "updatedAt", "displayName", "handle", "avatarUrl", "persona", "email", "primaryPhone", "addressLine1", "addressCity", "addressState", "addressPostalCode", "addressCountry", "createdBy" ], "additionalProperties": false, "title": "PartyAttributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false, "title": "PartyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "type": "party", "attributes": { "partyType": "ORG", "legalName": "Natural AI, Inc", "firstName": null, "lastName": null, "status": "ACTIVE", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "displayName": "Natural", "handle": "@natural", "avatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2024-01-15_ab12cd34ef56ab90.webp", "persona": "DEVELOPER", "email": "contact@natural.com", "primaryPhone": "+1-555-555-0100", "addressLine1": "123 Main Street", "addressCity": "San Francisco", "addressState": "CA", "addressPostalCode": "94105", "addressCountry": "US", "createdBy": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] } }, "/parties/me/limits": { "get": { "operationId": "parties.getLimits", "summary": "Get party approval limits", "description": "Get the party's approval limits", "tags": [ "Parties" ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "partyLimitPolicy" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-transaction spend cap in cents, or null when unset." }, "perDay": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Daily (UTC) spend cap in cents, or null when unset." }, "perMonth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Calendar-month (UTC) spend cap in cents, or null when unset." } }, "required": [ "perTransaction", "perDay", "perMonth" ], "additionalProperties": false, "title": "PartyLimits" }, { "type": "null" } ], "description": "Party-wide spend caps applied to money movement, or null when no limits are set." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currency of the configured limits, or null when none are set." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the limits were last updated." } }, "required": [ "limits", "currency", "updatedAt" ], "additionalProperties": false, "title": "PartyLimitPolicyAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "PartyLimitPolicyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartyLimitPolicyResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "partyLimitPolicy", "id": "pty_019cd1798d617f65a79cb965dda9eac3", "attributes": { "limits": { "perTransaction": 250000, "perDay": 1000000, "perMonth": null }, "currency": "USD", "updatedAt": "2026-01-04T15:30:00Z" } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "put": { "operationId": "parties.setLimits", "summary": "Set party approval limits", "description": "Set the party's approval limits", "tags": [ "Parties" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents. Pass null or omit to clear it." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents. Pass null or omit to clear it." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents. Pass null or omit to clear it." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency of the configured limits." } }, "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "SetPartyLimitsInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "perTransaction": 250000, "perDay": 1000000, "perMonth": null, "currency": "USD" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "partyLimitPolicy" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-transaction spend cap in cents, or null when unset." }, "perDay": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Daily (UTC) spend cap in cents, or null when unset." }, "perMonth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Calendar-month (UTC) spend cap in cents, or null when unset." } }, "required": [ "perTransaction", "perDay", "perMonth" ], "additionalProperties": false, "title": "PartyLimits" }, { "type": "null" } ], "description": "Party-wide spend caps applied to money movement, or null when no limits are set." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currency of the configured limits, or null when none are set." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the limits were last updated." } }, "required": [ "limits", "currency", "updatedAt" ], "additionalProperties": false, "title": "PartyLimitPolicyAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "PartyLimitPolicyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartyLimitPolicyResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "partyLimitPolicy", "id": "pty_019cd1798d617f65a79cb965dda9eac3", "attributes": { "limits": { "perTransaction": 250000, "perDay": 1000000, "perMonth": null }, "currency": "USD", "updatedAt": "2026-01-04T15:30:00Z" } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "delete": { "operationId": "parties.disableLimits", "summary": "Disable party approval limits", "description": "Disable all approval limits for the party", "tags": [ "Parties" ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "partyLimitPolicy" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-transaction spend cap in cents, or null when unset." }, "perDay": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Daily (UTC) spend cap in cents, or null when unset." }, "perMonth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Calendar-month (UTC) spend cap in cents, or null when unset." } }, "required": [ "perTransaction", "perDay", "perMonth" ], "additionalProperties": false, "title": "PartyLimits" }, { "type": "null" } ], "description": "Party-wide spend caps applied to money movement, or null when no limits are set." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currency of the configured limits, or null when none are set." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the limits were last updated." } }, "required": [ "limits", "currency", "updatedAt" ], "additionalProperties": false, "title": "PartyLimitPolicyAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "PartyLimitPolicyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartyLimitPolicyResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "partyLimitPolicy", "id": "pty_019cd1798d617f65a79cb965dda9eac3", "attributes": { "limits": null, "currency": null, "updatedAt": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] } }, "/parties/me/members/{userId}": { "delete": { "operationId": "parties.removeMember", "summary": "Remove party member", "description": "Remove a member from the party", "tags": [ "Parties" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^usr_[0-9a-f]{32}$", "description": "User ID to remove from party." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "pattern": "^usr_[0-9a-f]{32}$", "description": "ID of the removed user." } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "RemovedMemberResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "user", "id": "usr_019cd1798d657de5b5fed4198cb9fac0" }, "meta": { "deleted": true } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/wallets": { "get": { "operationId": "wallets.list", "summary": "List wallets", "description": "List wallets", "tags": [ "Wallets" ], "parameters": [ { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID for delegated wallet lookup." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet readiness status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the party's default for unnamed operations." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Wallet creation time, when available." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount currently available to spend or withdraw in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total unclaimed product-payment amount in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." } }, "required": [ "bankName" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "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 wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false, "title": "WalletListMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WalletListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000", "attributes": { "status": "active", "walletType": "standard", "isDefault": true, "createdAt": "2026-01-04T15:30:00Z", "displayName": "Operating", "description": null, "balance": { "available": 120000, "total": 125000, "currency": "USD" }, "claims": { "amount": 125000, "count": 2 }, "depositInstructions": { "bankName": "Bridge Financial" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, { "type": "wallet", "id": "wal_650e8400e29b41d4a716446655440000", "attributes": { "status": "active", "walletType": "vault", "isDefault": false, "createdAt": "2026-01-04T15:30:00Z", "displayName": "Vault", "description": null, "balance": { "available": 500000, "total": 500000, "currency": "USD" }, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Bridge Financial" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "operationId": "wallets.create", "summary": "Create wallet", "description": "Create a standard wallet", "tags": [ "Wallets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Wallet name." }, "description": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "User-facing wallet description." } }, "required": [ "displayName" ], "additionalProperties": false, "title": "WalletCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WalletCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "displayName": "Payroll", "description": "Dedicated wallet for payroll runs" } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet readiness status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the party's default for unnamed operations." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Wallet creation time, when available." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount currently available to spend or withdraw in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total unclaimed product-payment amount in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." } }, "required": [ "bankName" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "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 wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_650e8400e29b41d4a716446655440001", "attributes": { "status": "active", "walletType": "standard", "isDefault": false, "createdAt": "2026-01-04T15:30:00Z", "displayName": "Payroll", "description": "Dedicated wallet for payroll runs", "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Bridge Financial" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] } }, "/wallets/{walletId}": { "get": { "operationId": "wallets.get", "summary": "Get wallet", "description": "Get a wallet", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet readiness status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the party's default for unnamed operations." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Wallet creation time, when available." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount currently available to spend or withdraw in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total unclaimed product-payment amount in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." } }, "required": [ "bankName" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "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 wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000", "attributes": { "status": "active", "walletType": "standard", "isDefault": true, "createdAt": "2026-01-04T15:30:00Z", "displayName": "Operating", "description": null, "balance": { "available": 120000, "total": 125000, "currency": "USD" }, "claims": { "amount": 125000, "count": 2 }, "depositInstructions": { "bankName": "Bridge Financial" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "patch": { "operationId": "wallets.update", "summary": "Update wallet", "description": "Update wallet metadata", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Wallet name." }, "description": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "User-facing wallet description." } }, "additionalProperties": false, "title": "WalletUpdateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WalletUpdateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletUpdateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "displayName": "Operating (US)", "description": "Primary USD operating wallet" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet readiness status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the party's default for unnamed operations." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Wallet creation time, when available." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount currently available to spend or withdraw in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total unclaimed product-payment amount in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." } }, "required": [ "bankName" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "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 wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000", "attributes": { "status": "active", "walletType": "standard", "isDefault": true, "createdAt": "2026-01-04T15:30:00Z", "displayName": "Operating (US)", "description": "Primary USD operating wallet", "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Bridge Financial" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/wallets/{walletId}/default": { "post": { "operationId": "wallets.setDefault", "summary": "Set default wallet", "description": "Make a wallet the default. Payments sent to the party's email, phone number, or handle land in the default wallet.", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet readiness status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the party's default for unnamed operations." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Wallet creation time, when available." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount currently available to spend or withdraw in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total unclaimed product-payment amount in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." } }, "required": [ "bankName" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "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 wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000", "attributes": { "status": "active", "walletType": "standard", "isDefault": true, "createdAt": "2026-01-04T15:30:00Z", "displayName": "Operating", "description": null, "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Bridge Financial" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/wallets/{walletId}/freeze": { "post": { "operationId": "wallets.freeze", "summary": "Freeze wallet", "description": "Freeze a wallet", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet readiness status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the party's default for unnamed operations." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Wallet creation time, when available." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount currently available to spend or withdraw in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total unclaimed product-payment amount in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." } }, "required": [ "bankName" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "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 wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000", "attributes": { "status": "frozen", "walletType": "standard", "isDefault": false, "createdAt": "2026-01-04T15:30:00Z", "displayName": "Operating", "description": null, "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Bridge Financial" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/wallets/{walletId}/unfreeze": { "post": { "operationId": "wallets.unfreeze", "summary": "Unfreeze wallet", "description": "Unfreeze a wallet that was frozen through the API", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet readiness status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the party's default for unnamed operations." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Wallet creation time, when available." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount currently available to spend or withdraw in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total unclaimed product-payment amount in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." } }, "required": [ "bankName" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "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 wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000", "attributes": { "status": "active", "walletType": "standard", "isDefault": false, "createdAt": "2026-01-04T15:30:00Z", "displayName": "Operating", "description": null, "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Bridge Financial" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/wallets/{walletId}/agents": { "post": { "operationId": "wallets.attachAgent", "summary": "Grant agent access to wallet", "description": "Grant an agent access to a wallet", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent to attach to this wallet." } }, "required": [ "agentId" ], "additionalProperties": false, "title": "WalletAgentAttachAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WalletAgentAttachData" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletAgentAttachRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "agentId": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null if none is configured." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this agent was created." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent last authenticated, or null if it has never authenticated." } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" }, "meta": { "type": "object", "properties": { "walletAccess": { "type": "object", "properties": { "isDefault": { "type": "boolean", "description": "Whether this is the agent's default wallet." }, "attachedAt": { "type": "string", "format": "date-time", "description": "When the agent was attached to this wallet." } }, "required": [ "isDefault", "attachedAt" ], "additionalProperties": false, "title": "WalletAgentAccessMeta", "description": "The agent's access to this wallet." } }, "required": [ "walletAccess" ], "additionalProperties": false, "title": "WalletAgentMeta" } }, "required": [ "type", "id", "attributes", "relationships", "meta" ], "additionalProperties": false, "title": "WalletAgentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletAgentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "attributes": { "name": "Carrier Payment Agent v2.1", "description": "Autonomous agent that pays delivery carriers", "handle": "@natural-carrier_payments", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "lastActiveAt": "2026-01-05T09:12:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } }, "meta": { "walletAccess": { "isDefault": true, "attachedAt": "2026-01-05T10:00:00Z" } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "get": { "operationId": "wallets.listAgents", "summary": "List wallet agents", "description": "List agents granted access to a wallet", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null if none is configured." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this agent was created." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent last authenticated, or null if it has never authenticated." } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" }, "meta": { "type": "object", "properties": { "walletAccess": { "type": "object", "properties": { "isDefault": { "type": "boolean", "description": "Whether this is the agent's default wallet." }, "attachedAt": { "type": "string", "format": "date-time", "description": "When the agent was attached to this wallet." } }, "required": [ "isDefault", "attachedAt" ], "additionalProperties": false, "title": "WalletAgentAccessMeta", "description": "The agent's access to this wallet." } }, "required": [ "walletAccess" ], "additionalProperties": false, "title": "WalletAgentMeta" } }, "required": [ "type", "id", "attributes", "relationships", "meta" ], "additionalProperties": false, "title": "WalletAgentResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WalletAgentListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "attributes": { "name": "Carrier Payment Agent v2.1", "description": "Autonomous agent that pays delivery carriers", "handle": "@natural-carrier_payments", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "lastActiveAt": "2026-01-05T09:12:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } }, "meta": { "walletAccess": { "isDefault": true, "attachedAt": "2026-01-05T10:00:00Z" } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/wallets/{walletId}/agents/{agentId}/default": { "post": { "operationId": "wallets.setAgentDefaultWallet", "summary": "Set agent default wallet", "description": "Make this wallet the default for the attached agent", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null if none is configured." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this agent was created." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent last authenticated, or null if it has never authenticated." } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" }, "meta": { "type": "object", "properties": { "walletAccess": { "type": "object", "properties": { "isDefault": { "type": "boolean", "description": "Whether this is the agent's default wallet." }, "attachedAt": { "type": "string", "format": "date-time", "description": "When the agent was attached to this wallet." } }, "required": [ "isDefault", "attachedAt" ], "additionalProperties": false, "title": "WalletAgentAccessMeta", "description": "The agent's access to this wallet." } }, "required": [ "walletAccess" ], "additionalProperties": false, "title": "WalletAgentMeta" } }, "required": [ "type", "id", "attributes", "relationships", "meta" ], "additionalProperties": false, "title": "WalletAgentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletAgentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "attributes": { "name": "Carrier Payment Agent v2.1", "description": "Autonomous agent that pays delivery carriers", "handle": "@natural-carrier_payments", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "lastActiveAt": "2026-01-05T09:12:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } }, "meta": { "walletAccess": { "isDefault": true, "attachedAt": "2026-01-05T10:00:00Z" } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/wallets/{walletId}/agents/{agentId}": { "delete": { "operationId": "wallets.detachAgent", "summary": "Detach agent from wallet", "description": "Detach an agent from a wallet", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "WalletAgentDetachedResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WalletAgentDetachResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f" }, "meta": { "deleted": true } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] } }, "/external-accounts": { "get": { "operationId": "externalAccounts.list", "summary": "List external accounts", "description": "List linked external accounts", "tags": [ "External Accounts" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "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" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ExternalAccountListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000", "attributes": { "bankName": "Chase", "accountName": "Business Checking", "accountType": "checking", "lastFour": "6789", "status": "active", "connectionStatus": "active", "createdAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/external-accounts/{externalAccountId}": { "get": { "operationId": "externalAccounts.get", "summary": "Get external account", "description": "Get a linked external account", "tags": [ "External Accounts" ], "parameters": [ { "name": "externalAccountId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "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" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000", "attributes": { "bankName": "Chase", "accountName": "Business Checking", "accountType": "checking", "lastFour": "6789", "status": "active", "connectionStatus": "active", "createdAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "delete": { "operationId": "externalAccounts.remove", "summary": "Remove external account", "description": "Remove a linked external account", "tags": [ "External Accounts" ], "parameters": [ { "name": "externalAccountId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "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" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ExternalAccountDeleteResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000", "attributes": { "bankName": null, "accountName": null, "accountType": null, "lastFour": "", "status": "disabled", "connectionStatus": "active", "createdAt": "0001-01-01T00:00:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, "meta": { "deleted": true } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api-keys": { "get": { "operationId": "apiKeys.list", "summary": "List API keys", "description": "List API keys", "tags": [ "API Keys" ], "parameters": [ { "name": "status", "in": "query", "schema": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Filter by status (ACTIVE or REVOKED)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "API key ID (apy_*)." }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_prod_abc123`." }, "name": { "type": "string", "description": "API key name." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Authorized scopes." }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment." }, "status": { "enum": [ "ACTIVE", "REVOKED", "UNKNOWN" ], "type": "string", "description": "API key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy" ], "additionalProperties": false, "title": "ApiKeyAttributes" }, "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 API key." } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ApiKeyListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "apiKey", "id": "apy_550e8400e29b41d4a716446655440000", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, { "type": "apiKey", "id": "apy_7f8e4d0012a64ef3bca4d21e44a5c001", "attributes": { "apiKeyPrefix": "sk_ntl_prod_Ab12Cd34Ef56Gh78", "name": "Reporting (read-only)", "scopes": [ "payments.read" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "operationId": "apiKeys.create", "summary": "Create API key", "description": "Create an API key. The secret is returned only once.", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32, "description": "API key name." }, "scopes": { "type": "array", "minItems": 1, "items": { "enum": [ "party.read", "party.update", "invite.read", "invite.create", "invite.update", "invite.delete", "membership.create", "membership.read", "membership.update", "membership.delete", "payments.create", "payments.read", "external_accounts.create", "wallets.read", "wallets.create", "wallets.update", "wallets.delete", "wallets.fund", "wallets.withdraw", "delegations.read", "delegations.create", "delegations.update", "delegations.delete", "api_keys.read", "api_keys.create", "api_keys.delete", "agents.read", "agents.create", "agents.update", "agents.delete", "disputes.read", "disputes.create" ], "type": "string" }, "default": [ "party.read", "party.update", "invite.read", "invite.create", "invite.update", "invite.delete", "membership.create", "membership.read", "membership.update", "membership.delete", "payments.create", "payments.read", "external_accounts.create", "wallets.read", "wallets.create", "wallets.update", "wallets.delete", "wallets.fund", "wallets.withdraw", "delegations.read", "delegations.create", "delegations.update", "delegations.delete", "api_keys.read", "api_keys.create", "api_keys.delete", "agents.read", "agents.create", "agents.update", "agents.delete", "disputes.read", "disputes.create" ], "description": "Permission scopes for the API key." } }, "required": [ "name" ], "additionalProperties": false, "title": "ApiKeyCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "ApiKeyCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateApiKeyInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ] } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "API key ID (apy_*)." }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_prod_abc123`." }, "name": { "type": "string", "description": "API key name." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Authorized scopes." }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment." }, "status": { "enum": [ "ACTIVE", "REVOKED", "UNKNOWN" ], "type": "string", "description": "API key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "apiKey": { "type": "string", "description": "Full API key secret. Returned only once." } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "apiKey" ], "additionalProperties": false, "title": "ApiKeyCreateResultAttributes" }, "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 API key." } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "ApiKeyCreateSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "apiKey", "id": "apy_550e8400e29b41d4a716446655440000", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null, "apiKey": "sk_ntl_prod_sxHp_FRoRTnDEmEHD8FKVJg7P0d3UJMSWCtzQe9GBxk" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] } }, "/api-keys/{keyId}": { "get": { "operationId": "apiKeys.get", "summary": "Get API key", "description": "Get an API key", "tags": [ "API Keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "description": "API key ID (apy_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "API key ID (apy_*)." }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_prod_abc123`." }, "name": { "type": "string", "description": "API key name." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Authorized scopes." }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment." }, "status": { "enum": [ "ACTIVE", "REVOKED", "UNKNOWN" ], "type": "string", "description": "API key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy" ], "additionalProperties": false, "title": "ApiKeyAttributes" }, "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 API key." } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "ApiKeySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "apiKey", "id": "apy_550e8400e29b41d4a716446655440000", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "delete": { "operationId": "apiKeys.revoke", "summary": "Revoke API key", "description": "Revoke an API key", "tags": [ "API Keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "description": "API key ID (apy_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "API key ID (apy_*)." }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_prod_abc123`." }, "name": { "type": "string", "description": "API key name." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Authorized scopes." }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment." }, "status": { "enum": [ "ACTIVE", "REVOKED", "UNKNOWN" ], "type": "string", "description": "API key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy" ], "additionalProperties": false, "title": "ApiKeyAttributes" }, "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 API key." } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ApiKeyRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "apiKey", "id": "apy_550e8400e29b41d4a716446655440000", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "REVOKED", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": "2026-01-05T10:00:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": "usr_550e8400e29b41d4a716446655440000" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, "meta": { "deleted": true } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agent-keys": { "get": { "operationId": "agentKeys.list", "summary": "List agent keys", "description": "List agent keys", "tags": [ "Agent Keys" ], "parameters": [ { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Filter to keys bound to this agent (agt_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agentKey" ] }, "id": { "type": "string", "description": "Agent key ID (agk_*)." }, "attributes": { "type": "object", "properties": { "agentKeyPrefix": { "type": "string", "description": "Non-secret prefix of the agent key, e.g. `ak_ntl_prod_abc123`." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Status (ACTIVE or REVOKED)." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key stops authenticating, or null if it has no scheduled expiration." } }, "required": [ "agentKeyPrefix", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "expiresAt" ], "additionalProperties": false, "title": "AgentKeyAttributes" }, "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 agent key." }, "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Agent this key is bound to." } }, "required": [ "party", "agent" ], "additionalProperties": false, "title": "AgentKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentKeyListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agentKey", "id": "agk_550e8400e29b41d4a716446655440000", "attributes": { "agentKeyPrefix": "ak_ntl_prod_sxHp_FRoRTnDEmEH", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null, "expiresAt": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } }, { "type": "agentKey", "id": "agk_7f8e4d0012a64ef3bca4d21e44a5c001", "attributes": { "agentKeyPrefix": "ak_ntl_prod_Ab12Cd34Ef56Gh78", "status": "ACTIVE", "createdAt": "2026-01-05T09:00:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null, "expiresAt": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "operationId": "agentKeys.create", "summary": "Create agent key", "description": "Create an agent key for an agent. The secret is returned only once.", "tags": [ "Agent Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "additionalProperties": false, "title": "AgentKeyCreateAttributes" }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Existing agent the key is bound to." } }, "required": [ "agent" ], "additionalProperties": false, "title": "AgentKeyCreateRelationships" } }, "required": [ "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateAgentKeyInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": {}, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agentKey" ] }, "id": { "type": "string", "description": "Agent key ID (agk_*)." }, "attributes": { "type": "object", "properties": { "agentKeyPrefix": { "type": "string", "description": "Non-secret prefix of the agent key, e.g. `ak_ntl_prod_abc123`." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Status (ACTIVE or REVOKED)." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key stops authenticating, or null if it has no scheduled expiration." }, "agentKey": { "type": "string", "description": "Full agent key secret. Returned only once." } }, "required": [ "agentKeyPrefix", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "expiresAt", "agentKey" ], "additionalProperties": false, "title": "AgentKeyCreateResultAttributes" }, "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 agent key." }, "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Agent this key is bound to." } }, "required": [ "party", "agent" ], "additionalProperties": false, "title": "AgentKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentKeyCreateSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentKey", "id": "agk_550e8400e29b41d4a716446655440000", "attributes": { "agentKeyPrefix": "ak_ntl_prod_sxHp_FRoRTnDEmEH", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null, "expiresAt": null, "agentKey": "ak_ntl_prod_sxHp_FRoRTnDEmEHD8FKVJg7P0d3UJMSWCtzQe9GBxk" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] } }, "/agent-keys/{keyId}": { "delete": { "operationId": "agentKeys.revoke", "summary": "Revoke agent key", "description": "Revoke an agent key immediately without issuing a replacement. Other active keys for the same agent keep working.", "tags": [ "Agent Keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agk_[0-9a-f]{32}$", "description": "Agent key ID (agk_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agentKey" ] }, "id": { "type": "string", "description": "Agent key ID (agk_*)." }, "attributes": { "type": "object", "properties": { "agentKeyPrefix": { "type": "string", "description": "Non-secret prefix of the agent key, e.g. `ak_ntl_prod_abc123`." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Status (ACTIVE or REVOKED)." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key stops authenticating, or null if it has no scheduled expiration." } }, "required": [ "agentKeyPrefix", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "expiresAt" ], "additionalProperties": false, "title": "AgentKeyAttributes" }, "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 agent key." }, "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Agent this key is bound to." } }, "required": [ "party", "agent" ], "additionalProperties": false, "title": "AgentKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentKeyRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentKey", "id": "agk_550e8400e29b41d4a716446655440000", "attributes": { "agentKeyPrefix": "ak_ntl_prod_sxHp_FRoRTnDEmEH", "status": "REVOKED", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": "2026-01-06T10:00:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": "usr_550e8400e29b41d4a716446655440000", "expiresAt": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } }, "meta": { "deleted": true } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agent-keys/{keyId}/rotate": { "post": { "operationId": "agentKeys.rotate", "summary": "Rotate agent key", "description": "Generate a replacement agent key.", "tags": [ "Agent Keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agk_[0-9a-f]{32}$", "description": "Agent key ID (agk_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "expiresInSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "Grace period in seconds for the previous key (0 = immediate cutover, max 86400)." } }, "required": [ "expiresInSeconds" ], "additionalProperties": false, "title": "AgentKeyRotateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "AgentKeyRotateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "RotateAgentKeyInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "expiresInSeconds": 86400 } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agentKey" ] }, "id": { "type": "string", "description": "Agent key ID (agk_*)." }, "attributes": { "type": "object", "properties": { "agentKeyPrefix": { "type": "string", "description": "Non-secret prefix of the agent key, e.g. `ak_ntl_prod_abc123`." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Status (ACTIVE or REVOKED)." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key stops authenticating, or null if it has no scheduled expiration." }, "agentKey": { "type": "string", "description": "Full agent key secret. Returned only once." }, "previousKeyExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the previous key stops authenticating, or null for immediate cutover." } }, "required": [ "agentKeyPrefix", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "expiresAt", "agentKey", "previousKeyExpiresAt" ], "additionalProperties": false, "title": "AgentKeyRotateResultAttributes" }, "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 agent key." }, "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Agent this key is bound to." } }, "required": [ "party", "agent" ], "additionalProperties": false, "title": "AgentKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyRotateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentKeyRotateSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentKey", "id": "agk_7f8e4d0012a64ef3bca4d21e44a5c001", "attributes": { "agentKeyPrefix": "ak_ntl_prod_Ab12Cd34Ef56Gh78", "status": "ACTIVE", "createdAt": "2026-01-06T10:00:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null, "expiresAt": null, "agentKey": "ak_ntl_prod_Ab12Cd34Ef56Gh78mN90Pq12Rs34Tu56Vw78Xy90Za12Bc34", "previousKeyExpiresAt": "2026-01-07T10:00:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/webhooks": { "post": { "operationId": "webhooks.create", "summary": "Create webhook", "description": "Create a webhook endpoint. The signing secret is returned only once.", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "maxLength": 100, "description": "Webhook description." }, "enabledEvents": { "type": "array", "minItems": 1, "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types to subscribe to; use \"*\" to subscribe to all event types." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Tags applied to this webhook." } }, "required": [ "url", "enabledEvents" ], "additionalProperties": false, "title": "WebhookCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WebhookCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateWebhookInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "tags": { "env": "prod", "team": "payments" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "description": "Webhook description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status." }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types this webhook listens to." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this webhook was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this webhook was last updated." }, "signingSecret": { "type": "string", "description": "Webhook signing secret. Returned only once." } }, "required": [ "url", "description", "status", "enabledEvents", "tags", "createdAt", "updatedAt", "signingSecret" ], "additionalProperties": false, "title": "WebhookCreateResultAttributes" }, "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 webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WebhookCreateSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z", "signingSecret": "whsec_3JZ8aQpL2vR7nXdE5fW1cT0yK6mB4hG9" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "webhooks.list", "summary": "List webhooks", "description": "List webhook endpoints", "tags": [ "Webhooks" ], "parameters": [ { "name": "status", "in": "query", "schema": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Filter by status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "description": "Webhook description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status." }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types this webhook listens to." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this webhook was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this webhook was last updated." } }, "required": [ "url", "description", "status", "enabledEvents", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes" }, "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 webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WebhookListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, { "type": "webhook", "id": "whk_0192def4abc1789034567890abcdef34", "attributes": { "url": "https://example.com/webhooks/funding", "description": "External account notifications", "status": "DISABLED", "enabledEvents": [ "external_account.connected" ], "tags": { "env": "prod" }, "createdAt": "2026-03-10T09:00:00Z", "updatedAt": "2026-03-14T18:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/webhooks/{webhookId}": { "get": { "operationId": "webhooks.get", "summary": "Get webhook", "description": "Get a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "description": "Webhook ID (whk_*)." } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "description": "Webhook description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status." }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types this webhook listens to." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this webhook was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this webhook was last updated." } }, "required": [ "url", "description", "status", "enabledEvents", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes" }, "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 webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WebhookSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "patch": { "operationId": "webhooks.update", "summary": "Update webhook", "description": "Update a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "description": "Webhook ID (whk_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "New webhook endpoint URL." }, "description": { "type": "string", "maxLength": 100, "description": "New description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "New status." }, "enabledEvents": { "type": "array", "minItems": 1, "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types to subscribe to; use \"*\" to subscribe to all event types." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "description": "Tag updates. Pass null to remove a key." } }, "additionalProperties": false, "title": "WebhookUpdateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WebhookUpdateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "UpdateWebhookInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "description": "Production webhook for wallet, party, and delegation events", "status": "DISABLED", "enabledEvents": [ "wallet.created", "party.updated" ], "tags": { "env": "staging", "team": null } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "description": "Webhook description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status." }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types this webhook listens to." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this webhook was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this webhook was last updated." } }, "required": [ "url", "description", "status", "enabledEvents", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes" }, "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 webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WebhookSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet, party, and delegation events", "status": "DISABLED", "enabledEvents": [ "wallet.created", "party.updated" ], "tags": { "env": "staging" }, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-17T08:15:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "delete": { "operationId": "webhooks.remove", "summary": "Delete webhook", "description": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "description": "Webhook ID (whk_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "description": "Webhook description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status." }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types this webhook listens to." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this webhook was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this webhook was last updated." } }, "required": [ "url", "description", "status", "enabledEvents", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes" }, "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 webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WebhookDeleteResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, "meta": { "deleted": true } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/webhooks/{webhookId}/rotate-secret": { "post": { "operationId": "webhooks.rotateSecret", "summary": "Rotate webhook signing secret", "description": "Generate a new signing secret.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "description": "Webhook ID (whk_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "expiresInSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "Grace period in seconds for the previous secret (0 = immediate cutover, max 86400)." } }, "required": [ "expiresInSeconds" ], "additionalProperties": false, "title": "RotateSecretAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "RotateSecretData" } }, "required": [ "data" ], "additionalProperties": false, "title": "RotateSecretInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "expiresInSeconds": 3600 } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "signingSecret": { "type": "string", "description": "New webhook signing secret. Returned only once." }, "previousSecretExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the previous secret expires, or null for immediate cutover." } }, "required": [ "signingSecret", "previousSecretExpiresAt" ], "additionalProperties": false, "title": "RotateSecretResponseAttributes" }, "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 webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "RotateSecretResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "RotateSecretResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "signingSecret": "whsec_7Yp2KdN9wL4xT8rE1cV5bM0aQ6hJ3fG8", "previousSecretExpiresAt": "2026-03-17T09:15:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/events": { "get": { "operationId": "events.list", "summary": "List events", "description": "List events", "tags": [ "Events" ], "parameters": [ { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "eventType", "in": "query", "schema": { "enum": [ "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string", "description": "Filter by event type. Required when partyId names another party." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "maxLength": 64, "format": "date-time", "description": "Return events created after this timestamp." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "maxLength": 64, "format": "date-time", "description": "Return events created before this timestamp." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "description": "Event ID (evt_*)." }, "attributes": { "type": "object", "properties": { "eventType": { "enum": [ "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string", "description": "Type of event." }, "resourceId": { "type": "string", "description": "ID of the resource that triggered the event." }, "resourceType": { "type": "string", "description": "Type of the resource (e.g. wallet, payment)." }, "payload": { "type": "object", "properties": { "object": { "description": "Point-in-time resource snapshot." } }, "additionalProperties": {}, "description": "Event payload containing the resource snapshot. Additional keys may be added in the future." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this event was created." } }, "required": [ "eventType", "resourceId", "resourceType", "payload", "createdAt" ], "additionalProperties": false, "title": "EventAttributes" }, "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 event." } }, "required": [ "party" ], "additionalProperties": false, "title": "EventRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "EventResource" } }, "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" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "event", "id": "evt_0192abc1def2789034567890abcdef12", "attributes": { "eventType": "wallet.created", "resourceId": "wal_7c9e6679e29b41d4a716446655440001", "resourceType": "wallet", "payload": { "object": { "partyId": "pty_7c9e6679e29b41d4a716446655440001", "walletType": "standard", "status": "active", "displayName": "My Wallet", "currency": "usd", "freezeDetails": null, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "version": 1 } }, "createdAt": "2026-03-16T12:00:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/events/{eventId}": { "get": { "operationId": "events.get", "summary": "Get event", "description": "Get an event", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "description": "Event ID (evt_*)." } }, { "name": "partyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 36, "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ] }, "description": "Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "description": "Event ID (evt_*)." }, "attributes": { "type": "object", "properties": { "eventType": { "enum": [ "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string", "description": "Type of event." }, "resourceId": { "type": "string", "description": "ID of the resource that triggered the event." }, "resourceType": { "type": "string", "description": "Type of the resource (e.g. wallet, payment)." }, "payload": { "type": "object", "properties": { "object": { "description": "Point-in-time resource snapshot." } }, "additionalProperties": {}, "description": "Event payload containing the resource snapshot. Additional keys may be added in the future." }, "createdAt": { "type": "string", "format": "date-time", "description": "When this event was created." } }, "required": [ "eventType", "resourceId", "resourceType", "payload", "createdAt" ], "additionalProperties": false, "title": "EventAttributes" }, "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 event." } }, "required": [ "party" ], "additionalProperties": false, "title": "EventRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "EventResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "event", "id": "evt_0192abc1def2789034567890abcdef12", "attributes": { "eventType": "wallet.created", "resourceId": "wal_7c9e6679e29b41d4a716446655440001", "resourceType": "wallet", "payload": { "object": { "partyId": "pty_7c9e6679e29b41d4a716446655440001", "walletType": "standard", "status": "active", "displayName": "My Wallet", "currency": "usd", "freezeDetails": null, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "version": 1 } }, "createdAt": "2026-03-16T12:00:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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 } }, "required": [ "code", "detail", "status", "meta" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "errors": [ { "code": "conflict", "detail": "The request conflicts with the current resource state.", "status": "409", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "422": { "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": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } } }, "tags": [ { "name": "Agents", "description": "Agent management" }, { "name": "Customers", "description": "Customer management" }, { "name": "Payments", "description": "Payment management" }, { "name": "Transactions", "description": "Transaction activity and history" }, { "name": "Transfers", "description": "Deposits and withdrawals" }, { "name": "PaymentRequests", "description": "Payment request management" }, { "name": "Approvals", "description": "Approval review" }, { "name": "Invitations", "description": "Party invitation management" }, { "name": "Parties", "description": "Party and organization management" }, { "name": "Wallets", "description": "Wallet management" }, { "name": "External Accounts", "description": "Linked external bank accounts" }, { "name": "API Keys", "description": "API key management" }, { "name": "Agent Keys", "description": "Agent key management" }, { "name": "Webhooks", "description": "Webhook endpoint management" }, { "name": "Events", "description": "Webhook event log" } ] }