Getting started

This page is for the developer making the first connection between your organisation's software and InMyWords.

It lists what has to be in place before a call is answered, the two base addresses, and the conventions every call follows. With it you can make your first call, read a list and make a change.

Before the first call

The API is offered on organisation plans only.

1. We switch the Integrations module on for your organisation. Until then your organisation has no Integrations page, and every call answers 403 module_off.
2. Somebody accepts the integrations data policy. It needs a person in your organisation with the Manage integrations permission, on the Integrations page. Until they do, every call still answers 403 module_off.
3. The same person makes a connection. On the Integrations page they give it a name and the scopes it needs. They can give a scope only if they hold the matching permission themselves.
4. Keep the key when it is shown. It appears once, when the connection is made, as imw_ followed by 64 hex characters. InMyWords keeps only a hash of it and cannot show it to you again.

A connection belongs to your organisation, not to the person who made it, so it keeps working when that person leaves.

Where to send calls

The REST API is also described as an OpenAPI 3.1 document, which needs no key. Load it into a client generator, an API gateway or Postman to start from the same paths, scopes and answers these guides describe.

Your first call

GET /me tells you which connection the key belongs to. It needs no particular scope.

curl https://app.inmywords.chat/api/integrations/v1/me \
  -H "Authorization: Bearer imw_3f9a0c2e7b1d4a6f8e0c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a"

{
  "data": {
    "connection_id": "17",
    "name": "Case management system",
    "organisation": {
      "id": "42",
      "name": "Northfield Advice Centre"
    },
    "scopes": ["conversations:read", "summaries:read", "cases:read", "cases:write"],
    "created_at": "2026-10-03T14:05:00Z"
  }
}

Reading a list

curl "https://app.inmywords.chat/api/integrations/v1/conversations?limit=20" \
  -H "Authorization: Bearer imw_3f9a0c2e7b1d4a6f8e0c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a"

{
  "data": [
    { "id": "5c0e93a17f2b4d6890ae1b4c7d3f2e05", "started_at": "2026-10-03T09:12:40Z", "ended_at": "2026-10-03T09:41:05Z" }
  ],
  "next_cursor": "eyJiIjo4ODEyfQ"
}

Lists come newest first. limit is 50 by default and 100 at most, and a larger value is reduced to 100.

To read the next page, pass next_cursor back as cursor. When next_cursor is null, you have the last page.

To fetch only what has changed, give updated_since an ISO 8601 time and you get back only what changed after it.

A limit, cursor or updated_since that cannot be read answers 400 invalid_request.

Making a change

curl -X POST https://app.inmywords.chat/api/integrations/v1/cases \
  -H "Authorization: Bearer imw_3f9a0c2e7b1d4a6f8e0c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6d1f0b7a-2c44-4f0e-9a3b-1e5c7d9f2a10" \
  -d '{"title": "Housing claim", "external_ref": "CMS-20931"}'

Send bodies as JSON, with Content-Type: application/json.

Every POST takes an Idempotency-Key header. If you send the same key and the same body again within 24 hours, you get the first result back and nothing changes, so a retry within that time is safe.

Conventions

What your organisation sees

Every call is logged against the connection, and your organisation can read the log on the connection's page. Every change, and every read of a conversation's words, is also written on your audit trail under the connection's name.

What the API never does

1. Start a conversation without a person.
2. Send a password reset, remove an authenticator or remove passkeys.
3. Erase a person.
4. Give a group Manage users, Manage billing, Manage integrations or Manage groups.