IntakeQ Partner API

The IntakeQ Partner API is composed of HTTP endpoints that can be reached through a REST API.

This API is reserved for IntakeQ partners who offer white-labeled forms functionality.

Before being able to use this API, IntakeQ partners should get in touch with IntakeQ's management team in order to have a partner website provisioned.  

For the Intake Forms API, please refer to this article.

Jump to a Section

Authentication

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

X-Auth-Key:xxxxxxxxxxxxxxxxxxxxxxxxx

In order to obtain your API key, reach out to your point of contact at IntakeQ.

Never expose your Partner API key in plain text (config files, source control) or use it on client side code that runs in the browser. The Partner API Key is extremely sensitive and should only be used on server-to-server requests. 

Base URL

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

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

[GET] https://intakeq.com/api/partner/practice?id=123

Role Management

On a regular IntakeQ practice account, roles are customizable, and each practice can create as many roles as they wish ( see more details here). In the whitelabeled version of IntakeQ, we decided not to expose the role customization feature to the end user, as access control is typically already managed in the parent application. However, when creating practitioners and assistants you are still able to assign a role for each account. These roles will be created and managed by you (the partner) in a master account that will be provisioned by IntakeQ. 

In other words, you will use a user interface to create standard roles in a master account, and later assign these roles to the users that you create using the /practitioners and /assistants endpoints. As you will see further below, the role assignment will be done by the role name. By default, practitioners and assistants are assigned an Administrator role, which allows them to send forms, open forms, edit form templates, etc. 

Create Practice

Use this method to create a new Practice account. 

[POST] https://intakeq.com/api/partner/practice
X-Auth-Key: [Partner Key]

The body of the POST request should contain a JSON object in the following format:

{
    "PracticeName": "ABC Health", (required)
    "FirstName":"John", //First name of the main practice user (required)
    "LastName": "Smith", //Last name of the main practice user, (required)
    "Email":"abc@email.com", //Email associated with the main practice user (required)
    "ExternalPracticeId": "1234", //A key that you can use to retrieve this practice later (optional)	
}

Things to note:

  • When provided, the ExternalPracticeId must be unique across all your practices.

A successful response to this method will return the same object with an additional Id field and a DateCreated field. It's a common practice to store the practice Id in your own database in order to reference it in other API calls.

Response example:

{
    "Id": "54DC9E8F", //Practice Id
    "PracticeName": "ABC Health", 
    "FirstName":"John", 
    "LastName": "Smith", 
    "Email":"abc@email.com", 
    "ExternalPracticeId": "1234", 
    "DateCreated": "yyyy-MM-ddThh:mm:ss.000Z", 	
    "StreetAddress": "123 Remedy Lane",
    "City": "New York",
    "State": "NY",
    "PostalCode": "12345",
    "FormsEnabled": true,
    "BookingEnabled": false
}

Update Practice

Use this method to update an existing Practice account. 

[PUT] https://intakeq.com/api/partner/practice
X-Auth-Key: [Partner Key]

The body of the PUT request should contain a JSON object in the following format:

{
    "Id": "1234", //(required if ExternalPracticeId is empty)
    "PracticeName": "ABC Health", (required)
    "FirstName":"John", //First name of the main practice user (required)
    "LastName": "Smith", //Last name of the main practice user, (required)
    "Email":"abc@email.com", //Email associated with the main practice user (required)
    "ExternalPracticeId": "1234", //(required if Id is empty)	
    "StreetAddress": "123 Remedy Lane",
    "City": "New York",
    "State": "NY",
    "PostalCode": "12345",
    "FormsEnabled": true,
    "BookingEnabled": false
}

A successful response to this method will return the same object with an additional Id field and a DateCreated field. It's a common practice to store the practice Id in your own database in order to reference it in other API calls.

Response example:

{
    "Id": "54DC9E8F", //Practice Id
    "PracticeName": "ABC Health", 
    "FirstName":"John", 
    "LastName": "Smith", 
    "Email":"abc@email.com", 
    "ExternalPracticeId": "1234", 
    "DateCreated": "yyyy-MM-ddThh:mm:ss.000Z", 
    "StreetAddress": "123 Remedy Lane",
    "City": "New York",
    "State": "NY",
    "PostalCode": "12345",
    "FormsEnabled": true,
    "BookingEnabled": false	
}

Delete Practice

Use this method to delete an existing practice.  

[DELETE] https://intakeq.com/api/partner/practice/[practiceId]
X-Auth-Key: [Partner Key]

For the practiceId parameter in the URL above, you can use the Id field or the ExternalPracticeId.

Retrieve Practices

Use this method to retrieve multiple practices or a specific practice. 

[GET] https://intakeq.com/api/partner/practice?id=123&email=practice@email.com&externalPracticeId=123
X-Auth-Key: [Partner Key]

To get all practices associated with your Partner API Key, call this method without any query string parameters.

To get a specific practice, pass 1 of the 3 parameters in the query string: id, email or externalPracticeId.

The method will always return an array, even when you are querying for a specific practice.

[
  {
    "Id": "ACB123", //Practice Id
    "PracticeName": "ABC Health", 
    "FirstName":"John", 
    "LastName": "Smith", 
    "Email":"abc@email.com", 
    "ExternalPracticeId": "1234", 
    "DateCreated": "yyyy-MM-ddThh:mm:ss.000Z",
    "StreetAddress": "123 Remedy Lane",
    "City": "New York",
    "State": "NY",
    "PostalCode": "12345" 	
  },
  {
    "Id": "123ABC", //Practice Id
    "PracticeName": "My Practice", 
    "FirstName":"Larry", 
    "LastName": "David", 
    "Email":"larry@email.com", 
    "ExternalPracticeId": "001", 
    "DateCreated": "yyyy-MM-ddThh:mm:ss.000Z",
    "StreetAddress": "123 South Park Street",
    "City": "New York",
    "State": "NY",
    "PostalCode": "12345" 	
  },
 ...
]

Get Practice API Key

Use this method to retrieve the API key for a given practice. The practice API key can be used to access API methods in the practice scope (send forms, manage clients, manage practitioners, etc).

[GET] https://intakeq.com/api/partner/practice/[practiceId]/key
X-Auth-Key: [Partner Key]

In the URL above, replace the [id] parameter with the practice Id, or the externalPracticeId that you provided when creating the practice.

The result for this request is in the following format:

{
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}

Get Ephemeral Token

This GET method generates a token for a practice user that can be used to perform single sign-on on the white-labeled version of IntakeQ. 

[GET] https://intakeq.com/api/partner/practice/[practiceId]/ephemeral?userId=123
X-Auth-Key: [Partner Key]

The practiceId parameter can be the practice Id or the externalPracticeId you provided when creating the practice.

The userId parameter in the query string is optional. You can pass the practitioner ID or the externalPractitionerId. If omitted, the ephemeral token will be created for the practice main admin user.

The result for this request contains the token and the user ID that you will need to authenticate this user in the UI (see next section).

{
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "userId": "33a23c42b286e76cca15c"
}

Single Sign-On

The ephemeral token created in the section above can be used to authenticate a user from your system onto the white-labeled IntakeQ website. To authenticate a user, redirect them to the following URL:

[GET] https://[forms.yourdomain.com]/signin/authenticate?token=[token]&userId=[userId]

IntakeQ will validate the token and create a new session so that the user can access the white-labeled website. 

Note that the ephemeral token can only be used once, but since IntakeQ uses cookie-based authentication, the session will stay active for 1 hour.

Once a user is authenticated, IntakeQ will automatically redirect them to the dashboard page. Optionally, you can specify which page to open by adding a path parameter to the query string. The supported values are intakes, templates, settings and report. Here's an example of a redirect that authenticates the user and opens the form templates page:

/signin/authenticate?token=[token]userId=[userId]&path=templates

If you are using our system in iframe mode, you may want to terminate the user session when they sign out of your application. In order to do this, use this code in the iframe host to trigger a logout event in the iframe:

  document.getElementById('[iframe id here]').contentWindow.postMessage("iq_logout", '*')

Create Practitioner

The main practice account is also a practitioner, but depending on your use-case you may need to add more than one practitioner to the practice account.

[POST] https://intakeq.com/api/v1/practitioners
X-Auth-Key: [Practice Key]

Notice that the URL above is part of the api/v1 group, and, unlike the previous endpoints in this document, you should pass the practice API key in the X-Auth-Key header. This is how IntakeQ will associate this practitioner with the proper practice.

The expected body for this request is described below:

{
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "js@email.com",
    "RoleName": "Administrator",
    "ExternalPractitionerId": "abcd" //optional 
}

When provided, the ExternalPractitionerId must be unique across the practitioners from this particular practice.

The response for this method will contain the practitioner Id field, which you can store in order to refer to this practitioner later.

{
    "Id":"43b471c0877aa6ec92556bee1",	
    "CompleteName": "John Smith",	
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "js@email.com",
    "RoleName": "Administrator",
    "ExternalPractitionerId": "abcd" 
}

Update Practitioner

Use this method to update the email, name or role of a practitioner.

[PUT] https://intakeq.com/api/v1/practitioners
X-Auth-Key: [Practice Key]

Notice that the URL above is part of the api/v1 group, and, unlike most endpoints in this document, you should pass the practice API key in the X-Auth-Key header. This is how IntakeQ will associate this practitioner with the proper practice.

The expected body for this request is described below:

{
    "Id": "43b471c0877aa6ec92556bee1", //optional if ExternalPractitionerId is provided	
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "js@email.com",
    "RoleName": "Administrator",//role must exist in your Seed Account  
    "ExternalPractitionerId": "abcd" //optional if Id is provided
}

List Practitioners

Use this method to get a list of practitioners for a given practice. Make sure to use the practice API key in the X-Auth-Key header, instead of the partner API key.

[GET] https://intakeq.com/api/v1/practitioners
X-Auth-Key: [Practice Key]

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

[
  {
    Id: "43b471c0877aa6ec92556bee1",    
    CompleteName: "Dexter Morgan",    
    FirstName: "Dexter",    
    LastName "Morgan",
    Email: "dexter@email.com",
    RoleName: "Administrator", //role must exist in your Seed Account                
    ExternalPractitionerId: "0002"
  },
   ...
]

Disable Practitioner

Use this method to disable an existing practitioner. 

[POST] https://intakeq.com/api/v1/practitioners/[practitionerId]/disable
X-Auth-Key: [Practice Key]

For the practitionerId parameter in the URL above, you can use the Id field or the ExternalPractitionerId.

Enable Practitioner

Use this method to re-enable a practitioner that has been previously disabled. 

[POST] https://intakeq.com/api/v1/practitioners/[practitionerId]/enable
X-Auth-Key: [Practice Key]

For the practitionerId parameter in the URL above, you can use the Id field or the ExternalPractitionerId.

Delete Practitioner

Use this method to delete an existing practitioner.  

[DELETE] https://intakeq.com/api/v1/practitioners/[practitionerId]
X-Auth-Key: [Practice Key]

For the practitionerId parameter in the URL above, you can use the Id field or the ExternalPractitionerId.

This method will fail if there is any client data (clients, forms, appointments, etc.) associated with the practitioner. You may need to use the Transfer Client Data method before deleting a practitioner.

Transfer Client Data

Use this method to transfer client data from one practitioner to another.

[POST] https://intakeq.com/api/v1/practitioners/[sourcePractitionerId]/transferData/[destinationPractitionerId]
X-Auth-Key: [Practice Key]

For the practitionerId parameters in the URL above, you can use the Id field or the ExternalPractitionerId.

Transfer Client Ownership

Use this method to transfer client ownership from one practitioner to another. This is useful when a practitioner is leaving a practice and you want to move clients to another practitioner without affecting historical data. This method is typically called before a practitioner is disabled.

[POST] https://intakeq.com/api/v1/practitioners/[sourcePractitionerId]/transferClientOwnership/[destinationPractitionerId]
X-Auth-Key: [Practice Key]

For the practitionerId parameters in the URL above, you can use the Id field or the ExternalPractitionerId.

Create Assistant

Assistant accounts allow you to give access to users who are not practitioners. Assistants are able to view and perform actions on behalf of practitioners, but forms can only be assigned to practitioners. 

[POST] https://intakeq.com/api/v1/assistants
X-Auth-Key: [Practice Key]

Notice that the URL above is part of the api/v1 group, so you should pass the practice API key in the X-Auth-Key header. This is how IntakeQ will associate this assistant with the proper practice.

The expected body for this request is described below:

{
    "Name": "John Smith",
    "Email": "js@email.com",
    "RoleName": "Administrator", //role must exist in your Seed Account        
    "ExternalAssistantId": "abcd", //optional  
    "PractitionerIds": ["43b471c0877aa6ec92556bee1"], //optional  
}

If you want the assistant to have access to all practitioners in the practice, leave the PractitonerIds property empty, otherwise, specify the practitioner IDs (or external IDs) in this request.

Update Assistant

Use this method to update the email, name or role of an existing assistant.

[PUT] https://intakeq.com/api/v1/assistants
X-Auth-Key: [Practice Key]

Notice that the URL above is part of the api/v1 group, so you should pass the practice API key in the X-Auth-Key header. This is how IntakeQ will associate this assistant with the proper practice.

The expected body for this request is described below:

{
    "Id": "43b471c0877aa6ec92556bee1", //optional if ExternalAssistantId is provided
    "Name": "John Smith",
    "LastName": "Smith",
    "Email": "js@email.com",
    "RoleName": "Administrator", //role must exist in your Seed Account      
    "ExternalAssistantId": "abcd", //optional if Id is provided 
    "PractitionerIds": [] 
}

If you want the assistant to have access to all practitioners in the practice, leave the PractitonerIds property empty, otherwise, specify the practitioner IDs (or external IDs) in this request.

List Assistants

Use this method to get a list of assistants for a given practice. Make sure to use the practice API key in the X-Auth-Key header, instead of the partner API key.

[GET] https://intakeq.com/api/v1/assistants
X-Auth-Key: [Practice Key]

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

[
  {
    Id: "43b471c0877aa6ec92556bee1",
    Name: "Dexter Morgan",
    Email: "dexter@email.com",
    RoleName: "Administrator", 
    ExternalAssistantId: "0002" 
    PractitionerIds: []   	
  },
 ... 
]

Delete Assistant

Use this method to delete an existing assistant. 

[DELETE] https://intakeq.com/api/v1/assistants/[assistantId]
X-Auth-Key: [Practice Key]

For the assistantId parameter in the URL above, you can use the Id field or the ExternalAssistantId.

Create Intake Form

This method allows intakeQ partners to create an intake form without sending it to the client. Partners can use this method if they want to control how the form is sent to the client, or they can make use of the authentication method below in order to control how the client logs into a form. Make sure to use the practice API key in the X-Auth-Key header, instead of the partner API key.

[POST] https://intakeq.com/api/v1/intakes/create
X-Auth-Key: [Practice Key]

To create 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", 
    PractitionerId: "00000000-0000-0000-0000-000000000000",
    ExternalClientId: "abcd" //you can use this instead of ClientId
}

If the form is created successfully, this method will return an Intake object as described below. Note that the form object contains the form URL and its password, allowing you to control how this information is presented to the client.

{
    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",
    Url: "https://intakeq.com/intake/xxxxx",
    Password: "345835",
    ConsentForms: [
      {
	Id: "00000000-0000-0000-0000-000000000000",
        Name: "HIPAA Release Form",
	DocumentType: "Html",
        Signed: true,
        DateSubmitted: 1458526532654, //Unix timestamp in milliseconds
     }
   ]
}

Create Form Authentication Token

This method allows intakeQ partners to create a form authentication token that can be used in the UI to log a user into a form.

To create a form authentication token, send a POST request to the URL below, replacing {id} with the ID of the specific client intake form.

[POST] https://intakeq.com/api/v1/intakes/{id}/token
X-Auth-Key: [Practice Key]

A successful request will return the following object.

{
    Token: "7ec6232d6707e85860fa25733a5b3046dd8e8147",
    Url: "https://intakeq.com/intake/xxxx"
    Expiration: "2022-04-14T15:26:42.089Z"
}

Once you have obtained the token, you can redirect the user to the form URL, passing the token in the auth parameter of the query string. Here's an example:

https://[hostname]/intake/mkdsk7ds?auth=7ec6232d6707e85860fa25733a5b3046dd8e8147

You can also tell intakeQ to redirect the user back to your website when the form is completed by passing a redirect parameter in the form URL:

https://[hostname]/intake/mkdsk7ds?auth=7ec6232d6707e85860fa25733a5b3046dd8e8147&redirect=https://mywebsite.com

List Master Forms

Use this method to get a list of master forms associated with your intakeQ partner account.

[GET] https://intakeq.com/api/partner/masterForms
X-Auth-Key: [Partner Key]

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

[
    {
    Id: "43b471c0877aa6ec92a56b003",    
    Name: "Intake Form",
    Archived: false,
    Type: "Questionnaire"
    },
    {
    Id: "43b471c0877aa6ec92556bc328",    
    Name: "Note",
    Archived: false,
    Type: "TreatmentNote"
	},
	...
]

List Practice Forms

Use this method to get a list of forms for a specific practice.

[GET] https://intakeq.com/api/partner/practice/{practiceIdOrExternalPracticeId}/forms
X-Auth-Key: [Partner Key]

The practiceIdOrExternalPracticeId parameter can be the practice Id or the externalPracticeId you provided when creating the practice.

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

[
  {
    Id: "43b471c0877aa6ec92556bcc4",    
    Name: "Intake Form",
    Archived: false,
    Type: "Questionnaire"
  },
  {
    Id: "43b471c0877aa6ec92556bdd5",    
    Name: "Note",
   Archived: false,
    Type: "TreatmentNote"
  },
  ...
]

Copy Form

Use this method to copy a form from your master account to a practice.

[POST] https://intakeq.com/api/partner/practice/copyForm
X-Auth-Key: [Partner Key]

The body of the POST request should contain a JSON object in the following format:

{
    "SourceMasterFormId": "43b471c0877aa6ec92556bcc4", (required) 	
    "DestinationPracticeId": "1234", (required) 	
    "CopyAttachedConsentForms": true
}

Response example:

{
    Id: "43b471c0877aa6ec945679c4d2",    
    Name: "Intake Form",
    Archived: false,
    Type: "Questionnaire"
}

Staff Form Notification URL

There is a setting in the white-label admin portal that you can set to specify the URL that is sent in the notification to the practice staff. This allows your system to authenticate the user before they can access the form and should be a URL that is handled by your system. 

Once the user is authenticated (via a login page or verifying that they have an active session), please redirect them to IntakeQ by using the single sign-on method. 

To open our system on a specific form, your redirect URL would look like this:

[GET] https://[forms.yourdomain.com]/signin/authenticate?token=[token]&userId=[userId]&path=intake&pathKey=[formId]

Still need help? Contact Us Contact Us