# List open times

`GET /v1/campaigns/{campaign_id}/appointment-slots`

Lists the appointment start times that can be booked in a campaign right now.

**Scope:** `leads:write`

No lead is needed. A start time is listed only when it is inside the campaign's appointment hours (every `slot_minutes` from each opening time, with the whole slot ending by closing time), at least 30 minutes from now, and at least one appointment host has room at that exact time. Hosts are the team members in the campaign's routing with an assignment weight above 0%; a host has room while they have fewer appointments starting then, across every campaign of your organization, than the campaign's Max bookings per time slot. Local times skipped by a daylight-saving change are never listed.

Fetch the slots from your server and cache the response there for about 60 seconds, so visitors share one request per minute. A listed time can still be taken before the visitor books it; the booking then answers `409 slot_unavailable`. Re-fetch, bypassing your cache, and let the visitor pick again.

URL-encode the timestamps: a literal `+` in a query string means a space, so send `+00:00` as `%2B00:00` (`URLSearchParams` does this) or use `Z`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `campaign_id` | `UUID` | Yes | A campaign the key may reach. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `start` | `timestamp` | No | Earliest slot start to list (inclusive). ISO 8601 with a UTC offset, for example `2026-11-02T09:00:00-05:00` or `2026-11-02T14:00:00Z`. Default: now. |
| `end` | `timestamp` | No | List slots starting before this time. ISO 8601 with a UTC offset. After `start` and at most 31 days after it. Default: `start` + 14 days. |

## Response

**Status:** `200 OK`

| Name | Type | Description |
| --- | --- | --- |
| `campaign_id` | `UUID` | The campaign. |
| `timezone` | `string` | IANA time zone of the campaign's appointment hours. Every `start` is given in it, with its UTC offset. |
| `slot_minutes` | `integer` | The grid and the length of a slot. |
| `slots` | `array of objects` | Only open start times, ascending. Empty when nothing is open in the range. |
| `slots.start` | `timestamp` | A bookable start, in `timezone` with its offset. Send it as `start` to book. |

## Example request

**curl**

```bash
curl "https://development.agencydevworks.ai/v1/campaigns/cccccccc-0000-4000-8000-000000000001/appointment-slots?start=2026-11-02T00:00:00-05:00&end=2026-11-03T00:00:00-05:00" \
  -H "Authorization: Bearer dei_your_key"
```

**JavaScript**

```js
const response = await fetch("https://development.agencydevworks.ai/v1/campaigns/cccccccc-0000-4000-8000-000000000001/appointment-slots?start=2026-11-02T00:00:00-05:00&end=2026-11-03T00:00:00-05:00", {
  headers: {
    "Authorization": "Bearer dei_your_key",
  },
});
const data = await response.json();
```

## Example response

**Status:** `200 OK`

```json
{
  "campaign_id": "cccccccc-0000-4000-8000-000000000001",
  "timezone": "America/New_York",
  "slot_minutes": 30,
  "slots": [
    { "start": "2026-11-02T09:00:00-05:00" },
    { "start": "2026-11-02T09:30:00-05:00" },
    { "start": "2026-11-02T11:00:00-05:00" }
  ]
}
```

## Errors

| HTTP | Code | When |
| --- | --- | --- |
| 403 | `insufficient_scope` | The key does not have `leads:write`. |
| 404 | `not_found` | The campaign does not exist or the key cannot reach it. |
| 409 | `availability_not_configured` | The campaign's Appointment availability is off or has no hours. Set them in DialEcho; retrying unchanged will not help. |
| 422 | `invalid_request` | `campaign_id` is not a UUID, or `start`/`end` is invalid: no UTC offset, `end` not after `start`, or a range longer than 31 days (these carry an empty `error.fields`). |

Every endpoint can also answer `401 invalid_api_key`, `429 rate_limited` and `503 dependency_unavailable`. See [Errors](/api/#errors) in the overview.

## Related endpoints

- `PUT /v1/leads/{lead_id}/appointment` · [Book or reschedule](/api/appointments/book)