# Partiful API

> Every Partiful endpoint on Cotlet: inputs, JSON Schema, cURL, Python and Node.js examples and an example response for each call.

Source: https://cotlet.dev/docs/api/partiful

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

13 endpoints for Partiful. Each one is a POST with a JSON body, called with your API key.

- Base URL: `https://cotlet.dev/api/v1/partiful`
- Connects with: Your own Partiful host account
- Integration page: https://cotlet.dev/integrations/partiful-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `list_events` | read | Events you host, with date, status and guest counts. |
| `get_event` | read | Full event: title, description, start and end, location, RSVP deadline, guest limit, Guest Approval and waitlist settings, link. |
| `list_guests` | read | Guests of an event with RSVP status, check-in and Guest Questionnaire answers. |
| `export_guest_list` | read | The guest list as a CSV file link, the same file as the Export CSV button. |
| `list_past_guests` | read | People you can invite: your past guests and mutuals, optionally from one past event. |
| `create_event` | write | New event page. Nobody is invited until you call invite_guests. |
| `update_event` | write | Change the details or settings of an event you host. |
| `duplicate_event` | write | Copy an event with its settings to a new date. The copy has no guests yet. |
| `invite_guests` | write | Invite past guests and mutuals through Partiful, or anyone by email. |
| `approve_guests` | write | Approve pending guests on a Guest Approval event. |
| `check_in_guests` | write | Mark guests as checked in at the door, or undo it. |
| `send_text_blast` | write | Text a message to guests by RSVP status. Partiful allows up to 10 Text Blasts per event. |
| `cancel_event` | write | Cancel an event. Partiful notifies the guests. |

## List events

`POST https://cotlet.dev/api/v1/partiful/list_events`

Access: read.

Returns your events with start time, whether the event is canceled and counts of guests by RSVP status. Use event_id from each item in the other tools. Pages hold up to 50 events; pass next_cursor back as cursor for the next page.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `when` | enum | no | upcoming, past or all. Default: upcoming. |
| `limit` | integer | no | 1 to 50. Default: 20. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/list_events \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("partiful", "list_events")
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'list_events');
```

**CLI**

```bash
cotlet call partiful list_events
```

### Example response

```json
{
  "events": [
    {
      "event_id": "evt_hK3vQ9xL",
      "title": "Rooftop dinner",
      "start_at": "2026-10-17T19:00:00-04:00",
      "status": "active",
      "guests": {
        "going": 28,
        "maybe": 9,
        "cant_go": 4,
        "invited": 31,
        "pending": 0
      }
    },
    {
      "event_id": "evt_pL8wN2aD",
      "title": "Launch party",
      "start_at": "2026-10-24T20:00:00-04:00",
      "status": "active",
      "guests": {
        "going": 52,
        "maybe": 6,
        "cant_go": 11,
        "invited": 60,
        "pending": 3
      }
    }
  ],
  "next_cursor": null
}
```

## Get event

`POST https://cotlet.dev/api/v1/partiful/get_event`

Access: read.

Returns one event with its details and the settings you chose in Event Settings: guest limit, waitlist, Guest Approval and the Guest Questionnaire questions. Use it before update_event to see what is set now.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/get_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'
```

**Python**

```python
result = client.call("partiful", "get_event", {"event_id":"event_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'get_event', {"event_id":"event_8c41d2"});
```

**CLI**

```bash
cotlet call partiful get_event --data '{"event_id":"event_8c41d2"}'
```

### Example response

```json
{
  "event_id": "evt_hK3vQ9xL",
  "title": "Rooftop dinner",
  "start_at": "2026-10-17T19:00:00-04:00",
  "end_at": "2026-10-17T23:00:00-04:00",
  "location": "21 Mercer St, New York",
  "description": "Bring a drink to share.",
  "rsvp_deadline": "2026-10-15T18:00:00-04:00",
  "max_guests": 60,
  "waitlist": true,
  "guest_approval": false,
  "questions": [
    "Dietary restrictions"
  ],
  "url": "https://partiful.com/e/hK3vQ9xLexample"
}
```

## List guests

`POST https://cotlet.dev/api/v1/partiful/list_guests`

Access: read.

Returns the guests of one event, each with RSVP status, whether they are checked in and their answers to your Guest Questionnaire. Filter by status to see only pending guests or only the ones going. Pages hold up to 200 guests; pass next_cursor back as cursor for the next page.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |
| `status` | enum | no | all, going, maybe, cant_go, invited, waitlist or pending. Default: all. |
| `checked_in` | boolean | no | Only guests who are checked in (true) or not (false). |
| `limit` | integer | no | 1 to 200. Default: 100. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/list_guests \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'
```

**Python**

```python
result = client.call("partiful", "list_guests", {"event_id":"event_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'list_guests', {"event_id":"event_8c41d2"});
```

**CLI**

```bash
cotlet call partiful list_guests --data '{"event_id":"event_8c41d2"}'
```

### Example response

```json
{
  "guests": [
    {
      "guest_id": "g_41aa",
      "name": "Maya Chen",
      "status": "going",
      "checked_in": false,
      "answers": [
        {
          "question": "Dietary restrictions",
          "answer": "Vegetarian"
        }
      ]
    },
    {
      "guest_id": "g_41ab",
      "name": "Leo Park",
      "status": "going",
      "checked_in": false,
      "answers": [
        {
          "question": "Dietary restrictions",
          "answer": "Peanut allergy"
        }
      ]
    }
  ],
  "next_cursor": null
}
```

## Export guest list

`POST https://cotlet.dev/api/v1/partiful/export_guest_list`

Access: read.

Returns a link to the CSV that Partiful's Export CSV button produces, limited to the RSVP statuses you choose. It includes Guest Questionnaire answers. Your agent or n8n flow reads the file and appends the rows to a sheet or CRM.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |
| `statuses` | string[] | no | RSVP statuses to include: going, maybe, cant_go, invited, waitlist, pending. Default: all. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/export_guest_list \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"evt_hK3vQ9xL","statuses":["going"]}'
```

**Python**

```python
result = client.call("partiful", "export_guest_list", {"event_id":"evt_hK3vQ9xL","statuses":["going"]})
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'export_guest_list', {"event_id":"evt_hK3vQ9xL","statuses":["going"]});
```

**CLI**

```bash
cotlet call partiful export_guest_list --data '{"event_id":"evt_hK3vQ9xL","statuses":["going"]}'
```

### Example response

```json
{
  "event_id": "evt_hK3vQ9xL",
  "statuses": [
    "going"
  ],
  "guests": 28,
  "download_url": "https://cotlet.dev/api/v1/files/exports/partiful/evt_hK3vQ9xL-going.csv"
}
```

## List past guests

`POST https://cotlet.dev/api/v1/partiful/list_past_guests`

Access: read.

Returns people you can invite again: guests who attended your events and mutuals. Filter to one past event to invite only the people who came to it. Use user_id from each item in invite_guests. Pages hold up to 200 people.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `from_event_id` | string | no | Only people from this past event. |
| `query` | string | no | Search by name. |
| `limit` | integer | no | 1 to 200. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/list_past_guests \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("partiful", "list_past_guests")
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'list_past_guests');
```

**CLI**

```bash
cotlet call partiful list_past_guests
```

### Example response

```json
{
  "people": [
    {
      "user_id": "u_2f81",
      "name": "Maya Chen",
      "attended": 3
    },
    {
      "user_id": "u_2f93",
      "name": "Leo Park",
      "attended": 2
    }
  ],
  "next_cursor": null
}
```

## Create event

`POST https://cotlet.dev/api/v1/partiful/create_event`

Access: write.

Creates an event page on your account. Nobody is invited and nothing is sent, so there is no confirmation; one call to update_event or cancel_event changes it. Guest Approval and the Guest Questionnaire are set here, the same way as in Event Settings.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `title` | string | yes | Event title. |
| `start_at` | datetime | yes | ISO 8601 with time zone. |
| `end_at` | datetime | no | ISO 8601 with time zone. |
| `location` | string | no | Address or place name. |
| `description` | string | no | Event details shown on the page. |
| `rsvp_deadline` | datetime | no | Last moment guests can RSVP. |
| `max_guests` | integer | no | Guest limit; with the waitlist on, extra RSVPs go to the waitlist. |
| `guest_approval` | boolean | no | Guests ask to get on the list and you approve them. Default: false. |
| `questions` | string[] | no | Guest Questionnaire questions, short answer. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/create_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"title","start_at":"2026-10-01T09:00:00Z"}'
```

**Python**

```python
result = client.call("partiful", "create_event", {"title":"title","start_at":"2026-10-01T09:00:00Z"})
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'create_event', {"title":"title","start_at":"2026-10-01T09:00:00Z"});
```

**CLI**

```bash
cotlet call partiful create_event --data '{"title":"title","start_at":"2026-10-01T09:00:00Z"}'
```

### Example response

```json
{
  "event_id": "evt_bK7dR3nM",
  "title": "Book club: November",
  "start_at": "2026-11-14T19:00:00-05:00",
  "status": "active",
  "url": "https://partiful.com/e/bK7dR3nMexample"
}
```

## Update event

`POST https://cotlet.dev/api/v1/partiful/update_event`

Access: write.

Changes the fields you pass and leaves the rest as it is. It sends nothing itself, so there is no confirmation, and another call restores the old values. Use get_event first to see the current values.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |
| `fields` | object | yes | Any of title, start_at, end_at, location, description, rsvp_deadline, max_guests, guest_approval. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/update_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2","fields":"fields"}'
```

**Python**

```python
result = client.call("partiful", "update_event", {"event_id":"event_8c41d2","fields":"fields"})
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'update_event', {"event_id":"event_8c41d2","fields":"fields"});
```

**CLI**

```bash
cotlet call partiful update_event --data '{"event_id":"event_8c41d2","fields":"fields"}'
```

### Example response

```json
{
  "event_id": "evt_hK3vQ9xL",
  "updated": [
    "location"
  ],
  "location": "88 Bleecker St, New York"
}
```

## Duplicate event

`POST https://cotlet.dev/api/v1/partiful/duplicate_event`

Access: write.

Does what Clone Event does in Partiful: copies the event details to a new event on the date you give. Guests are not copied, so re-invite them with invite_guests. It sends nothing, so there is no confirmation.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |
| `start_at` | datetime | yes | Start of the new event, ISO 8601 with time zone. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/duplicate_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2","start_at":"2026-10-01T09:00:00Z"}'
```

**Python**

```python
result = client.call("partiful", "duplicate_event", {"event_id":"event_8c41d2","start_at":"2026-10-01T09:00:00Z"})
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'duplicate_event', {"event_id":"event_8c41d2","start_at":"2026-10-01T09:00:00Z"});
```

**CLI**

```bash
cotlet call partiful duplicate_event --data '{"event_id":"event_8c41d2","start_at":"2026-10-01T09:00:00Z"}'
```

### Example response

```json
{
  "event_id": "evt_bK7dR3nM",
  "copied_from": "evt_aQ4tX9cE",
  "start_at": "2026-11-14T19:00:00-05:00",
  "guests": 0
}
```

## Invite guests

`POST https://cotlet.dev/api/v1/partiful/invite_guests`

Access: write. Confirm: waits for the user's OK before it runs.

Invites people you pick from list_past_guests and sends email invites to the addresses you give. Partiful caps invites per event at 1,000 in total and 500 by email; a call over the cap fails. Invitees reached by email still log in with their phone number to RSVP. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |
| `user_ids` | string[] | no | People from list_past_guests. |
| `emails` | string[] | no | Email addresses to invite. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/invite_guests \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"evt_bK7dR3nM","user_ids":["u_2f81","u_2f93"]}'
```

**Python**

```python
result = client.call("partiful", "invite_guests", {"event_id":"evt_bK7dR3nM","user_ids":["u_2f81","u_2f93"]})
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'invite_guests', {"event_id":"evt_bK7dR3nM","user_ids":["u_2f81","u_2f93"]});
```

**CLI**

```bash
cotlet call partiful invite_guests --data '{"event_id":"evt_bK7dR3nM","user_ids":["u_2f81","u_2f93"]}'
```

### Example response

```json
{
  "event_id": "evt_bK7dR3nM",
  "invited": 2,
  "by_email": 0,
  "status": "sent"
}
```

## Approve guests

`POST https://cotlet.dev/api/v1/partiful/approve_guests`

Access: write. Confirm: waits for the user's OK before it runs.

Marks the guests you name as Approved on an event that has Guest Approval on. Only approved guests have access to the event. Guests you leave alone stay Pending. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |
| `guest_ids` | string[] | yes | Guest IDs from list_guests. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/approve_guests \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"evt_pL8wN2aD","guest_ids":["g_41aa","g_41ab"]}'
```

**Python**

```python
result = client.call("partiful", "approve_guests", {"event_id":"evt_pL8wN2aD","guest_ids":["g_41aa","g_41ab"]})
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'approve_guests', {"event_id":"evt_pL8wN2aD","guest_ids":["g_41aa","g_41ab"]});
```

**CLI**

```bash
cotlet call partiful approve_guests --data '{"event_id":"evt_pL8wN2aD","guest_ids":["g_41aa","g_41ab"]}'
```

### Example response

```json
{
  "event_id": "evt_pL8wN2aD",
  "approved": 2,
  "still_pending": 1
}
```

## Check in guests

`POST https://cotlet.dev/api/v1/partiful/check_in_guests`

Access: write.

Checks in the guests you name, like checking them in manually from the guest list. Guests are not notified, and set undo to true to remove a check-in, so it runs without asking first.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |
| `guest_ids` | string[] | yes | Guest IDs from list_guests. |
| `undo` | boolean | no | Remove the check-in instead. Default: false. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/check_in_guests \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2","guest_ids":["guest ids"]}'
```

**Python**

```python
result = client.call("partiful", "check_in_guests", {"event_id":"event_8c41d2","guest_ids":["guest ids"]})
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'check_in_guests', {"event_id":"event_8c41d2","guest_ids":["guest ids"]});
```

**CLI**

```bash
cotlet call partiful check_in_guests --data '{"event_id":"event_8c41d2","guest_ids":["guest ids"]}'
```

### Example response

```json
{
  "event_id": "evt_hK3vQ9xL",
  "checked_in": 2,
  "undo": false
}
```

## Send Text Blast

`POST https://cotlet.dev/api/v1/partiful/send_text_blast`

Access: write. Confirm: waits for the user's OK before it runs.

Sends one Text Blast to the guests in the statuses you pick, the same as New Blast on the event page. It reaches guests who RSVP'd or were invited directly through Partiful; guests invited by email get it by email until they RSVP. Returns how many people it went to and how many blasts are left. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |
| `message` | string | yes | Message text. |
| `statuses` | string[] | yes | Who receives it: going, maybe, cant_go, invited. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/send_text_blast \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"evt_hK3vQ9xL","message":"Door code is 4512. We start at 7:30, see you soon!","statuses":["going","maybe"]}'
```

**Python**

```python
result = client.call("partiful", "send_text_blast", {"event_id":"evt_hK3vQ9xL","message":"Door code is 4512. We start at 7:30, see you soon!","statuses":["going","maybe"]})
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'send_text_blast', {"event_id":"evt_hK3vQ9xL","message":"Door code is 4512. We start at 7:30, see you soon!","statuses":["going","maybe"]});
```

**CLI**

```bash
cotlet call partiful send_text_blast --data '{"event_id":"evt_hK3vQ9xL","message":"Door code is 4512. We start at 7:30, see you soon!","statuses":["going","maybe"]}'
```

### Example response

```json
{
  "blast_id": "bl_8Fq2Lw0Zr4",
  "event_id": "evt_hK3vQ9xL",
  "recipients": 37,
  "by_status": {
    "going": 28,
    "maybe": 9
  },
  "blasts_left": 7,
  "sent_at": "2026-10-17T18:42:05-04:00"
}
```

## Cancel event

`POST https://cotlet.dev/api/v1/partiful/cancel_event`

Access: write. Confirm: waits for the user's OK before it runs.

Cancels the event the way Cancel Event does in Partiful. Guests are notified; Partiful has no way to cancel without telling them. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/partiful/cancel_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'
```

**Python**

```python
result = client.call("partiful", "cancel_event", {"event_id":"event_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('partiful', 'cancel_event', {"event_id":"event_8c41d2"});
```

**CLI**

```bash
cotlet call partiful cancel_event --data '{"event_id":"event_8c41d2"}'
```

### Example response

```json
{
  "event_id": "evt_hK3vQ9xL",
  "status": "canceled",
  "guests_notified": true
}
```