IntakeQ Appointments API

Overview

The IntakeQ Appointment API is composed of HTTP endpoints that can be reached through a REST API. Additionally, you can setup webhooks that are fired when an appointment status changes; giving you the opportunity to watch for changes in realtime and integrate with 3rd party software.

For Intake Forms API, please refer to this article.

Getting Started

To get started, you first need to enable API access (navigate to More > Settings > Integrations > Developer API). That’s also where you’ll find your API key, used to authenticate your HTTP calls.

Only the main account owner has access to the API tab.

Never expose your API key in plain text (config files, source control, etc.).

Base URL

All endpoints are located under the following URL: https://intakeq.com/api/v1/

An example of a typical API call would look like this:

[GET] https://intakeq.com/api/v1/appointments/[appointment-id]

Authentication

Every HTTP request needs to contain your API key embedded in an authentication header named X-Auth-Key.

X-Auth-Key:xxxxxxxxxxxxxxxxxxxxxxxxx

The Appointment Object

Below is the JSON representation of the appointment object, which is used throughout this API.

{
   Id: "123", 
   ClientName: "test",
   ClientEmail: "test@email.com",
   ClientPhone: "(222) 222-2222",
   ClientId: 9999,
   Status: "Confirmed", 
   StartDate: 1458526480368, //Unix timestamp,
   EndDate: 1458526484236, //Unix timestamp,
   Duration: 90, //minutes
   ServiceName: "Initial Consultation",
   ServiceId: "00000000-0000-0000-0000-000000000000", //GUID
   LocationName: "Manhattan Office",
   LocationId: 1,
   Price: 100.00, 	
   PractitionerEmail: "test@email.com",
   PractitionerName: "FirstName LastName"   
   DateCreated: 1458526532654, //Unix timestamp
   IntakeId: "00000000-0000-0000-0000-000000000000", //GUID
   BookedByClient: true,
   CreatedBy: "John Smith",
   AppointmentPackageId: "00000000-0000-0000-0000-000000000000", //GUID
   AppointmentPackageName: "Package Name"	
}

Let’s look at each property individually:

Field Explanation
Id The ID of the appointment.
ClientName The name of the client.
ClientEmail
The email of the client.
ClientPhone
The client's phone number.
ClientId
The client's ID assigned by IntakeQ.
Status Possible values:
Confirmed – The appointment has been confirmed (either manually or automatically).
WaitingConfirmation – The appointment has not been confirmed by the staff.
Declined – The appointment has been declined by the staff.
Canceled – The appointment has been canceled.
Missed – The appointment has been marked as missed by the staff.
StartDate
When the appointment is scheduled for in Unix timestamp.
EndDate
When the appointment ends in Unix timestamp.
Duration
An integer representing the appointment duration in minutes.
ServiceName
The name of the service.
ServiceId
The ID of the service.
LocationName
The name of the location.
LocationId
The ID of the location.
PractitionerEmail The email of the practitioner associated with this appointment.
PractitionerName The name of the practitioner associated with this appointment.
Price The appointment price.
IntakeId If this appointment is associated with an intake form, this field will provide the IntakeId that can be used to retrieve the form using the Intake Forms' API.
DateCreated When the appointment was created in Unix timestamp.
BookedByClient Will be true when the appointment was created by the client using the booking widget, or false when the appointment was created by the staff.
CreatedBy The name of the person who created the appointment. It can be the name of a client or of a staff member.

AppointmentPackageId If this appointment is part of a package, this filed will contain the ID of the package.

AppointmentPackageName If this appointment is part of a package, this filed will contain the name of the package.

Query Appointments

Use this method to query appointments in your organization. The results will be ordered by Date in descending order.

[GET]
/appointments?client=[searchString]&startDate=[yyyy-MM-dd]&endDate=[yyyy-MM-dd]&status=[status]&practitionerEmail=[practitionerEmail]&page=[pageNumber]

This method accepts the following query string parameters:

  • client (optional) – A string used to search the client by name or email. Partial matches will be respected, so a search for “Paul” will return appointments for clients with Paul in their names. Likewise, a search for “paul.smith@gmail.com” will return appointments for that specific client.
  • startDate (optional) – Return only appointments that are scheduled for after the specified date. Use the following date format: yyyy-MM-dd (ex.: 2016-08-21)
  • endDate (optional) – Return only appointments that are scheduled for before the specified date. Use the following date format: yyyy-MM-dd (ex.: 2016-08-21)
  • status (optional) – Possible values are "Confirmed", "Canceled", "WaitingConfirmation", "Declined" and "Missed".
  • practitionerEmail (optional) – Use this to get appointments for a specific practitioner. The email must match the email used in the practitioner IntakeQ account. If empty, appointments for all practitioners in the organization will be returned.
  • page (optional) – This method returns a maximum of 100 records. Use the page parameter to implement paging from your end. Use 1 for page 1, 2 for page 2, etc.

This method returns a JSON object representing an array of appointments.

[{
   Id: "123", 
   ClientName: "test",
   ClientEmail: "test@email.com",
   ClientPhone: "(222) 222-2222",
   ClientId: 9999,
   Status: "Confirmed", 
   StartDate: 1458526480368, //Unix timestamp,
   EndDate: 1458526484236, //Unix timestamp,
   Duration: 90, //minutes
   Service: "Initial Consultation",
   Location: "Manhattan Office",
   Price: 100.00, 	
   PractitionerEmail: "test@email.com",
   PractitionerName: "FirstName LastName"   
   DateCreated: 1458526532654, //Unix timestamp
   IntakeId: "00000000-0000-0000-0000-000000000000", //GUID
   BookedByClient: true,
   CreatedBy: "John Smith"
},...
]

This method returns a maximum of 100 records. If needed, use the page query string parameter to implement paging from your end.

Use this method to get a single appointment using its ID.

[GET] https://intakeq.com/api/v1/appointments/[appointment-id]

Refer to the appointment object above for its JSON representation.

Appointment Webhooks

You can subscribe to specific appointment events in the API settings page.

If you populate the webhook URL in the API settings page, we will send the following JSON object in a POST message every time an intake is submitted by a client:

   {
      EventType: "AppointmentCreated",
      ActionPerformedByClient: true,
      Appointment: { .... } //refer to the appointment object above
   }

Let’s look at each property individually:


Field Explanation
EventType Describes which action triggered this event. Possible values:
AppointmentCreated - triggered once when the appointment is initially created.
AppointmentConfirmed - triggered when the appointment is confirmed, either automatically or by a staff member.
AppointmentRescheduled - triggered when the date/time of the appointment has changed.
AppointmentCanceled - triggered when the appointment is canceled.
AppointmentDeclined - triggered when a staff member declined the appointment request.
AppointmentMissed - triggered when a staff member marks the appointment as missed.

ActionPerformedByClient Boolean value indicating whether the action was performed by a client using the booking widget or by a staff member.
Appointment The appointment object as defined above.

We currently provide an open source C# client library to help you use our API. Let us know if you want to contribute by building a library in a different language.

If you have any questions or need assistance, please contact us and we'll be happy to help!

Still need help? Contact Us Contact Us