Skip to main content
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 /appointments with the required X-Qminder-API-Version header: 
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: 
{
  "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 for details.

​
Auto-Assigning Appointments

For appointments that should be automatically assigned to an available user, use the /appointments/auto-assign endpoint. This endpoint does not require an assigneeId - the system will automatically find an available user based on their availability. 
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: 
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: 
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: 
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: 
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.