Invite many customers to one agent

curl --request POST \
  --url https://api.natural.co/agents/{agentId}/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "data": {
    "attributes": {
      "recipients": [
        {
          "type": "email",
          "value": "ops@example.com"
        },
        {
          "type": "phone",
          "value": "+14155550123"
        },
        {
          "type": "party_id",
          "value": "pty_4a8c9823f39c42a5b817556766551112"
        }
      ],
      "permissions": [
        "payments.create",
        "payments.read"
      ],
      "limits": {
        "perTransaction": 100000
      },
      "expiresAt": "2026-01-18T12:00:00.000Z"
    }
  }
}
'

{
  "data": [
    {
      "type": "customerInvitation",
      "id": "adi_550e8400e29b41d4a716446655440000",
      "attributes": {
        "recipient": {
          "type": "email",
          "value": "ops@example.com"
        },
        "status": "PENDING",
        "permissions": [
          "payments.create",
          "payments.read"
        ],
        "limits": {
          "perTransaction": 100000
        },
        "expiresAt": "2026-01-18T12:00:00.000Z",
        "createdAt": "2026-01-11T12:00:00.000Z",
        "updatedAt": "2026-01-11T12:00:00.000Z"
      },
      "relationships": {
        "agent": {
          "data": {
            "type": "agent",
            "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
            "attributes": {
              "name": "Carrier Payment Agent",
              "description": "Autonomous agent that pays delivery carriers",
              "status": "ACTIVE"
            }
          }
        },
        "customerParty": {
          "data": null
        }
      }
    },
    {
      "type": "customerInvitation",
      "id": "adi_650e8400e29b41d4a716446655440000",
      "attributes": {
        "recipient": {
          "type": "phone",
          "value": "+14155550123"
        },
        "status": "PENDING",
        "permissions": [
          "payments.create",
          "payments.read"
        ],
        "limits": {
          "perTransaction": 100000
        },
        "expiresAt": "2026-01-18T12:00:00.000Z",
        "createdAt": "2026-01-11T12:00:00.000Z",
        "updatedAt": "2026-01-11T12:00:00.000Z"
      },
      "relationships": {
        "agent": {
          "data": {
            "type": "agent",
            "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
            "attributes": {
              "name": "Carrier Payment Agent",
              "description": "Autonomous agent that pays delivery carriers",
              "status": "ACTIVE"
            }
          }
        },
        "customerParty": {
          "data": null
        }
      }
    },
    {
      "type": "customerInvitation",
      "id": "adi_750e8400e29b41d4a716446655440000",
      "attributes": {
        "recipient": {
          "type": "party_id",
          "value": "pty_4a8c9823f39c42a5b817556766551112"
        },
        "status": "PENDING",
        "permissions": [
          "payments.create",
          "payments.read"
        ],
        "limits": {
          "perTransaction": 100000
        },
        "expiresAt": "2026-01-18T12:00:00.000Z",
        "createdAt": "2026-01-11T12:00:00.000Z",
        "updatedAt": "2026-01-11T12:00:00.000Z"
      },
      "relationships": {
        "agent": {
          "data": {
            "type": "agent",
            "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
            "attributes": {
              "name": "Carrier Payment Agent",
              "description": "Autonomous agent that pays delivery carriers",
              "status": "ACTIVE"
            }
          }
        },
        "customerParty": {
          "data": {
            "type": "party",
            "id": "pty_4a8c9823f39c42a5b817556766551112"
          }
        }
      }
    }
  ],
  "meta": {
    "emailFailures": []
  }
}

Customer Invitations

Invite many customers to one agent

Send delegation invitations from one specific agent (the agentId in the path) to one or more customers. Each recipient receives their own email and consents to this single agent independently. The agentId is fixed; the recipients list varies. Use this when onboarding a batch of customers to a single agent (for example, rolling out an Invoicing Agent to all your existing customers). To invite one customer to multiple agents in a single consent moment, use POST /agents/invitations instead.

POST

agents

{agentId}

customers

Invite many customers to one agent

curl --request POST \
  --url https://api.natural.co/agents/{agentId}/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "data": {
    "attributes": {
      "recipients": [
        {
          "type": "email",
          "value": "ops@example.com"
        },
        {
          "type": "phone",
          "value": "+14155550123"
        },
        {
          "type": "party_id",
          "value": "pty_4a8c9823f39c42a5b817556766551112"
        }
      ],
      "permissions": [
        "payments.create",
        "payments.read"
      ],
      "limits": {
        "perTransaction": 100000
      },
      "expiresAt": "2026-01-18T12:00:00.000Z"
    }
  }
}
'

{
  "data": [
    {
      "type": "customerInvitation",
      "id": "adi_550e8400e29b41d4a716446655440000",
      "attributes": {
        "recipient": {
          "type": "email",
          "value": "ops@example.com"
        },
        "status": "PENDING",
        "permissions": [
          "payments.create",
          "payments.read"
        ],
        "limits": {
          "perTransaction": 100000
        },
        "expiresAt": "2026-01-18T12:00:00.000Z",
        "createdAt": "2026-01-11T12:00:00.000Z",
        "updatedAt": "2026-01-11T12:00:00.000Z"
      },
      "relationships": {
        "agent": {
          "data": {
            "type": "agent",
            "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
            "attributes": {
              "name": "Carrier Payment Agent",
              "description": "Autonomous agent that pays delivery carriers",
              "status": "ACTIVE"
            }
          }
        },
        "customerParty": {
          "data": null
        }
      }
    },
    {
      "type": "customerInvitation",
      "id": "adi_650e8400e29b41d4a716446655440000",
      "attributes": {
        "recipient": {
          "type": "phone",
          "value": "+14155550123"
        },
        "status": "PENDING",
        "permissions": [
          "payments.create",
          "payments.read"
        ],
        "limits": {
          "perTransaction": 100000
        },
        "expiresAt": "2026-01-18T12:00:00.000Z",
        "createdAt": "2026-01-11T12:00:00.000Z",
        "updatedAt": "2026-01-11T12:00:00.000Z"
      },
      "relationships": {
        "agent": {
          "data": {
            "type": "agent",
            "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
            "attributes": {
              "name": "Carrier Payment Agent",
              "description": "Autonomous agent that pays delivery carriers",
              "status": "ACTIVE"
            }
          }
        },
        "customerParty": {
          "data": null
        }
      }
    },
    {
      "type": "customerInvitation",
      "id": "adi_750e8400e29b41d4a716446655440000",
      "attributes": {
        "recipient": {
          "type": "party_id",
          "value": "pty_4a8c9823f39c42a5b817556766551112"
        },
        "status": "PENDING",
        "permissions": [
          "payments.create",
          "payments.read"
        ],
        "limits": {
          "perTransaction": 100000
        },
        "expiresAt": "2026-01-18T12:00:00.000Z",
        "createdAt": "2026-01-11T12:00:00.000Z",
        "updatedAt": "2026-01-11T12:00:00.000Z"
      },
      "relationships": {
        "agent": {
          "data": {
            "type": "agent",
            "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
            "attributes": {
              "name": "Carrier Payment Agent",
              "description": "Autonomous agent that pays delivery carriers",
              "status": "ACTIVE"
            }
          }
        },
        "customerParty": {
          "data": {
            "type": "party",
            "id": "pty_4a8c9823f39c42a5b817556766551112"
          }
        }
      }
    }
  ],
  "meta": {
    "emailFailures": []
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

required

Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned.

X-Agent-ID

string | null

Agent ID (agt_xxx) identifying which agent is making the request.

X-Instance-ID

string | null

Required when X-Agent-ID is present. Session or conversation ID for agent observability.

Maximum string length: 1024

Path Parameters

agentId

string

required

Agent ID

Pattern: ^agt_[0-9a-f]{32}$

Body

application/json

data

object

required

Resource object

Show child attributes

Response

Successful Response

data

AgentCustomerInvitationResource · object[]

required

Created customer invitation resources

Show child attributes