API

The InTouch API lets your other systems read and update InTouch data: find a matter, save a document to it, or submit a form on a client’s behalf. This article explains what the API can do and the rules every request follows. The full reference for each endpoint, with its fields and an example request, is in your account under Settings > API.

Each request is authenticated with an API key, which a member of staff with the Can edit API keys permission creates.

What you can do with the API

Matters

• List Matters: page through your matters, filter them (for example by state or by when they were last updated) and search across matter fields. You can also find the matters linked to a phone number, such as an incoming caller’s.
• Create Matter: open a new matter from a matter template, assigned to a Fee Earner.
• Read Matter: return the fields you choose from a matter.
• Update Matter: change a matter’s fields and the details of its stakeholders.
• List Matter Tasks: return a matter’s tasks and the state of each.
• Complete Task: complete a task on a matter. A task that only a supervisor or the matter’s Fee Earner can complete, or that waits on another task, is refused with a message saying why.

Matter folders

• List Folder Items: list the files, emails, email drafts, notes, phone calls, SMS and form completions in a matter’s Folder tab.
• Download Item: get a link to download a file, email or email draft from the folder.
• Save File: add a file to the matter.
• Save Email, Save Note and Save Phone Call: record an email, note or phone call on the matter. An email needs a sender.
• Delete Item: move a file, email, note, phone call or SMS to the trash, where staff can restore it. This needs a key with the Delete permission.

Forms

• Get Quote: calculate a form’s quote from a set of answers, without submitting the form.
• Submit - Create Matter: submit answers to a form that creates a new matter, as if a client had completed it. The submission follows the form’s own settings, such as submission review or a chained form.
• Submit - Existing Matter: submit answers to a form against a matter that already exists.

Forms submitted through the API do not support file upload, Fee Earner selection or e-signature questions. The form’s conditional logic and answer validation are not applied either, so check the answers before you send them.

Making a request

Every request must:

• be sent over HTTPS
• include the x-intouch-o-token header, holding one of your organisation’s API keys
• send its body as JSON, with the header content-type: application/json; charset=utf-8, when it has one

Send requests to the same web address you use to sign in to InTouch. The examples under Settings > API show the full address for your account. For example, this request submits a form that creates a matter:

POST /api/v2/public/form-completions/{formGuid}/matter/create
x-intouch-o-token: your-api-key
content-type: application/json; charset=utf-8

{
  "data": {
    "matter.reference": "SC/P/Tasker-HR"
  }
}

Data markers in requests

Fields in requests and responses are named by their data markers, such as matter.reference. The data markers available depend on the matter template, because each template can add its own custom fields.

To see them, navigate to Settings > API and open Data Markers. Choose a matter template to list its data markers and their types, or select Download CSV to download the data markers for every template. The data markers built into every account are listed in Built-in data markers.

Responses

A successful request returns a 2xx status code. The body holds message, success and the endpoint’s data:

{
  "message": "Success",
  "success": true,
  "data": {
    "matterGuid": "6db90198-bd3c-4656-b9e9-6070652aab52"
  }
}

A failed request returns a 4xx or 5xx status code, usually with a message and, where there is more detail, a list of errors:

{
  "message": "Invalid request data",
  "success": false,
  "errors": [
    "A required field is missing."
  ]
}

We add new fields to responses over time, so your integration should ignore any fields it does not recognise rather than reject the response.

Errors

Status code	What it means	What to check
400 Bad Request	The request was malformed or incomplete	The JSON is valid and every required field is included. The errors in the response say what is wrong
401 Unauthorized	The API key is missing or not valid	The x-intouch-o-token header is included and holds a current key
403 Forbidden	The key does not have the permission this endpoint needs	The key’s Read, Write and Delete permissions. The message names the one that is missing
404 Not Found	The resource does not exist	The endpoint path and the identifiers in it
429 Too Many Requests	You have exceeded the rate limit	Wait before retrying (see below)
500 Internal Server Error	Something went wrong on our side	Retry after a delay. If it keeps happening, contact support@intouch.cloud

Rate limits and retries

Every endpoint is rate limited, to protect the service and keep it fair for every account. When you exceed a limit, the API responds with 429 Too Many Requests, and its Retry-After header gives the number of seconds to wait.

We cannot guarantee the API is available 100% of the time, so build in failure handling. When you receive a response outside the 2xx range, log it, decide whether the request is safe to send again, and wait before retrying, increasing the wait after each failure. Take care when retrying a request that creates something, such as a matter, so that you do not create it twice.

OpenAPI definition

The API is also described in an OpenAPI definition, a standard machine-readable format that API tools can import to generate code or test requests. Open it from the link on the Overview page under Settings > API.

Webhooks

To have InTouch tell your systems when something happens, rather than asking the API, use webhooks.