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.

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
• Query Appointments
• Retrieve an Appointment
• Retrieve Booking Settings
• Create an Appointment
• Update an Appointment
• Cancel an Appointment
• Webhooks

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",
   ClientDateOfBirth: "1988-05-23",
   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"	
	},
    Procedures: [
        {
            ProcedureCode: "11901",
            Price: 90,
            Units: 1,
            Modifiers: ["26"]
        }
    ],
    AdditionalClients: [
        ClientId: 9999,
        ClientName: "Name Test",
        ClientEmail: "test@email.com",
        ClientPhone: "2222222222",
        IntakeId: "00000000-0000-0000-0000-000000000000", //GUID

    ]
}

Let’s look at each property individually:

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]&updatedSince=[yyyy-MM-dd]&deletedOnly=[bool]

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.
• updatedSince (optional) – Returns only appointments that have been changed after a given date.
• deletedOnly (optional)  – Returns only appointments that have been deleted. Deleted appointments can be retrieved up to 10 days after they have been deleted. Appointments that have been deleted more than 10 days prior cannot be retrieved anymore. 

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

[{
   Id: "123", 
   ClientName: "test",
   ClientEmail: "test@email.com",
   ClientPhone: "(222) 222-2222",
   ClientDateOfBirth: "1988-05-23",
   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
   ExternalClientId: "xxxx",   
   BookedByClient: true,
   CreatedBy: "John Smith"
},...
]

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
      ClientId: 123,
      PracticeId: "xxxxxx",
      ExternalPracticeId: "xxxxxx", // for partners only
      ExternalClientId: "xxxx" // for partners only   
  }

Let’s look at each property individually: