---
title: "List invitations"
method: GET
path: "/v1/invitations"
---

# List invitations

`GET /v1/invitations`

List partner invitations for this project.

## Query parameters

- `status` 'pending' | 'in_progress' | 'completed' | 'expired' | 'cancelled' | 'failed' — Current status of the partner invitation. `failed` means the client started the connection and it did not finish (they cancelled Meta's dialog, denied a permission, or abandoned the tab). A failed invitation is still usable: the same link can be retried, and it moves back to `in_progress` when the client tries again.
- `limit` integer
- `cursor` string

## Response `200`

List of invitations.

- object
  - `items` Invitation[], required
    - `id` string, required
    - `url` string, required — Full URL to share with the client.
    - `token` string, required — Unique invitation token.
    - `clientName` string, nullable
    - `clientEmail` string, nullable
    - `clientPhone` string, nullable
    - `phoneNumberId` string, nullable — ID of a pre-assigned Zavu phone number for WhatsApp registration. Always null for `messenger` invitations.
    - `connectionType` 'whatsapp_waba' | 'messenger' — Which Meta channel the client connects: `whatsapp_waba` (official WhatsApp Cloud API via embedded signup) or `messenger` (a Facebook Page's Messenger inbox, including Marketplace chats).
    - `status` 'pending' | 'in_progress' | 'completed' | 'expired' | 'cancelled' | 'failed', required — Current status of the partner invitation. `failed` means the client started the connection and it did not finish (they cancelled Meta's dialog, denied a permission, or abandoned the tab). A failed invitation is still usable: the same link can be retried, and it moves back to `in_progress` when the client tries again.
    - `senderId` string, nullable — ID of the sender created when invitation is completed.
    - `connectedAccount` object, nullable — The account the client linked, populated once the invitation is `completed`. Null before that. Use it to show the partner what was connected without fetching the sender.
      - `channel` 'whatsapp' | 'messenger', required
      - `id` string, required — Provider-side identifier: the WhatsApp phone number ID, or the Facebook Page ID.
      - `name` string, nullable — Display name of the connected account: the WhatsApp verified name, or the Facebook Page name.
    - `failureReason` string, nullable — Stable code for why the last attempt failed, present when `status` is `failed`. Values include `fb_cancelled` (client closed Meta's dialog), `fb_not_authorized` (permission denied), `signup_abandoned` (started but never finished), `meta_no_pages` (the client administers no Facebook Page), and `internal_error`. Treat unknown codes as a generic failure.
    - `failedAt` string, date-time, nullable
    - `expiresAt` string, date-time, required
    - `viewedAt` string, date-time, nullable
    - `startedAt` string, date-time, nullable
    - `completedAt` string, date-time, nullable
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `nextCursor` string, nullable

## Other responses

- `401` — Unauthorized.

---

[API](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api.md) · [All operations](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zavudev/zavu-unified-messaging-layer-api/revisions/eb3dc75cc05b/schema)