---
title: "List customer invitations"
method: GET
path: "/customers/invitations"
tags: ["Customers"]
---

# List customer invitations

`GET /customers/invitations`

List pending invitations addressed to specific customers

## Query parameters

- `cursor` string — Cursor from the previous page.
- `limit` integer — Maximum results per page.

## Headers

- `X-Agent-ID` string, nullable
- `X-Instance-ID` string, nullable

## Response `200`

Successful Response

- object
  - `data` object[], required
    - `type` 'customerInvitation', required
    - `id` string, required — Recipient email.
    - `attributes` object, required
      - `status` string, required — Invitation status.
      - `party` object, nullable, required — Customer party, or null if they haven't signed up yet.
        - `id` string, required — Customer party ID (pty_*).
        - `name` string, required — Customer name.
        - `email` string, nullable, required — Email address.
        - `avatarUrl` string, uri, nullable, required — Public avatar URL, or null if none is set.
        - `createdAt` string, date-time, nullable, required — When the customer was created.
      - `email` string, required — Recipient email.
      - `createdAt` string, date-time, required — When the invitation was created.
      - `agentInvitations` object[], required — Agent invitations sent to this recipient.
        - `invitationId` string, required — Invitation ID (adi_*).
        - `agent` object, required — Invited agent.
          - `id` string, required — Agent ID (agt_*).
          - `name` string, nullable, required — Agent name.
          - `handle` string, nullable, required — The agent's composed public handle (@namespace-slug), or null when it has none.
        - `permissions` string[], required — Permissions requested for this agent.
        - `url` string, uri, required — Invitation URL. Natural sends it automatically for email invitations; deliver it yourself for phone invitations.
        - `createdAt` string, date-time, required — When the invitation was created.
        - `expiresAt` string, date-time, nullable, required — When the invitation expires, or null if it does not expire.
        - `tags` object, required — Metadata visible to anyone who can read the resource.
  - `meta` object, required
    - `pagination` object, required
      - `hasMore` boolean, required — Whether more results are available.
      - `nextCursor` string, nullable, required — Cursor for the next page, or null when there are no more results.

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — 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.
- `409` — Conflict
- `422` — Validation Error
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

---

[API](https://skmtc.net/natural/apis/natural-api.md) · [All operations](https://skmtc.net/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/natural/natural-api/versions/9561339ea461/schema)