> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leadscoutapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API endpoint for listing prospect appointments

> Retrieve scheduled appointments across all prospects in your company. Filter by date range to build calendar views or sync with external scheduling tools.

The appointments endpoint returns scheduled appointments across every prospect in your company. You can filter by date range to build a daily or weekly calendar view, sync upcoming appointments to an external calendar system, or report on appointment volume over time. Each appointment record includes a reference to the parent prospect and the user who created it.

<Note>
  Calendar access must be enabled on your plan. Requests from accounts without calendar access return `403` with the message `"Calendar access not available on your plan"`.
</Note>

## List appointments

```
GET /api/appointments
```

Returns all non-deleted appointments for prospects in your company, ordered by `appointmentTime` ascending (earliest first).

### Query parameters

<ParamField query="dateFrom" type="string">
  ISO 8601 date string. Returns only appointments scheduled on or after this date. Example: `2024-06-01`
</ParamField>

<ParamField query="dateTo" type="string">
  ISO 8601 date string. Returns only appointments scheduled on or before this date. Example: `2024-06-30`
</ParamField>

### Response

Returns an array of appointment objects directly (not paginated).

<ResponseField name="id" type="number">Appointment ID.</ResponseField>
<ResponseField name="appointmentTime" type="string | null">ISO 8601 scheduled time for the appointment.</ResponseField>
<ResponseField name="durationMinutes" type="number | null">Duration of the appointment in minutes.</ResponseField>
<ResponseField name="createdAt" type="string">ISO 8601 creation timestamp.</ResponseField>

<ResponseField name="prospect" type="object">
  Summary of the associated prospect.

  <Expandable title="prospect">
    <ResponseField name="id" type="number">Prospect ID.</ResponseField>
    <ResponseField name="name" type="string | null">Prospect's full name.</ResponseField>

    <ResponseField name="address" type="object | null">
      <Expandable title="address">
        <ResponseField name="address1" type="string">Street line 1.</ResponseField>
        <ResponseField name="city" type="string">City.</ResponseField>
        <ResponseField name="state" type="string">State.</ResponseField>
        <ResponseField name="zip" type="string">ZIP code.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createdBy" type="object">
  The user who created this appointment.

  <Expandable title="createdBy">
    <ResponseField name="id" type="number">User ID.</ResponseField>
    <ResponseField name="firstName" type="string">First name.</ResponseField>
    <ResponseField name="lastName" type="string">Last name.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://app.leadscoutapp.com/api/appointments?dateFrom=2024-06-01&dateTo=2024-06-30' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.leadscoutapp.com/api/appointments?dateFrom=2024-06-01&dateTo=2024-06-30',
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );
  const appointments = await response.json();
  ```
</CodeGroup>

<Tip>
  To create or delete an appointment on a specific prospect, use `POST /api/prospects/:id/appointments` or `DELETE /api/prospects/:id/appointments/:appointmentId`. The `/api/appointments` endpoint is read-only and is best used for calendar aggregation.
</Tip>