# Mangomint API

> Every Mangomint 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/mangomint

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 Mangomint. Each one is a POST with a JSON body, called with your API key.

- Base URL: `https://cotlet.dev/api/v1/mangomint`
- Connects with: Your own Mangomint account (admin, or staff with the permission for the task: reports and waitlist have their own)
- Integration page: https://cotlet.dev/integrations/mangomint-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `list_locations` | read | Your business locations with address and time zone. |
| `list_services` | read | Service menu of a location with duration, price and the staff who perform each service. |
| `list_appointments` | read | Appointments on the calendar in a date range with client, services, staff member and notes. |
| `find_client` | read | Search clients by name, email or phone; returns contact details, tags and client notes. |
| `get_client_timeline` | read | A client's timeline: past and upcoming appointments, sales, timeline notes and form submissions. |
| `list_waitlist` | read | Intelligent Waitlist entries for a day, with the openings Mangomint found for each. |
| `get_report` | read | One of the built-in reports for a date range, as rows. |
| `export_clients` | read | The client list as a CSV download link, with the same filters as the Clients app. |
| `add_client_note` | write | Add an internal note to a client: a client note shown at booking and checkout, or a dated timeline note. |
| `book_appointment` | write | Book one or more services for a client with a staff member. |
| `reschedule_appointment` | write | Move an appointment to a new time, day or staff member. |
| `cancel_appointment` | write | Cancel an appointment as a normal cancellation, late cancellation or no show. |
| `book_from_waitlist` | write | Accept an opening Mangomint found for a waitlist entry and book it. |

## List locations

`POST https://cotlet.dev/api/v1/mangomint/list_locations`

Access: read.

Returns every location in your Mangomint account. Use the location_id from each item in the other tools. Most single-location businesses have one item.

### Parameters

No parameters.

### Request

**cURL**

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

**Python**

```python
result = client.call("mangomint", "list_locations")
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'list_locations');
```

**CLI**

```bash
cotlet call mangomint list_locations
```

### Example response

```json
{
  "locations": [
    {
      "location_id": "loc_1",
      "name": "Downtown",
      "address": "412 Alder St, Portland, OR",
      "time_zone": "America/Los_Angeles"
    }
  ]
}
```

## List services

`POST https://cotlet.dev/api/v1/mangomint/list_services`

Access: read.

Returns the services you can book at a location, grouped by category, with duration, price and the staff members who perform each one. Use the service_id values in book_appointment.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location_id` | string | no | Location ID from list_locations. Default: your main location. |

### Request

**cURL**

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

**Python**

```python
result = client.call("mangomint", "list_services")
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'list_services');
```

**CLI**

```bash
cotlet call mangomint list_services
```

### Example response

```json
{
  "services": [
    {
      "service_id": "svc_signature_facial",
      "name": "Signature Facial",
      "category": "Facials",
      "duration_minutes": 60,
      "price": {
        "amount": 120,
        "currency": "USD"
      },
      "staff": [
        {
          "staff_id": "st_207",
          "name": "Alex"
        }
      ]
    },
    {
      "service_id": "svc_brow_shape",
      "name": "Brow Shaping",
      "category": "Brows",
      "duration_minutes": 30,
      "price": {
        "amount": 45,
        "currency": "USD"
      },
      "staff": [
        {
          "staff_id": "st_207",
          "name": "Alex"
        },
        {
          "staff_id": "st_311",
          "name": "Sam"
        }
      ]
    }
  ]
}
```

## List appointments

`POST https://cotlet.dev/api/v1/mangomint/list_appointments`

Access: read.

Returns appointments in a date range in start order, each with client, services, staff member, start, end and appointment note. Filter by staff member to read one calendar. Canceled appointments are left out unless include_canceled is true.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location_id` | string | no | Location ID from list_locations. Default: your main location. |
| `from` | date | yes | First day, inclusive. |
| `to` | date | no | Last day, inclusive. Default: same as from. |
| `staff_id` | string | no | Only this staff member. |
| `include_canceled` | boolean | no | Also return canceled and no-show appointments. Default: false. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/mangomint/list_appointments \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-10-01"}'
```

**Python**

```python
result = client.call("mangomint", "list_appointments", {"from":"2026-10-01"})
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'list_appointments', {"from":"2026-10-01"});
```

**CLI**

```bash
cotlet call mangomint list_appointments --data '{"from":"2026-10-01"}'
```

### Example response

```json
{
  "appointments": [
    {
      "appointment_id": "ap_903114",
      "client": {
        "client_id": "cl_48213",
        "name": "Jamie Doe"
      },
      "services": [
        {
          "service_id": "svc_signature_facial",
          "name": "Signature Facial"
        }
      ],
      "staff": {
        "staff_id": "st_207",
        "name": "Alex"
      },
      "start": "2026-10-12T14:00:00-07:00",
      "end": "2026-10-12T15:00:00-07:00",
      "status": "booked",
      "note": null
    }
  ]
}
```

## Find client

`POST https://cotlet.dev/api/v1/mangomint/find_client`

Access: read.

Searches your client list and returns every match with contact details, tags and client notes. Client notes are the internal notes Mangomint shows when you book or check out that client. Pass client_id to the other client tools.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Name, email or phone number. |

### Request

**cURL**

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

**Python**

```python
result = client.call("mangomint", "find_client", {"query":"query"})
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'find_client', {"query":"query"});
```

**CLI**

```bash
cotlet call mangomint find_client --data '{"query":"query"}'
```

### Example response

```json
{
  "clients": [
    {
      "client_id": "cl_48213",
      "name": "Jamie Doe",
      "email": "client@example.com",
      "phone": "+15035550142",
      "tags": [
        "VIP"
      ],
      "client_notes": [
        "Prefers fragrance-free products"
      ]
    }
  ]
}
```

## Get client timeline

`POST https://cotlet.dev/api/v1/mangomint/get_client_timeline`

Access: read.

Returns entries from one client's timeline, newest first: appointments, sales, timeline notes and submitted forms. Use limit to read the latest few visits before a booking.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from find_client. |
| `limit` | integer | no | 1 to 100 entries, newest first. Default: 25. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/mangomint/get_client_timeline \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"client_8c41d2"}'
```

**Python**

```python
result = client.call("mangomint", "get_client_timeline", {"client_id":"client_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'get_client_timeline', {"client_id":"client_8c41d2"});
```

**CLI**

```bash
cotlet call mangomint get_client_timeline --data '{"client_id":"client_8c41d2"}'
```

### Example response

```json
{
  "client_id": "cl_48213",
  "entries": [
    {
      "type": "appointment",
      "date": "2026-09-14T14:00:00-07:00",
      "summary": "Signature Facial with Alex"
    },
    {
      "type": "sale",
      "date": "2026-09-14T15:05:00-07:00",
      "summary": "Checkout, 1 service, 1 product"
    },
    {
      "type": "timeline_note",
      "date": "2026-09-14T15:10:00-07:00",
      "summary": "Skin was dry; added hydrating serum"
    }
  ]
}
```

## List waitlist

`POST https://cotlet.dev/api/v1/mangomint/list_waitlist`

Access: read.

Returns the waitlist entries for one day with the openings Mangomint found for each. Needs the Intelligent Waitlist app enabled and an Admin user or the Can manage waitlist permission. Pass entry_id and opening_id to book_from_waitlist.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location_id` | string | no | Location ID from list_locations. Default: your main location. |
| `date` | date | yes | Calendar day to read. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/mangomint/list_waitlist \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-10-01"}'
```

**Python**

```python
result = client.call("mangomint", "list_waitlist", {"date":"2026-10-01"})
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'list_waitlist', {"date":"2026-10-01"});
```

**CLI**

```bash
cotlet call mangomint list_waitlist --data '{"date":"2026-10-01"}'
```

### Example response

```json
{
  "entries": [
    {
      "entry_id": "wl_2207",
      "client": {
        "client_id": "cl_51007",
        "name": "Priya Shah"
      },
      "service": "Signature Facial",
      "openings": [
        {
          "opening_id": "op_88a1",
          "staff": "Alex",
          "start": "2026-10-13T11:00:00-07:00"
        }
      ]
    }
  ]
}
```

## Get report

`POST https://cotlet.dev/api/v1/mangomint/get_report`

Access: read.

Returns one of the reports from the Reports app as rows. Sales Summary gives service and product quantities and sales totals for each day; Client Retention gives how many clients from the period visited again within 90 or 180 days. Needs an Admin user or the Can access company reports permission.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `report` | enum | yes | sales_summary, service_sales, product_sales, sales_by_time_period, sales_by_staff, canceled_appointments or client_retention. |
| `from` | date | yes | First day, inclusive. |
| `to` | date | yes | Last day, inclusive. |
| `location_ids` | string[] | no | Locations to include. Default: all. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/mangomint/get_report \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"report":"sales_summary","from":"2026-10-05","to":"2026-10-11"}'
```

**Python**

```python
result = client.call("mangomint", "get_report", {"report":"sales_summary","from":"2026-10-05","to":"2026-10-11"})
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'get_report', {"report":"sales_summary","from":"2026-10-05","to":"2026-10-11"});
```

**CLI**

```bash
cotlet call mangomint get_report --data '{"report":"sales_summary","from":"2026-10-05","to":"2026-10-11"}'
```

### Example response

```json
{
  "report": "sales_summary",
  "from": "2026-10-05",
  "to": "2026-10-11",
  "currency": "USD",
  "rows": [
    {
      "date": "2026-10-05",
      "services_qty": 31,
      "services_total": 3120,
      "products_qty": 6,
      "products_total": 214,
      "total": 3334
    },
    {
      "date": "2026-10-06",
      "services_qty": 28,
      "services_total": 2870,
      "products_qty": 4,
      "products_total": 148,
      "total": 3018
    },
    {
      "date": "2026-10-07",
      "services_qty": 35,
      "services_total": 3540,
      "products_qty": 9,
      "products_total": 302,
      "total": 3842
    },
    {
      "date": "2026-10-08",
      "services_qty": 33,
      "services_total": 3315,
      "products_qty": 5,
      "products_total": 176,
      "total": 3491
    },
    {
      "date": "2026-10-09",
      "services_qty": 41,
      "services_total": 4210,
      "products_qty": 12,
      "products_total": 388,
      "total": 4598
    },
    {
      "date": "2026-10-10",
      "services_qty": 47,
      "services_total": 4760,
      "products_qty": 10,
      "products_total": 341,
      "total": 5101
    },
    {
      "date": "2026-10-11",
      "services_qty": 12,
      "services_total": 1180,
      "products_qty": 2,
      "products_total": 64,
      "total": 1244
    }
  ],
  "totals": {
    "services_qty": 227,
    "services_total": 22995,
    "products_qty": 48,
    "products_total": 1633,
    "total": 24628
  }
}
```

## Export clients

`POST https://cotlet.dev/api/v1/mangomint/export_clients`

Access: read.

Applies the filters you give, as the Clients app does, and returns a link to the CSV file. Combine last_visit_days_ago and has_future_appointment to find clients who have not come back. The file has contact details, so open the link yourself.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `last_visit_days_ago` | integer | no | Only clients whose last appointment was more than this many days ago. |
| `has_future_appointment` | boolean | no | Only clients with (true) or without (false) a future appointment. |
| `tag` | string | no | Only clients with this tag. |

### Request

**cURL**

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

**Python**

```python
result = client.call("mangomint", "export_clients")
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'export_clients');
```

**CLI**

```bash
cotlet call mangomint export_clients
```

### Example response

```json
{
  "status": "ready",
  "filters": {
    "last_visit_days_ago": 90,
    "has_future_appointment": false
  },
  "row_count": 42,
  "download_url": "https://files.cotlet.example/exports/mangomint-clients-2026-10-11.csv",
  "expires_at": "2026-10-11T22:00:00+02:00"
}
```

## Add client note

`POST https://cotlet.dev/api/v1/mangomint/add_client_note`

Access: write.

Adds an internal note to a client profile. A client note shows whenever staff book, view or check out that client; a timeline note is a dated entry on the client timeline. Notes are never shown to the client and reach no one, so add_client_note runs without asking first.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from find_client. |
| `text` | string | yes | Note text. Internal, never shown to the client. |
| `kind` | enum | no | client or timeline. Default: timeline. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/mangomint/add_client_note \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"client_8c41d2","text":"text"}'
```

**Python**

```python
result = client.call("mangomint", "add_client_note", {"client_id":"client_8c41d2","text":"text"})
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'add_client_note', {"client_id":"client_8c41d2","text":"text"});
```

**CLI**

```bash
cotlet call mangomint add_client_note --data '{"client_id":"client_8c41d2","text":"text"}'
```

### Example response

```json
{
  "client_id": "cl_48213",
  "kind": "client",
  "status": "added",
  "text": "Allergic to lavender oil"
}
```

## Book appointment

`POST https://cotlet.dev/api/v1/mangomint/book_appointment`

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

Books the services in the order given, back to back, for one client with one staff member at the start time. The staff member must be on the schedule and free for the full length. Returns the appointment with start and end. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client ID from find_client. |
| `location_id` | string | no | Location ID from list_locations. Default: your main location. |
| `service_ids` | string[] | yes | Service IDs from list_services, in order. |
| `staff_id` | string | yes | Staff member performing the services. |
| `start` | datetime | yes | ISO 8601 with time zone. |
| `note` | string | no | Appointment note. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/mangomint/book_appointment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"cl_48213","location_id":"loc_1","service_ids":["svc_signature_facial"],"staff_id":"st_207","start":"2026-10-16T14:00:00-07:00"}'
```

**Python**

```python
result = client.call("mangomint", "book_appointment", {"client_id":"cl_48213","location_id":"loc_1","service_ids":["svc_signature_facial"],"staff_id":"st_207","start":"2026-10-16T14:00:00-07:00"})
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'book_appointment', {"client_id":"cl_48213","location_id":"loc_1","service_ids":["svc_signature_facial"],"staff_id":"st_207","start":"2026-10-16T14:00:00-07:00"});
```

**CLI**

```bash
cotlet call mangomint book_appointment --data '{"client_id":"cl_48213","location_id":"loc_1","service_ids":["svc_signature_facial"],"staff_id":"st_207","start":"2026-10-16T14:00:00-07:00"}'
```

### Example response

```json
{
  "appointment_id": "ap_903114",
  "status": "booked",
  "client": {
    "client_id": "cl_48213",
    "name": "Jamie Doe"
  },
  "services": [
    {
      "service_id": "svc_signature_facial",
      "name": "Signature Facial",
      "duration_minutes": 60
    }
  ],
  "staff": {
    "staff_id": "st_207",
    "name": "Alex"
  },
  "start": "2026-10-16T14:00:00-07:00",
  "end": "2026-10-16T15:00:00-07:00"
}
```

## Reschedule appointment

`POST https://cotlet.dev/api/v1/mangomint/reschedule_appointment`

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

Moves one appointment to a new start and, if you pass staff_id, to another staff member, as dragging it on the calendar does. Mangomint sends its automated reschedule message only for changes clients make in the client portal, so set notify_client to true to tell the client about this one. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `appointment_id` | string | yes | Appointment ID from list_appointments. |
| `start` | datetime | yes | New start, ISO 8601 with time zone. |
| `staff_id` | string | no | New staff member. Default: unchanged. |
| `notify_client` | boolean | no | Send the client a notification about the change. Default: false. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/mangomint/reschedule_appointment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"appointment_id":"ap_903114","start":"2026-10-13T11:00:00-07:00","staff_id":"st_311","notify_client":true}'
```

**Python**

```python
result = client.call("mangomint", "reschedule_appointment", {"appointment_id":"ap_903114","start":"2026-10-13T11:00:00-07:00","staff_id":"st_311","notify_client":True})
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'reschedule_appointment', {"appointment_id":"ap_903114","start":"2026-10-13T11:00:00-07:00","staff_id":"st_311","notify_client":true});
```

**CLI**

```bash
cotlet call mangomint reschedule_appointment --data '{"appointment_id":"ap_903114","start":"2026-10-13T11:00:00-07:00","staff_id":"st_311","notify_client":true}'
```

### Example response

```json
{
  "appointment_id": "ap_903114",
  "status": "rescheduled",
  "staff": {
    "staff_id": "st_207",
    "name": "Alex"
  },
  "start": "2026-10-13T11:00:00-07:00",
  "end": "2026-10-13T12:00:00-07:00",
  "client_notified": true
}
```

## Cancel appointment

`POST https://cotlet.dev/api/v1/mangomint/cancel_appointment`

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

Cancels one appointment with the cancellation type you choose: normal (the client canceled within the cancellation period), late (after it) or no_show. The client is notified if cancellation notifications are on in Mangomint. A late cancellation or no show does not charge a fee by itself; the fee is added at checkout. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `appointment_id` | string | yes | Appointment ID from list_appointments. |
| `type` | enum | yes | normal, late or no_show. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/mangomint/cancel_appointment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"appointment_id":"appointment_8c41d2","type":"normal"}'
```

**Python**

```python
result = client.call("mangomint", "cancel_appointment", {"appointment_id":"appointment_8c41d2","type":"normal"})
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'cancel_appointment', {"appointment_id":"appointment_8c41d2","type":"normal"});
```

**CLI**

```bash
cotlet call mangomint cancel_appointment --data '{"appointment_id":"appointment_8c41d2","type":"normal"}'
```

### Example response

```json
{
  "appointment_id": "ap_903210",
  "status": "canceled",
  "type": "late"
}
```

## Book from waitlist

`POST https://cotlet.dev/api/v1/mangomint/book_from_waitlist`

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

Accepts one opening for one waitlist entry, the same as Book on the calendar notification, and puts the client on the calendar. Needs an Admin user or the Can manage waitlist permission. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `entry_id` | string | yes | Waitlist entry ID from list_waitlist. |
| `opening_id` | string | yes | Opening ID from the same entry. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/mangomint/book_from_waitlist \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entry_id":"wl_2207","opening_id":"op_88a1"}'
```

**Python**

```python
result = client.call("mangomint", "book_from_waitlist", {"entry_id":"wl_2207","opening_id":"op_88a1"})
```

**Node.js**

```js
const result = await cotlet.call('mangomint', 'book_from_waitlist', {"entry_id":"wl_2207","opening_id":"op_88a1"});
```

**CLI**

```bash
cotlet call mangomint book_from_waitlist --data '{"entry_id":"wl_2207","opening_id":"op_88a1"}'
```

### Example response

```json
{
  "entry_id": "wl_2207",
  "status": "booked",
  "appointment_id": "ap_903377",
  "client": {
    "client_id": "cl_51007",
    "name": "Priya Shah"
  },
  "staff": {
    "staff_id": "st_207",
    "name": "Alex"
  },
  "start": "2026-10-13T11:00:00-07:00"
}
```