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

# Scheduled tasks

> Push upcoming appointments into Sales Ask so recordings can be matched to your CRM jobs.

## Overview

When your CRM books an appointment, you can push it to Sales Ask via `POST /v1/scheduled-tasks`. Appointments are keyed by your **event\_id** (e.g. CRM job or calendar event ID). Use the same **event\_id** to update or delete the appointment later.

Sales Ask stores the appointment with the assigned rep (resolved from **user\_email**). When that rep records a call around the appointment time, Sales Ask can match the recording and include your event\_id in webhook payloads so your system can look up the original job.

## Create or update an appointment (upsert)

Send `event_id`, `user_email`, and `start_time`. If an appointment with that `event_id` already exists for your organization, it is updated; otherwise it is created.

```bash theme={null}
curl -X POST https://integrations.salesask.com/v1/scheduled-tasks \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "CRM-JOB-9871",
    "user_email": "rep@company.com",
    "start_time": "2026-03-01T14:00:00.000Z",
    "end_time": "2026-03-01T15:00:00.000Z",
    "title": "Discovery call",
    "customer": {
      "id": "cust_123",
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'
```

All times must be UTC date-time strings (e.g. `2026-03-01T14:00:00.000Z`).

```json theme={null}
{
  "appointment": {
    "id": "task_abc123",
    "event_id": "CRM-JOB-9871",
    "startTime": "2026-03-01T14:00:00.000Z",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "scheduledAt": "2026-03-01T14:15:00.000Z",
    "status": "scheduled",
    "metadata": {},
    "createdAt": "2026-02-28T09:00:00.000Z",
    "updatedAt": "2026-02-28T09:00:00.000Z"
  }
}
```

### Required fields

| Field        | Type         | Description                                                                                        |
| ------------ | ------------ | -------------------------------------------------------------------------------------------------- |
| `event_id`   | string       | Your CRM/external event ID. Unique per organization; used for upsert and for matching in webhooks. |
| `user_email` | string       | Sales rep email. Must be an active member of your organization; resolved to `repUid`.              |
| `start_time` | string (UTC) | Appointment start (e.g. `2026-03-01T14:00:00.000Z`).                                               |

### Optional fields

| Field      | Type         | Description                                                               |
| ---------- | ------------ | ------------------------------------------------------------------------- |
| `end_time` | string (UTC) | Appointment end.                                                          |
| `title`    | string       | Appointment title.                                                        |
| `customer` | object       | `id`, `name`, `email`; stored as customerId, customerName, customerEmail. |

<Tip>
  Always set `event_id` to your CRM's job or appointment ID. This is what you will receive in webhook payloads when a matching recording is processed.
</Tip>

## Update an appointment (partial)

Update only the fields you send. Path parameter is your **event\_id**.

```bash theme={null}
curl -X PUT https://integrations.salesask.com/v1/scheduled-tasks/CRM-JOB-9871 \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2026-03-01T15:00:00.000Z",
    "customer": { "name": "Jane Doe" }
  }'
```

## List appointments

```bash theme={null}
curl "https://integrations.salesask.com/v1/scheduled-tasks?fromDate=2026-03-01&toDate=2026-03-31" \
  -H "x-api-key: <YOUR_API_KEY>"
```

Filter by rep email:

```bash theme={null}
curl "https://integrations.salesask.com/v1/scheduled-tasks?user_email=rep@company.com" \
  -H "x-api-key: <YOUR_API_KEY>"
```

Results are paginated. Use `nextCursor` from the response as `startAfter` for the next page. Optional query params: `fromDate`, `toDate`, `user_email`, `limit` (1–100, default 25), `startAfter`.

## Get one appointment

```bash theme={null}
curl "https://integrations.salesask.com/v1/scheduled-tasks/CRM-JOB-9871" \
  -H "x-api-key: <YOUR_API_KEY>"
```

## Delete an appointment

Use your **event\_id** in the path:

```bash theme={null}
curl -X DELETE https://integrations.salesask.com/v1/scheduled-tasks/CRM-JOB-9871 \
  -H "x-api-key: <YOUR_API_KEY>"
```

## Finding the rep

The `user_email` must match an active user in your organization. The API resolves it to an internal rep identifier; no rep IDs are returned in API responses.