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, email draft, SMS, note or phone call from the folder. An SMS, note or phone call downloads as a JSON record of the whole item: an SMS with its sender and recipient, and a note or phone call with its author and dates.
• 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. A note or phone call can be up to 50,000 characters of HTML; a longer one is refused with a message giving the limit.
• Delete Item: move a file, email, note, phone call or SMS to the trash, where staff can restore it. A note or phone call can only be trashed this way if it was created through the API. This needs a key with the Write and Delete permissions.

Matter accounts

These need accounts turned on for your firm. Receivables need a matter template with invoices or a ledger, and anticipated money needs one with a ledger. None of them posts to the ledger or to Xero. An update replaces the whole item, so send every field each time: a field you leave out, such as a receivable’s supplier, is cleared.

• Receivable Options: list the accounts and tax types a receivable can use.
• List Receivables, Create Receivable, Update Receivable and Void Receivable: read a matter’s receivables, add one, or change or void one that is outstanding and whose supplier hasn’t been billed or paid. A receivable reaches the ledger only when staff invoice it, raise its supplier bill or pay it. To set a receivable’s supplier, send the supplier’s Contact GUID. To copy it, open the contact in InTouch and select the GUID beside Contact GUID, at the right of the window’s tabs.
• List Anticipated Money, Create Anticipated Money, Update Anticipated Money and Delete Anticipated Money: read and maintain a matter’s anticipated client money, for any date. It becomes a real transaction only when staff post it from the ledger. If an update says the entry was not found, staff have posted or removed it, so don’t create it again or the money is counted twice. Deleting an entry can’t be undone, and needs a key with the Write and Delete permissions.

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 usually 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 saying why and success: false. A 401 for a missing or invalid key has only the message. When a required field is missing, a field is longer than its limit or a value is the wrong type, the message is Invalid request data and the reasons are listed in errors:

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

Every other failure gives its reason in message alone. errors is then empty or left out, so treat a missing errors as empty. Each endpoint’s page under Settings > API lists the messages it can give.

Decide what to do from the status code, not the message. Messages are written for people and may be reworded, so log them and show them rather than matching on their text. The exceptions are the messages an endpoint’s page tells you to act on, which are kept the same.

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

Any endpoint can give these:

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. For Invalid request data, the reasons are in errors. A body that is missing or is not JSON gives a message starting No request data received
401 Unauthorized	The API key is missing, not valid or not a key for this API	The x-intouch-o-token header is included and holds a current key. This response has only a message
403 Forbidden	The key does not have the permission this endpoint needs	The key’s Read, Write and Delete permissions. An endpoint that deletes needs both Write and Delete. The message names only the first permission missing, in that order, so check the others too
404 Not Found	The resource does not exist	The endpoint path and the identifiers in it. An identifier that is not a GUID gives a 404 whose body is not JSON
429 Too Many Requests	You have exceeded the rate limit	Wait for the number of seconds in the Retry-After header before retrying (see below)
500 Internal Server Error	Something went wrong on our side	An unexpected error’s message gives an error ID, which is also in the response’s apiErrorId. Some endpoints give a 500 of their own instead, listed on their page. Either way, the change may have been saved before the error, so before repeating a request that creates something, check whether it was made, for example with List Folder Items or List Matters. A receivable or anticipated money sent again with the same guid is not added twice. Then retry after a delay. If it keeps happening, contact support@intouch.cloud and quote the error ID

Endpoints also give refusals of their own. For example, a matter that can’t be found is a 404 on most endpoints but a 400 on some. Each endpoint’s page lists its own.

Rate limits and retries

Every endpoint is rate limited, to protect the service and keep it fair for every account. The standard allowance is 60 requests per 60 seconds for your organisation. It is shared across all of your organisation’s API keys, so adding a key doesn’t add to it, and it covers all the endpoints together rather than each one separately. The allowance is higher at quiet times of day, so plan around 60 a minute rather than treating it as a fixed ceiling. The download link that Download Item returns is opened without a key, and doesn’t count towards the allowance, though opening many links quickly from one address can still be refused with 429 Too Many Requests.

When you exceed the allowance, the API responds with 429 Too Many Requests, and its Retry-After header gives the number of seconds to wait. Spread your requests out rather than sending them in bursts.

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.