Documents

This page is for the developer who sends letters, forms and other text from your system to be translated.

It covers sending a file or a piece of text into a case, and reading the document and its translation back.

Calls go to https://app.inmywords.chat/api/integrations/v1/, and every request carries Authorization: Bearer imw_<64 hex characters>, the key of a connection your organisation has made. To send a document the connection needs documents:write; to read it and its translation, it needs documents:read.

A document is sent into a case and translated into one language. When it has been translated, the document.translated webhook event is sent.

1. Document translation must be on as well. It has to be switched on for your organisation, as well as integrations. When it is off, sending a document answers 403 module_off. A document already sent can still be read.
2. You read back only what you sent. Only documents sent through the API can be read through it. A document sent from the InMyWords screens answers 404.
3. You see only your own organisation's documents. A document of another organisation answers 404, the same as one that does not exist.
4. Translation is billed as usual. It is billed to your organisation, as it is when a document is sent from the screens.

Ids are strings of digits, such as "57". Times are ISO 8601 in UTC. Field names are snake_case.

Endpoints

What a document holds

A document starts as queued, which means it has not been read yet. It moves to translating once it has been read and is being translated.

waiting means the document is over your organisation's word limit. A person must choose its sections in InMyWords before it is translated.

failed is final. To try again, send the document again.

How the translation comes back

Blocks come in the document's own order. A table arrives as its cells, one block each, row by row.

Send a document

Send a multipart form, or a JSON body for text, with these fields.

1. A file or text, not both. Text is translated just as a document is: in the background, read back with GET /documents/{id}, and announced by the document.translated webhook. Its file_name is pasted.txt.
2. Size limits. A file can be up to 20 MB, and text up to 400,000 characters. Send longer text as a .txt file.
3. File types. Plain text (.txt), Markdown (.md), Word (.docx) and OpenDocument (.odt). PDF, JPEG, PNG and HEIC as well, where reading by the model is switched on for your organisation.
4. Retrying safely. Send an Idempotency-Key header, up to 255 characters. The same key with the same body within 24 hours answers the first result. The same key with a different body answers 422 idempotency_key_reused.

The answer is 202, with the document in status queued.

curl -X POST https://app.inmywords.chat/api/integrations/v1/documents \
  -H "Authorization: Bearer imw_3f9c..." \
  -H "Idempotency-Key: 0c7e-doc-1207-notice" \
  -F case_id=1207 \
  -F target_language=so \
  -F [email protected]

curl -X POST https://app.inmywords.chat/api/integrations/v1/documents \
  -H "Authorization: Bearer imw_3f9c..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0c7e-text-1207-1" \
  -d '{"case_id": "1207", "target_language": "so", "text": "Your appointment is on Tuesday at 10am."}'

{
  "data": {
    "id": "1054",
    "case_id": "1207",
    "file_name": "notice.pdf",
    "status": "queued",
    "source_language": null,
    "target_language": "so",
    "created_at": "2026-10-02T10:05:12Z",
    "translated_at": null,
    "blocks": null
  }
}

Read a document

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

{
  "data": {
    "id": "1054",
    "case_id": "1207",
    "file_name": "notice.pdf",
    "status": "translated",
    "source_language": "en",
    "target_language": "so",
    "created_at": "2026-10-02T10:05:12Z",
    "translated_at": "2026-10-02T10:06:40Z",
    "blocks": [
      {"type": "heading", "text": "Ogeysiis", "level": 1},
      {"type": "paragraph", "text": "Waxaa lagaa codsanayaa inaad ka guurto hantida."},
      {"type": "list_item", "text": "Taariikhda: 28 Oktoobar 2026", "level": 1},
      {"type": "table_cell", "text": "Kirada"},
      {"type": "table_cell", "text": "GBP 650"}
    ]
  }
}

When something goes wrong

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

{"error": {"code": "validation_failed", "message": "target_language is not a language this organisation translates into."}}