The Intouch Insight API is the primary means for developers to access a collection of growing resources available at Intouch Insight. Customer applications can read and write resources to help administrate various aspects of the Intouch Platform. Depending on your applications use case, you can choose from our various APIs currently implemented.

If you have a use case that it outside of our current available endpoints, please feel free to contact Client Services to help investigate your specific use case.

All of our APIs are based on REST architecture and are accessed via HTTPS. The base URL for all requests is

https://api.intouchinsight.com/public/v1/

The fully qualified URL varies depending on the endpoints of the resources being accessed. For instance, you query to retrieve a list of tags by using https://api.intouchinsight.com/public/v1/tags.

The Intouch Insight API uses key based authentication to the API. These tokens are generated and managed within the platform and should be stored securely when being used. Only admin users within the platform can manage these keys. If you do not have access to create a key, you will need to reach out to someone who has admin level access on the platform to generate a key for you.

If your organization does not have access to the Intouch Insight API, you can contact sales@intouchinsight.com for additional information. Once you have an API Key generated, you can simply add the key to every requests as an HTTP header.

curl -H "x-api-key: ii_654GTHdzbURNO734jgdBpvSe0S6pXIgtX3ZLVxHLu" https://api.staging.intouchinsight.com/public/v1/hierarchies

The API Key must be provided on every request, otherwise a resulting error of Missing Authentication Token will be generated. New keys can be added or removed as needed.

Endpoints that return multiple resources that can grow over time, and will have their results return page based properties that can be used to process of large result sets in batches.

Offset paged responses conform to the following format:

{
  "sort_by": "name",
  "order": "asc",
  "per_page": 25,
  "current_page": 1,
  "last_page": 1,
  "total": 3,
  "from": 1,
  "to": 3,
  "data": [...]
}

On top of the above response body, HTTP status codes are also used to provide additional context.

A rate limit is the number of API calls an application or user can make within a given time period. If this limit is exceeded, the application or user maybe be throttled. API requests made by a throttled user will fail.

All API requests offered as part of the Intouch Insight API are subject to rate limits. If your account has been rate limited, you will receive an HTTP response code of 429 - Too Many Requests and must wait for the rate limit to end.

Intouch Insight has worked across many different usage scenarios to set the default rate limits to be 2 requests per second for all customers. If you are hitting rate limits too often and wich to discuss additional quota scenarios, pleaes feel free to reach out to your Intouch Account Representative.

All platform Date Times in the Intouch Insight API are in ISO 8601 format.

Tags are essentially labels or keywords that can be applied to both data (questions, records, cases, follow-ups) and hierarchy nodes in the Intouch platform.

Tags can be used in a large variety of scenarios across the entire Intouch Insight Platform

• Filter/Group data sets with a similar characteristic in Intelligence/IQ (Record Tagging, Case Tagging)
• Filter/Group data sets with a similar characteristic in Check (Followup Tagging)
• Create an alternate scoring model for a program by grouping questions (Question Tagging)
• Control location listings in Survey (Hierarchy Tagging)
• Control checklist access in Check (Hierarchy Tagging)
• Control hide/show question logic in Check (Hierarchy Tagging)

Review our user guide to learn more about tags and their usage within the platform

A hierarchy is a structure that defines how a client’s locations are organized. It is often similar to how a folder directory is set up on a computer, starting with the top/main folder, and within that folder there are sub-folders, and each of the sub-folders might also contain sub-folders.

Review our user guide to learn more about hierarchies and their usage within the platform

Contacts and Contact Lists are added to facilitate Survey Distribution. That is, if you want a survey to be distributed by email to one or more specific individuals, you can accomplish that using our Contact Center. Access to the features described in these articles is restricted based on individual user settings. If you require access to IntouchSurvey or any of the features that are mentioned, contact your Program Administrator to change your permissions.

External Programs can be created within the Intouch Intelligence admin settings area to allow you to bring your own data, in any structure.

Unlike the other supported API endpoints, this requires a bit of a setup, in order to define your data properly -- as this is a dynamic API.

In order to use this endpoint, you will need to have created a new External Program in Intouch Intelligence or use an existing one already created.

Once this has been built, you will simply have to refer to the structure of that program to map it to the External Programs API endpoints.

As an example, you can use the admin interface and create the following External Program:

To add data to this program, you would use the "Add new External Programs" endpoint using the following payload:

HTTP POST > /public/v1/external-programs/{program_uuid}/records

{ 
  "data":{
    "book_category": "Fiction",
    "book_name": "The Shining",
    "book_sold_to_name": "Jane Doe",
    "book_sold_to_id": 34532,
    "book_sold_date": "2021-09-22"
  }
}

The program_uuid can be recorded on the External Program edit screen via the UUID found in the URL

A successful request will result in the data being added to the given program and available for reporting, usage, etc. within Intouch Intelligence.