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

# Appointments

> Appointments represent scheduled visits with a specific time slot.

Appointments are scheduled visits where visitors book a specific time slot in advance. Unlike regular tickets that join a queue immediately, appointments have a defined start and end time and are assigned to a specific user.

All appointments belong to a Line and are created with a time slot and assignee.

### Creating an Appointment

To create an appointment, send a POST request to `/v1/appointments`:

```bash theme={null}
curl -X POST https://api.qminder.com/v1/appointments \
  -H "X-Qminder-REST-API-Key: YOUR_API_KEY" \
  -H "X-Qminder-API-Version: 2020-09-01" \
  -H "Content-Type: application/json" \
  -d '{
    "lineId": 12345,
    "firstName": "John",
    "lastName": "Doe",
    "startTime": "2024-12-15T10:00:00Z",
    "endTime": "2024-12-15T10:30:00Z",
    "assigneeId": 789
  }'
```

**Required fields:**

* `lineId` - ID of the line to create the appointment in
* `firstName` - Visitor's first name (2-50 characters)
* `startTime` - Appointment start time in ISO 8601 format
* `endTime` - Appointment end time in ISO 8601 format
* `assigneeId` - ID of the user to assign the appointment to

**Optional fields:**

* `lastName` - Visitor's last name (max 50 characters)
* `phoneNumber` - Phone number with optional + prefix (5-20 digits)
* `email` - Visitor's email address
* `languageCode` - Language code (default: "en")
* `fields` - Array of custom input fields with `inputFieldId` (UUID) and `value` or `optionIds`
* `labels` - Array of labels with `value`

**Response:**

```json theme={null}
{
  "id": "226859",
  "publicId": "A-42"
}
```

### Input Fields

To use the `fields` parameter, you first need to discover the available input field IDs for the location. See the [Input Fields query](/reference/queries/input-fields) for details.

### Auto-Assigning Appointments

For appointments that should be automatically assigned to an available user, use the `/v1/appointments/auto-assign` endpoint. This endpoint does not require an `assigneeId` - the system will automatically find an available user based on their availability.

```bash theme={null}
curl -X POST https://api.qminder.com/v1/appointments/auto-assign \
  -H "X-Qminder-REST-API-Key: YOUR_API_KEY" \
  -H "X-Qminder-API-Version: 2020-09-01" \
  -H "Content-Type: application/json" \
  -d '{
    "lineId": 12345,
    "firstName": "John",
    "startTime": "2024-12-15T10:00:00Z",
    "endTime": "2024-12-15T10:30:00Z"
  }'
```

### Appointment Lifecycle

Appointments go through the following states:

1. **Scheduled** - The appointment is created and waiting for the visitor
2. **Checked-in** - The visitor has arrived and checked in (moves to queue)
3. **Served** - The appointment has been completed
4. **Cancelled** - The appointment was cancelled
5. **No-show** - The visitor did not arrive

### Managing Appointments

#### Check-in

When a visitor arrives for their appointment:

```bash theme={null}
curl -X POST https://api.qminder.com/v1/appointments/14848/checkin \
  -H "X-Qminder-REST-API-Key: YOUR_API_KEY" \
  -H "X-Qminder-API-Version: 2020-09-01"
```

#### Cancel

To cancel an appointment:

```bash theme={null}
curl -X POST https://api.qminder.com/v1/appointments/14848/cancel \
  -H "X-Qminder-REST-API-Key: YOUR_API_KEY" \
  -H "X-Qminder-API-Version: 2020-09-01"
```

#### Mark as No-Show

When a visitor doesn't arrive:

```bash theme={null}
curl -X POST https://api.qminder.com/v1/appointments/14848/marknoshow \
  -H "X-Qminder-REST-API-Key: YOUR_API_KEY" \
  -H "X-Qminder-API-Version: 2020-09-01"
```

### Editing an Appointment

To update an appointment's time slot or assignee:

```bash theme={null}
curl -X PATCH https://api.qminder.com/v1/appointments/14848 \
  -H "X-Qminder-REST-API-Key: YOUR_API_KEY" \
  -H "X-Qminder-API-Version: 2020-09-01" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2024-12-15T11:00:00Z",
    "endTime": "2024-12-15T11:30:00Z"
  }'
```

All fields are optional - only include the fields you want to change.