IntakeQ Questionnaire API

Overview

The IntakeQ API is composed of HTTP endpoints that can be reached through a REST API. Additionally, you can setup a webhook that’s fired when a client submits an intake package; giving you the opportunity to download it in realtime and integrate with 3rd party software.

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/intakes/[intake-id]

Authentication

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

X-Auth-Key:xxxxxxxxxxxxxxxxxxxxxxxxx

Jump to a Method

Query Intake Forms

Use this method to query client intake form summaries. The result set does not contain all the contents of the intake forms, but only their basic information (id, status, client info).

[GET]
/intakes/summary?client=[searchString]&startDate=[yyyy-MM-dd]&endDate=[yyyy-MM-dd]&page=[pageNumber]&all=[bool]&clientId=[clientId]&externalClientId=[externalClientId]&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 all intakes for clients with Paul in their names. Likewise, a search for "paul.smith@gmail.com" will return all intakes for that specific client.
  • startDate (optional) – Returns only intakes that were created after the specified date. Use the following date format: yyyy-MM-dd (ex.: 2016-08-21)
  • endDate (optional) – Returns only intakes that were created before the specified date. Use the following date format: yyyy-MM-dd (ex.: 2016-08-21)
  • 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.
  • all (optional) – By default, only submitted forms are returned. Set this parameter to true if you want this method to return all intakes, regardless of their status.
  • clientId (optional) – Returns only intakes from a specific client using the client ID number.
  • externalClientId (optional) – Returns only intakes from a specific client using an external client ID string that you have specified when saving a client using the Clients API.
  • updatedSince (optional) – Returns only intakes that have been changed after a given date.
  • deletedOnly (optional)  – Returns only intakes that have been deleted. Deleted intakes can be retrieved up to 10 days after they have been deleted. Intakes that have been deleted more than 10 days prior cannot be retrieved anymore. 

If no query string parameter is passed, the method will return the last 100 submitted intakes.

This method returns a JSON object representing an array of intake forms.

[{
   Id: "00000000-0000-0000-0000-000000000000", //GUID
   ClientName: "test",
   ClientEmail: "test@email.com",
   ClientId: 9999,
   Status: "Completed", 
   DateCreated: 1458526480368, //Unix timestamp in milliseconds,
   DateSubmitted: 1458526532654, //Unix timestamp in milliseconds
   QuestionnaireName: "test",
   QuestionnaireId: "1234acbd",
   Practitioner: "test@email.com",
   PractitionerName: "FirstName LastName",
   ExternalClientId: "acbd"
},...
]

Let’s look at each property individually:

Field Explanation
Id The ID of the intake form. You can use this to get the full intake.
ClientName The name of the client who submitted the intake form.
ClientEmail
The email of the client associated with the intake form.
ClientId
The ID number of the client associated with the intake form.
Status Possible values:
Sent – Client has not started filling out the form.
Partial – Client has started filling out the form.
Completed – Form has been submitted.
Offline – Client chose to fill out by hand.
DateCreated When the form was created in Unix timestamp (milliseconds).
DateSubmitted When the client submitted the form in Unix timestamp (milliseconds). Null if form has not been submitted.
QuestionnaireName The name of the form template.
QuestionnaireId The ID of the questionnaire template used to create this intake.
Practitioner The email of the practitioner associated with the intake (for accounts with multiple practitioners)
PractitionerId The ID of the practitioner associated with the intake (for accounts with multiple practitioners)
ExternalClientId The external client ID of the client associated with the intake

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

Download Intake Form PDF

Use this method to download a client’s complete intake package as a PDF file.

[GET]
https://intakeq.com/api/v1/intakes/[intake-id]/pdf

Use this method to download a client’s consent form from an intake package as a PDF file.

[GET] 
https://intakeq.com/api/v1/intakes/[intake-id]/consent/[consent-form-id]/pdf

Get Full Intake Form

Use this method to get a full intake form in JSON format.

[GET] https://intakeq.com/api/v1/intakes/[intake-id]

The full intake form is very similar to intake summary object, except it adds an array of questions.

{
   Id: "00000000-0000-0000-0000-000000000000",
   ClientName: "test",
   ClientEmail: "test@email.com",
   ClientId: 9999,
   Status: "Completed", 
   DateCreated: 1458526480368, //Unix timestamp in milliseconds,
   DateSubmitted: 1458526532654, //Unix timestamp in milliseconds
   QuestionnaireName: "test",
   Practitioner: "test@email.com",
   PractitionerName: "FirstName LastName",	
   Questions: [...], //See Question structure below 
   AppointmentId: "xxxxxxxx", //only if form is associated with appointment
   ExternalClientId: "abcd",
   ConsentForms: [
      {
	Id: "00000000-0000-0000-0000-000000000000",
        Name: "HIPAA Release Form",
	DocumentType: "Html",
        Signed: true,
        DateSubmitted: 1458526532654, //Unix timestamp in milliseconds
     }
   ]
}

The Question Object

Because we support several question types, the question structure is a little more complex. We use a common structure for all questions, but certain properties will be populated and others will be empty, depending on the question type. This makes things simpler when you’re deserializing the JSON response using static languages.

Here’s an example of a question array:

 [
    {
        Id: "xxxx-1",
        Text: "Full name",
        Answer: "Dexter Morgan",
        QuestionType: "OpenQuestion",
        Rows: [],
        ColumnNames: [],
	OfficeUse: false,
	OfficeNote: null,<br>	ClientProfileFieldId: "FullName"
    },
    {
        Id: "xxxx-2",
        Text: "Address",
        Answer: "134 Silk Road",
        QuestionType: "OpenQuestion",
        Rows: [],
        ColumnNames: [],
	OfficeUse: false,
	OfficeNote: null,
	ClientProfileFieldId: "StreetAddress"
    },
    {
        Id: "o5iF-1",
        Text: "Please indicate if you or any family members have ever had any of the following problems. Specify who.",
        Answer: "High Cholesterol",
        QuestionType: "MultipleChoice",
        Rows: [],
        ColumnNames: []
    }, {
        Id: "4dHk-1",
        Text: "Please list your top major health concerns in order of importance, and indicate date of diagnosis (where relevant):",
        Answer: null,
        QuestionType: "Matrix",
        Rows: [
            {
                Text: "1",
                Answers: ["High Cholesterol", "Feb 2016"]
            },
            {
                Text: "2",
                Answers: ["", ""]
            }
        ],
        ColumnNames: ["Concern", "Date"],
	OfficeUse: false,
	OfficeNote: "Test note from practitioner.",
	ClientProfileFieldId: null
    }, {
        Id: "efiE-1",
        Text: "Please upload your insurance card.",
        Answer: null,
        QuestionType: "Attachment",
	Attachments: [
		{
		    Id: "352420dfnkdfsd9321j294k",
		    Url: "https://intakeq.com/api/v1/attachments/352420dfnkdfsd9321j294k",
		    ContentType: "image/png",
		    FileName: "insurance.png"
		}
	],
        Rows: [],
        ColumnNames: [],
	OfficeUse: false,
	OfficeNote: null,
	ClientProfileFieldId: null
    },

Notice that you can use the QuestionType field to figure out which fields will be populated (e.g. the Matrix question type will have Rows and Columns). Or you can use the question Id field to get specific questions.

For questions of the type "Attachment", an array of attachments will be provided (as shown above), and you can use the URL property to download the file. It's important to note that the API key must be included in the header of the download request as well.

List Questionnaire Templates

Use this method to get a list of questionnaire templates. This list is useful for learning the ID of each questionnaire so it can be used in the Send Questionnaire method (see next section).

[GET] https://intakeq.com/api/v1/questionnaires

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

[
	{    
		Id: "00000000-0000-0000-0000-000000000000",    
		Name: "Patient Intake Form",    
		Archived: false,    
		Anonymous: false,    
	},
	...
]

List Practitioners

Use this method to get a list of practitioners in the account. This list is useful for learning the ID of each practitioner so it can be used in other methods.

[GET] https://intakeq.com/api/v1/practitioners

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

[
	{    
		Id: "00000000-0000-0000-0000-000000000000",    
		CompleteName: "Dexter Morgan",    
		FirstName: "Dexter",    
		LastName "Morgan",
		Email: "dexter@email.com",
		ExternalPractitionerId: "002" //for partners only    
	},
	...
]

Send a Questionnaire

This endpoint allows you to send an intake package using the API.

[POST] https://intakeq.com/api/v1/intakes/send

To send a form, post a JSON document using the specification below.

{     		
	QuestionnaireId: "00000000-0000-0000-0000-000000000000",     		
	ClientId: 123, //mandatory if ClientName and Email and Phone are not provided
	ClientName: "Dexter Morgan", //mandatory if ClientId is not provided
	ClientEmail: "dexter@email.com",//mandatory if ClientId or Phone are not provided
	ClientPhone: "2222222222", //provide phone and leave email empty to send via SMS 
	PractitionerId: "00000000-0000-0000-0000-000000000000",
	ExternalClientId: "abcd" //for partners only
}

The preferred delivery method is Email. To force delivery via SMS, leave the ClientEmail field empty and provide the destination number in the ClientPhone field.

If the form is sent successfully, this method will return an Intake object as described in the Get Full Intake section.

Let’s look at each property individually:

Field Explanation      
QuestionnaireId The ID of the intake package. You can get this from the List Questionnaires method, or by opening the questionnaire template in IntakeQ and getting it from the browser address      
ClientName Mandatory only if ClientId is not provided. When used, provide first and last name.      
ClientEmail Mandatory only if ClientId and ClientPhone are not provided.    
ClientPhone Mandatory only if ClientId and ClientEmail are not provided. When ClientEmail is not provided and ClientPhone is provided, the form will be sent via SMS.     
PractitionerId The ID of the practitioner associated with this intake. If not provided, IntakeQ will try to use the practitioner who is already associated with this client. If that fails, IntakeQ will use the main account practitioner. If the main account is not a practitioner, the method will fail      
ClientId The ID of the client. This is a positive integer and can be retrieved using the /clients endpoint. When this field is provided, IntakeQ will ignore the ClientName and ClientEmail fields and look for an exact match on the ClientId to find an existing client. If the client is not found, the method will fail.
ExternalClientId The External ID of the client. This is a string and can be managed using the /clients endpoint. When this field is provided, IntakeQ will ignore the ClientName and ClientEmail fields and look for an exact match on the ExternalClientId to find an existing client. If the client is not found, the method will fail.

Update Office Use Questions

This endpoint allows you to update answers to Office Use questions.

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

The recommended way to use this method is to first get the full form object using the full intake endpoint, populate the desired Answer fields and post it back to the URL above.

When the intake is updated, IntakeQ will process all the client profile mappings, pinned note mappings and tagging rules, if applicable.

At this time it's not possible to update the following question types: Matrix, Attachment, e-signature.

Resend a Questionnaire

This endpoint allows you to send an intake package using the API.

[POST] https://intakeq.com/api/v1/intakes/resend

To resend an existing form, post a JSON document using the specification below.

{     		
	IntakeId: "00000000-0000-0000-0000-000000000000",     		
	DeliveryMethod: "sms" //optional. Possible values: null, "sms" or "email" 
}

All you need to provide when resending a form, is the intake ID. The DeliveryMethod field only needs to be provided if you want to change it from SMS to email or email to SMS.

When changing the original delivery method, make sure the client record is populated with the corresponding delivery method (e.g. if SMS, make sure the client record has a phone number). Use the Client API if needed.

If the form is resent successfully, this method will return an Intake object as described in the Get Full Intake section.

This method will return an error if the form has already been completed by the client.

Let’s look at each property individually:

Field Explanation      
IntakeId The ID of the intake package that was previously sent.      
DeliveryMethod Optional. Can be "sms" or "email". Leave it empty to reuse the delivery method that was used last time the form was sent.      

Query and Save Clients

To query and save clients, refer to this article: IntakeQ Client API

Intake Submission Webhook

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:

   {
      IntakeId: "00000000-0000-0000-0000-000000000000",
      Type: "Intake Submitted",
      ClientId: 123,
      ExternalPracticeId: "xxxxxx", // for partners only
      ExternalClientId: "xxxx" // for partners only
   }

Once you have the Intake ID, you can use it to get the full intake or download the PDF. The Client ID allows you to use the client search endpoint to get the client object.

Client Libraries

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.

Still need help? Contact Us Contact Us

Related Articles