Cases

This page is for the developer linking cases in your own system to cases in InMyWords.

With it you can list, read and manage cases.

A case holds the conversations and documents about one person or topic.

Before you start

1. Where to send calls. The base address is https://app.inmywords.chat/api/integrations/v1/.
2. Send your key every time. Every request carries Authorization: Bearer imw_<64 hex characters>, the key of a connection your organisation has made.
3. The scopes you need. cases:read lets you list and read cases. cases:write lets you create a case and start a conversation in one.
4. You see only your own organisation. A case of another organisation answers 404, the same as one that does not exist.
5. How values are written. Ids are strings of digits, such as "57". Times are ISO 8601 in UTC, and field names are snake_case.

What you can call

What a case holds

List your cases

Cases come newest first, sent in pages. limit is 50 by default and 100 at most.

To read the next page, pass the next_cursor of the page before as cursor. next_cursor will be null on the last page.

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

A bad limit, cursor or updated_since answers 400 invalid_request.

curl "https://app.inmywords.chat/api/integrations/v1/cases?limit=1&updated_since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer imw_3f9c..."

{
  "data": [
    {
      "id": "1207",
      "title": "Eviction notice, Flat 3",
      "reference": "HA-2026-0912",
      "external_ref": "crm-77120",
      "group": {"id": "57", "name": "Housing advice"},
      "created_at": "2026-10-01T10:02:00Z",
      "updated_at": "2026-10-02T09:41:47Z",
      "closed_at": null,
      "conversation_count": 2,
      "url": "https://app.inmywords.chat/cases/1207"
    }
  ],
  "next_cursor": null
}

Read a case

curl https://app.inmywords.chat/api/integrations/v1/cases/1207 \
  -H "Authorization: Bearer imw_3f9c..."

You get back {"data": {...}}, holding one case with the fields above.

Open a case

Send an Idempotency-Key header of up to 255 characters. If you send the same key with the same body within 24 hours, you get the first result back. The same key with a different body answers 422 idempotency_key_reused.

A new case answers 201, with the case. If your connection has used the external_ref before, you get 200 with the existing case instead, and no second case is made.

curl -X POST https://app.inmywords.chat/api/integrations/v1/cases \
  -H "Authorization: Bearer imw_3f9c..." \
  -H "Idempotency-Key: 5b1e0c4a-case-crm-77120" \
  -H "Content-Type: application/json" \
  -d '{"title": "Eviction notice, Flat 3", "external_ref": "crm-77120", "reference": "HA-2026-0912", "group_id": "57"}'

{
  "data": {
    "id": "1207",
    "title": "Eviction notice, Flat 3",
    "reference": "HA-2026-0912",
    "external_ref": "crm-77120",
    "group": {"id": "57", "name": "Housing advice"},
    "created_at": "2026-10-01T10:02:00Z",
    "updated_at": "2026-10-01T10:02:00Z",
    "closed_at": null,
    "conversation_count": 0,
    "url": "https://app.inmywords.chat/cases/1207"
  }
}

Start a conversation in a case

The API never starts a conversation without a person. What you get back is an address, and a signed-in member of your organisation opens it to start the conversation.

Send an Idempotency-Key header, as you do when opening a case. The answer is 201.

curl -X POST https://app.inmywords.chat/api/integrations/v1/cases/1207/conversations \
  -H "Authorization: Bearer imw_3f9c..." \
  -H "Idempotency-Key: 9d2f-start-1207-1"

{"data": {"url": "https://app.inmywords.chat/cases/1207/conversations/new"}}

Translations made in the conversation are billed to your organisation, as they are when a conversation is started from the user interface. When the conversation ends, the conversation.ended webhook event is sent.

When something goes wrong

Every error comes back as {"error": {"code": "...", "message": "..."}} with the HTTP status.

{"error": {"code": "validation_failed", "message": "title is required."}}