> ## Documentation Index > Fetch the complete documentation index at: https://docs.natural.com/llms.txt > Use this file to discover all available pages before exploring further. # Invite customers > Invite customers to connect with your agents. ## OpenAPI ````yaml /api-reference/openapi.json post /customers/invitations openapi: 3.1.1 info: title: Natural API version: 0.2.0 description: >- Natural's payments API for autonomous agents. **Base URL:** `https://api.natural.co` Agents and coding assistants should prefer the hosted MCP server at `https://mcp.natural.co` when an MCP-aware host runs the agent, the Natural CLI for terminal/CI workflows, and the official SDKs for application runtimes they own. Use direct HTTP only for explicit low-level integrations, unsupported SDK gaps, or infrastructure work where REST is required. For support: support@natural.co servers: - url: https://api.natural.co description: Production security: [] tags: - name: Agents description: Agent management - name: Customers description: Customer management - name: Counterparties description: Counterparty management - name: Payments description: Payment operations - name: Transactions description: Transaction activity and history operations - name: Transfers description: Deposit and withdrawal operations - name: PaymentRequests description: Payment-request management - name: Approvals description: Approval review operations - name: Invitations description: Party invitation management - name: Identity description: Caller identity introspection - name: Parties description: Party and organization management - name: Wallets description: Wallet balance, deposits, withdrawals, and external accounts - 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 access paths: /customers/invitations: post: tags: - Customers summary: Invite customers description: Invite customers to connect with your agents. operationId: customers.createInvitations parameters: - name: X-Agent-ID in: header required: false schema: anyOf: - type: string - type: 'null' description: Agent ID (agt_xxx) identifying which agent is making the request. - name: X-Instance-ID in: header required: false schema: anyOf: - type: string maxLength: 1024 - type: 'null' description: >- Required when X-Agent-ID is present. Session or conversation ID for agent observability. 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 format: email description: Email address required: - type - value additionalProperties: false - type: object properties: type: type: string enum: - phone value: type: string description: Phone number in E.164 format 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. Each recipient gets one invitation per agent. agents: type: array minItems: 1 maxItems: 50 items: type: object properties: agentId: type: string pattern: ^agt_[0-9a-f]{32}$ description: Agent ID 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, 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 format: date-time description: >- When the invitation expires. Defaults to 7 days from now. tags: type: object propertyNames: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9_]+$ additionalProperties: type: string minLength: 1 maxLength: 256 description: Tags applied to every invitation in this request required: - recipients - agents additionalProperties: false description: Customer invitation creation attributes required: - attributes additionalProperties: false description: Resource object 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: description: Resource type type: string enum: - agentDelegationInvitation id: type: string pattern: ^adi_[0-9a-f]{32}$ description: Invitation ID 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: >- Shareable URL where the recipient reviews and accepts the invitation. Also sent in the invitation email; for phone invitations, deliver it yourself. 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 cap, integer cents (USD). 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, accounting for expiry 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: >- Custom metadata tags. Visible to any party authorized to 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: description: Resource 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: description: Resource 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 the invitation was accepted on (null until accept) 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 format: email description: Email address required: - type - value additionalProperties: false - type: object properties: type: type: string enum: - phone value: type: string description: Phone number in E.164 format 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: The recipient that failed reason: type: string description: Why the whole recipient batch failed required: - recipient - reason additionalProperties: false description: Recipients where the invitation 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.co/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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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: A request value is invalid. 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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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: 'email: Invalid email address' 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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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 parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name 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: [] components: securitySchemes: HTTPBearer: type: http scheme: bearer ````