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.).

Consider setting an IP Allow-List as explained here.

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

Index

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 in milliseconds,
   EndDate: 1458526484236, //Unix timestamp in milliseconds,
   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"   
   PractitionerId: "acbdefg",
   DateCreated: 1458526532654, //Unix timestamp in milliseconds
   IntakeId: "00000000-0000-0000-0000-000000000000", //GUID
   BookedByClient: true,
   CreatedBy: "John Smith",
   AppointmentPackageId: "00000000-0000-0000-0000-000000000000", //GUID
   AppointmentPackageName: "Package Name",
   TelehealthInfo: {
		Id: "xyz",
		StartUrl: "https://mydomain.intakeq.com/videocall/123",
		Invitation: "Please join the video call using the link below: ....",
		Provider: "IntakeQ", //or Zoom
		InvitationCode: "123456"	
	}
}

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.

TelehealthInfo If this is a telehealth appointment (either IntakeQ or Zoom), this property will contain information such as Start URL and the Invitation Code.

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 in milliseconds,
   EndDate: 1458526484236, //Unix timestamp in milliseconds,
   Duration: 90, //minutes
   Service: "Initial Consultation",
   Location: "Manhattan Office",
   Price: 100.00, 	
   PractitionerEmail: "test@email.com",
   PractitionerName: "FirstName LastName"   
   DateCreated: 1458526532654, //Unix timestamp in milliseconds
   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.

Retrieve an Appointment

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.

Retrieve Booking Settings

Use this method to get a list of Services, Locations and Practitioners for your account. 

[GET] https://intakeq.com/api/v1/appointments/settings

The returned JSON follows the representation below.

{
    Locatons: [
	{
	    Id: "1",
	    Name: "Main Office"
	    Address: "123 Main Street, City, State"
	}
    ],     		 	
    Services: [
	{
	    Id: "00000000-0000-0000-0000-000000000000",
	    Name: "Initial Consultation",
	    Duration: 90,
	    Price: 200.0 
	},
	{
	    Id: "00000000-0000-0000-0000-000000000000",
	    Name: "Follow Up",
	    Duration: 60,
	    Price: 100.0
	}
    ],
    Practitioners: [
	{
	    Id: "00000000-0000-0000-0000-000000000000",    
	    CompleteName: "Dexter Morgan",    
	    FirstName: "Dexter",    
	    LastName "Morgan",
	    Email: "dexter@email.com" 
	}
    ] 	
}

Create an Appointment

This endpoint allows you to create a new appointment.

[POST] https://intakeq.com/api/v1/appointments

To create a new appointment, create a POST request containing the JSON represented below.

{     		
	PractitionerId: "5356eb98c5771321282d2ac4",     		
	ClientId: 123, 
	ServiceId: "00000000-0000-0000-0000-000000000000", 
	LocationId: "1",
	Status: "Confirmed", //Confirmed or WaitingConfirmation  
	UtcDateTime: 1458526480368, //Unix timestamp in milliseconds
	SendClientEmailNotification: true,
	ReminderType: "Sms" //Accepted values: Sms, Email, Voice, OptOut 
}

Remarks

- When creating a new appointment, all fields represented above are mandatory.

- SendClientEmailNotification can only be true if the Status is set to Confirmed.

- If the request succeeds, this endpoint will return an appointment object.

Update an Appointment

This endpoint allows you to update an existing appointment.

[PUT] https://intakeq.com/api/v1/appointments

To update an appointment, create a PUT request containing the JSON represented below.

{     		 	
	Id: "5356eb98c5771321282d2ac4",
	ServiceId: "00000000-0000-0000-0000-000000000000", //Optional  	
	LocationId: "1", //Optional	
	Status: "Confirmed", //Optional: Confirmed or WaitingConfirmation   	
	UtcDateTime: 1458526480368, //Unix timestamp in milliseconds. Mandatory 	
	SendClientEmailNotification: true, //Optional 	
	ReminderType: "Sms" //Optional. Accepted values: Sms, Email, Voice, OptOut  
}

Remarks

- An appointment cannot be changed from Confirmed to WaitingConfirmation

- The API does not support changing the client or the practitioner associated with the appointment.

- Fields like ServiceId, LocationId, ReminderType are only necessary if you are changing them. 

- If the request succeeds, this endpoint will return an appointment object.

Cancel an Appointment

This endpoint allows you to cancel an existing appointment.

[POST] https://intakeq.com/api/v1/appointments/cancellation

To cancel an appointment, create a POST request containing the JSON represented below.

{     		 	 	
	AppointmentId: "5356eb98c5771321282d2ac4", 	
	Reason: "...", //Optional
}

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 event is triggered:

   {
      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.

Still need help? Contact Us Contact Us