1.  [Documentation](/en/docs)
2.  [API](/en/docs/api/quickstart)
3.  API reference

# API reference

Every endpoint of the Public API, with its request and an example response.

Templates[GETList templates](#list-templates)

Runs[POSTCreate a run](#create-run)[GETRetrieve a run](#get-run)[GETDownload the output](#get-run-output)[GETDownload from a link](#download-run-output)

Webhook events[POSTA Run succeeded](#webhook-run-succeeded)[POSTA Run failed](#webhook-run-failed)[POSTA test event](#webhook-test)

Reference tables[GETList reference tables](#list-reference-tables)[PUTReplace a reference table's rows](#replace-reference-table-rows)

Base URL

`https://doctransform.xyz/api/v1`

Authentication

`Authorization: Bearer` · [How to get an API key](/en/docs/api/authentication)

Versioning

One version, in the base URL. Anything we retire keeps working for at least 12 months after we mark it with the Deprecation and Sunset headers.

Responses

Ignore any field you don't recognize: we add fields without warning.

OpenAPI 3.1

Download JSON · [doctransform.xyz/api/v1/openapi.json](https://doctransform.xyz/api/v1/openapi.json)

## Templates

### [List templates](#list-templates)

GET`/templates`

Returns your account's templates. Use a template's id to create a run.

Scope `templates:read`

GET/templatesCopy

curlPythonNode.js

    curl "https://doctransform.xyz/api/v1/templates" \
      -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"

Response200Copy

    {
      "data": [
        {
          "description": "Cleans the billing export and keeps the paid invoices.",
          "id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
          "name": "Monthly invoices",
          "output_format": "csv"
        }
      ]
    }

Returns [A list of Template objects](#template-object)

Errors (8)

*   401[API\_KEY\_MISSING](/en/docs/api/errors-and-limits#API_KEY_MISSING)
*   401[API\_KEY\_INVALID](/en/docs/api/errors-and-limits#API_KEY_INVALID)
*   403[INSUFFICIENT\_SCOPE](/en/docs/api/errors-and-limits#INSUFFICIENT_SCOPE)
*   403[JOIN\_FILES\_NOT\_AVAILABLE](/en/docs/api/errors-and-limits#JOIN_FILES_NOT_AVAILABLE)
*   403[JOIN\_FILES\_LIMIT\_EXCEEDED](/en/docs/api/errors-and-limits#JOIN_FILES_LIMIT_EXCEEDED)
*   403[NO\_SUBSCRIPTION](/en/docs/api/errors-and-limits#NO_SUBSCRIPTION)
*   429[CONCURRENCY\_LIMIT\_REACHED](/en/docs/api/errors-and-limits#CONCURRENCY_LIMIT_REACHED)
*   429[RATE\_LIMITED](/en/docs/api/errors-and-limits#RATE_LIMITED)

[See every error code and the limits](/en/docs/api/errors-and-limits)

### [The Template object](#template-object)

A saved Template a Run can apply.

ExampleCopy

    {
      "description": "Cleans the billing export and keeps the paid invoices.",
      "id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
      "name": "Monthly invoices",
      "output_format": "csv"
    }

Attributes

*   `description`stringoptionalnullable
    
    What the Template does, when its owner wrote one.
    
*   `id`stringrequired
    
    The Template's id; send it to create a Run.
    
*   `name`stringoptionalnullable
    
    The name the Template was saved under.
    
*   `output_format`stringoptionalnullable
    
    The file format a Run of this Template writes. A Template's Summary sheet is written only when this is xlsx.
    

## Runs

### [Create a run](#create-run)

POST`/templates/{template_id}/runs`

Runs a template on one file, plus one file for each Join File the template reads, matched by header, not by order. Answers 201 with the finished run if it completes within about 30 seconds, otherwise 202 while it keeps running. Send an Idempotency-Key and a retry is never charged twice. A run that finishes uses one export from your monthly allowance; a refused, failed or replayed run uses none.

Scope `runs:write`

POST/templates/{template\_id}/runsCopy

curlPythonNode.js

    curl -X POST "https://doctransform.xyz/api/v1/templates/{template_id}/runs" \
      -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
      -H "Idempotency-Key: <Idempotency-Key>" \
      -F "file=@/path/to/your/file.csv"

Response201Copy

    {
      "change_report": {
        "columns_in": 3,
        "columns_out": 3,
        "lines": [
          "Step 1 · Mark as empty: Emptied 212 rows in Phone."
        ],
        "previous": null,
        "previous_counted_at": "2026-03-02T09:15:00Z",
        "rows_in": 4,
        "rows_out": 4,
        "steps": [
          {
            "columns": [
              "Phone"
            ],
            "columns_added": [
              "Phone"
            ],
            "columns_removed": [
              "Phone"
            ],
            "counted": true,
            "kind": "mark_empty",
            "made_columns": null,
            "new_or_changed": false,
            "number": 1,
            "previous": {
              "rows_after": 1204,
              "rows_before": 1204,
              "rows_changed": [
                {
                  "column": "Phone",
                  "rows": 200
                }
              ],
              "unread_rows": null
            },
            "rows_after": 1204,
            "rows_before": 1204,
            "rows_changed": [
              {
                "column": "Phone",
                "rows": 212
              }
            ],
            "step_key": "3f2a9c01b7d4e856-1",
            "swings": [
              {
                "column": "Phone",
                "count": 40,
                "count_name": "rows_changed",
                "previous": 12
              }
            ],
            "title": "Mark as empty",
            "unread_columns": [
              "Phone"
            ],
            "unread_rows": null
          }
        ]
      },
      "completed_at": "2026-10-07T14:02:19Z",
      "created_at": "2026-10-07T14:02:11Z",
      "destination_check": {
        "destination_id": "hubspot_contacts",
        "passed": false,
        "reasons": [
          {
            "count": 12,
            "field": "Email",
            "message": "The email address is incomplete.",
            "outcome": "rejected",
            "rule_id": "email_format"
          }
        ],
        "rows_checked": 1204,
        "rows_failing": 12
      },
      "error": null,
      "expires_at": "2026-10-07T14:32:19Z",
      "id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
      "output": {
        "download_url": "/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/output",
        "mime_type": "text/csv",
        "name": "invoices.csv",
        "size_bytes": 48213,
        "split_parts": 12
      },
      "reference_tables": [
        {
          "id": "7d1c9a52-3b0e-4c57-8f21-6a94e0b5d3c8",
          "name": "Product catalog",
          "rows": 1204,
          "updated_at": "2026-10-07T13:58:40+00:00"
        }
      ],
      "rows_written": 1204,
      "status": "succeeded",
      "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
      "truncated": false,
      "warnings": [
        {
          "code": "APPEND_LOCALE_DISAGREEMENT",
          "column": "Invoice total",
          "count": 12,
          "expected_source_file": "January",
          "message": "12 values in this part read differently from the first file.",
          "part": 2,
          "step": 2,
          "output_rows": 500,
          "summary_rows": 480,
          "file_column": "invoice_total",
          "how": "normalised",
          "sample": [
            [
              "SKU-1042"
            ]
          ],
          "rows": 12,
          "values": 3,
          "checked": 4000,
          "left": 250,
          "count_name": "rows_changed",
          "previous": 12
        }
      ]
    }

Path parameters

*   `template_id`stringrequired
    
    The id of the Template to run.
    

Headers

*   `Idempotency-Key`stringoptional
    
    Replays the Run already started or finished for this key rather than starting a second one; a different request with the same key answers `409 IDEMPOTENCY_KEY_REUSED`.
    

Body (multipart/form-data)

*   `column_mapping`stringoptional
    
    For this Run only, never saved: a JSON object `{file column: Template column}` that settles a column the file renamed. Send it after a `422 TEMPLATE_COLUMNS_MISSING` names the candidates. Ignored for a Template with an Append Step.
    
*   `delimiter`stringoptional
    
    The one character that separates the columns of a delimited text file. The delimiter is detected when omitted.
    
*   `file`filerequired
    
    The file to run: .csv, .txt, .xls, .xlsx, .yaml, .yml, .json, within your plan's size and row limits. Send the part once, or repeat it to append several files, in order, when the Template has an Append Step. When the Template has a Join Step on a file sent with each Run, send one more part for each Join File: parts are matched to the main file and to each Join File by header fit, not by order. A Run has no running Dataset: every file comes in the request.
    
*   `header_row`integeroptional
    
    Which row holds the column names, 0-based. The header is detected when omitted.
    

Returns [A Run object](#run-object)

Errors (33)

*   400[MALFORMED\_FILE](/en/docs/api/errors-and-limits#MALFORMED_FILE)
*   401[API\_KEY\_MISSING](/en/docs/api/errors-and-limits#API_KEY_MISSING)
*   401[API\_KEY\_INVALID](/en/docs/api/errors-and-limits#API_KEY_INVALID)
*   402[EXPORT\_LIMIT\_REACHED](/en/docs/api/errors-and-limits#EXPORT_LIMIT_REACHED)
*   403[INSUFFICIENT\_SCOPE](/en/docs/api/errors-and-limits#INSUFFICIENT_SCOPE)
*   403[JOIN\_FILES\_NOT\_AVAILABLE](/en/docs/api/errors-and-limits#JOIN_FILES_NOT_AVAILABLE)
*   403[JOIN\_FILES\_LIMIT\_EXCEEDED](/en/docs/api/errors-and-limits#JOIN_FILES_LIMIT_EXCEEDED)
*   403[NO\_SUBSCRIPTION](/en/docs/api/errors-and-limits#NO_SUBSCRIPTION)
*   404[TEMPLATE\_NOT\_FOUND](/en/docs/api/errors-and-limits#TEMPLATE_NOT_FOUND)
*   404[RUN\_NOT\_FOUND](/en/docs/api/errors-and-limits#RUN_NOT_FOUND)
*   404[REFERENCE\_TABLE\_ID\_NOT\_FOUND](/en/docs/api/errors-and-limits#REFERENCE_TABLE_ID_NOT_FOUND)
*   409[IDEMPOTENCY\_KEY\_REUSED](/en/docs/api/errors-and-limits#IDEMPOTENCY_KEY_REUSED)
*   409[REFERENCE\_TABLE\_COLUMN\_IN\_USE](/en/docs/api/errors-and-limits#REFERENCE_TABLE_COLUMN_IN_USE)
*   413[FILE\_COUNT\_LIMIT\_EXCEEDED](/en/docs/api/errors-and-limits#FILE_COUNT_LIMIT_EXCEEDED)
*   413[FILE\_TOO\_LARGE](/en/docs/api/errors-and-limits#FILE_TOO_LARGE)
*   413[ROW\_LIMIT\_EXCEEDED](/en/docs/api/errors-and-limits#ROW_LIMIT_EXCEEDED)
*   415[UNSUPPORTED\_FILE\_TYPE](/en/docs/api/errors-and-limits#UNSUPPORTED_FILE_TYPE)
*   422[INVALID\_PARSE\_PARAMS](/en/docs/api/errors-and-limits#INVALID_PARSE_PARAMS)
*   422[INVALID\_IDEMPOTENCY\_KEY](/en/docs/api/errors-and-limits#INVALID_IDEMPOTENCY_KEY)
*   422[INVALID\_COLUMN\_MAPPING](/en/docs/api/errors-and-limits#INVALID_COLUMN_MAPPING)
*   422[TEMPLATE\_OP\_REFUSED](/en/docs/api/errors-and-limits#TEMPLATE_OP_REFUSED)
*   422[REFERENCE\_TABLE\_NOT\_FOUND](/en/docs/api/errors-and-limits#REFERENCE_TABLE_NOT_FOUND)
*   422[REFERENCE\_TABLE\_COLUMN\_MISSING](/en/docs/api/errors-and-limits#REFERENCE_TABLE_COLUMN_MISSING)
*   422[REFERENCE\_TABLE\_REFUSED](/en/docs/api/errors-and-limits#REFERENCE_TABLE_REFUSED)
*   422[TEMPLATE\_COLUMNS\_MISSING](/en/docs/api/errors-and-limits#TEMPLATE_COLUMNS_MISSING)
*   422[TEMPLATE\_OUTPUT\_AS\_SOURCE](/en/docs/api/errors-and-limits#TEMPLATE_OUTPUT_AS_SOURCE)
*   422[TEMPLATE\_TAKES\_ONE\_FILE](/en/docs/api/errors-and-limits#TEMPLATE_TAKES_ONE_FILE)
*   422[JOIN\_FILE\_MISSING](/en/docs/api/errors-and-limits#JOIN_FILE_MISSING)
*   422[JOIN\_FILE\_COLUMNS\_MISSING](/en/docs/api/errors-and-limits#JOIN_FILE_COLUMNS_MISSING)
*   422[RUN\_FILES\_AMBIGUOUS](/en/docs/api/errors-and-limits#RUN_FILES_AMBIGUOUS)
*   429[CONCURRENCY\_LIMIT\_REACHED](/en/docs/api/errors-and-limits#CONCURRENCY_LIMIT_REACHED)
*   429[RATE\_LIMITED](/en/docs/api/errors-and-limits#RATE_LIMITED)
*   503[SERVER\_BUSY](/en/docs/api/errors-and-limits#SERVER_BUSY)

[See every error code and the limits](/en/docs/api/errors-and-limits)

### [Retrieve a run](#get-run)

GET`/runs/{run_id}`

Returns the status of a run. Poll until it is succeeded or failed.

Scope `runs:read`

GET/runs/{run\_id}Copy

curlPythonNode.js

    curl "https://doctransform.xyz/api/v1/runs/{run_id}" \
      -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"

Response200Copy

    {
      "change_report": {
        "columns_in": 3,
        "columns_out": 3,
        "lines": [
          "Step 1 · Mark as empty: Emptied 212 rows in Phone."
        ],
        "previous": null,
        "previous_counted_at": "2026-03-02T09:15:00Z",
        "rows_in": 4,
        "rows_out": 4,
        "steps": [
          {
            "columns": [
              "Phone"
            ],
            "columns_added": [
              "Phone"
            ],
            "columns_removed": [
              "Phone"
            ],
            "counted": true,
            "kind": "mark_empty",
            "made_columns": null,
            "new_or_changed": false,
            "number": 1,
            "previous": {
              "rows_after": 1204,
              "rows_before": 1204,
              "rows_changed": [
                {
                  "column": "Phone",
                  "rows": 200
                }
              ],
              "unread_rows": null
            },
            "rows_after": 1204,
            "rows_before": 1204,
            "rows_changed": [
              {
                "column": "Phone",
                "rows": 212
              }
            ],
            "step_key": "3f2a9c01b7d4e856-1",
            "swings": [
              {
                "column": "Phone",
                "count": 40,
                "count_name": "rows_changed",
                "previous": 12
              }
            ],
            "title": "Mark as empty",
            "unread_columns": [
              "Phone"
            ],
            "unread_rows": null
          }
        ]
      },
      "completed_at": "2026-10-07T14:02:19Z",
      "created_at": "2026-10-07T14:02:11Z",
      "destination_check": {
        "destination_id": "hubspot_contacts",
        "passed": false,
        "reasons": [
          {
            "count": 12,
            "field": "Email",
            "message": "The email address is incomplete.",
            "outcome": "rejected",
            "rule_id": "email_format"
          }
        ],
        "rows_checked": 1204,
        "rows_failing": 12
      },
      "error": null,
      "expires_at": "2026-10-07T14:32:19Z",
      "id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
      "output": {
        "download_url": "/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/output",
        "mime_type": "text/csv",
        "name": "invoices.csv",
        "size_bytes": 48213,
        "split_parts": 12
      },
      "reference_tables": [
        {
          "id": "7d1c9a52-3b0e-4c57-8f21-6a94e0b5d3c8",
          "name": "Product catalog",
          "rows": 1204,
          "updated_at": "2026-10-07T13:58:40+00:00"
        }
      ],
      "rows_written": 1204,
      "status": "succeeded",
      "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
      "truncated": false,
      "warnings": [
        {
          "code": "APPEND_LOCALE_DISAGREEMENT",
          "column": "Invoice total",
          "count": 12,
          "expected_source_file": "January",
          "message": "12 values in this part read differently from the first file.",
          "part": 2,
          "step": 2,
          "output_rows": 500,
          "summary_rows": 480,
          "file_column": "invoice_total",
          "how": "normalised",
          "sample": [
            [
              "SKU-1042"
            ]
          ],
          "rows": 12,
          "values": 3,
          "checked": 4000,
          "left": 250,
          "count_name": "rows_changed",
          "previous": 12
        }
      ]
    }

Path parameters

*   `run_id`stringrequired
    
    The id of the Run, as returned when it was created.
    

Returns [A Run object](#run-object)

Errors (11)

*   401[API\_KEY\_MISSING](/en/docs/api/errors-and-limits#API_KEY_MISSING)
*   401[API\_KEY\_INVALID](/en/docs/api/errors-and-limits#API_KEY_INVALID)
*   403[INSUFFICIENT\_SCOPE](/en/docs/api/errors-and-limits#INSUFFICIENT_SCOPE)
*   403[JOIN\_FILES\_NOT\_AVAILABLE](/en/docs/api/errors-and-limits#JOIN_FILES_NOT_AVAILABLE)
*   403[JOIN\_FILES\_LIMIT\_EXCEEDED](/en/docs/api/errors-and-limits#JOIN_FILES_LIMIT_EXCEEDED)
*   403[NO\_SUBSCRIPTION](/en/docs/api/errors-and-limits#NO_SUBSCRIPTION)
*   404[TEMPLATE\_NOT\_FOUND](/en/docs/api/errors-and-limits#TEMPLATE_NOT_FOUND)
*   404[RUN\_NOT\_FOUND](/en/docs/api/errors-and-limits#RUN_NOT_FOUND)
*   404[REFERENCE\_TABLE\_ID\_NOT\_FOUND](/en/docs/api/errors-and-limits#REFERENCE_TABLE_ID_NOT_FOUND)
*   429[CONCURRENCY\_LIMIT\_REACHED](/en/docs/api/errors-and-limits#CONCURRENCY_LIMIT_REACHED)
*   429[RATE\_LIMITED](/en/docs/api/errors-and-limits#RATE_LIMITED)

[See every error code and the limits](/en/docs/api/errors-and-limits)

### [Download the output](#get-run-output)

GET`/runs/{run_id}/output`

Downloads the file a finished run produced.

Scope `runs:read`

GET/runs/{run\_id}/outputCopy

curlPythonNode.js

    curl -o output "https://doctransform.xyz/api/v1/runs/{run_id}/output" \
      -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"

Response200

Binary file. The Content-Type follows the Template's output format.

Path parameters

*   `run_id`stringrequired
    
    The id of the Run, as returned when it was created.
    

Returns The output file

Errors (11)

*   401[API\_KEY\_MISSING](/en/docs/api/errors-and-limits#API_KEY_MISSING)
*   401[API\_KEY\_INVALID](/en/docs/api/errors-and-limits#API_KEY_INVALID)
*   403[INSUFFICIENT\_SCOPE](/en/docs/api/errors-and-limits#INSUFFICIENT_SCOPE)
*   403[JOIN\_FILES\_NOT\_AVAILABLE](/en/docs/api/errors-and-limits#JOIN_FILES_NOT_AVAILABLE)
*   403[JOIN\_FILES\_LIMIT\_EXCEEDED](/en/docs/api/errors-and-limits#JOIN_FILES_LIMIT_EXCEEDED)
*   403[NO\_SUBSCRIPTION](/en/docs/api/errors-and-limits#NO_SUBSCRIPTION)
*   404[TEMPLATE\_NOT\_FOUND](/en/docs/api/errors-and-limits#TEMPLATE_NOT_FOUND)
*   404[RUN\_NOT\_FOUND](/en/docs/api/errors-and-limits#RUN_NOT_FOUND)
*   404[REFERENCE\_TABLE\_ID\_NOT\_FOUND](/en/docs/api/errors-and-limits#REFERENCE_TABLE_ID_NOT_FOUND)
*   429[CONCURRENCY\_LIMIT\_REACHED](/en/docs/api/errors-and-limits#CONCURRENCY_LIMIT_REACHED)
*   429[RATE\_LIMITED](/en/docs/api/errors-and-limits#RATE_LIMITED)

[See every error code and the limits](/en/docs/api/errors-and-limits)

### [Download from a link](#download-run-output)

GET`/runs/{run_id}/download`

Downloads a finished run's file from a pre-signed link. No API key needed: the link is public by design and expires, so share it only with who should have the file.

GET/runs/{run\_id}/downloadCopy

curlPythonNode.js

    curl -o output "https://doctransform.xyz/api/v1/runs/{run_id}/download"

Response200

Binary file. The Content-Type follows the Template's output format.

Path parameters

*   `run_id`stringrequired
    
    The id of the Run, as returned when it was created.
    

Returns The output file

Errors (7)

*   404[TEMPLATE\_NOT\_FOUND](/en/docs/api/errors-and-limits#TEMPLATE_NOT_FOUND)
*   404[RUN\_NOT\_FOUND](/en/docs/api/errors-and-limits#RUN_NOT_FOUND)
*   404[REFERENCE\_TABLE\_ID\_NOT\_FOUND](/en/docs/api/errors-and-limits#REFERENCE_TABLE_ID_NOT_FOUND)
*   410[DOWNLOAD\_LINK\_EXPIRED](/en/docs/api/errors-and-limits#DOWNLOAD_LINK_EXPIRED)
*   410[CHECK\_NOT\_FOUND](/en/docs/api/errors-and-limits#CHECK_NOT_FOUND)
*   429[CONCURRENCY\_LIMIT\_REACHED](/en/docs/api/errors-and-limits#CONCURRENCY_LIMIT_REACHED)
*   429[RATE\_LIMITED](/en/docs/api/errors-and-limits#RATE_LIMITED)

[See every error code and the limits](/en/docs/api/errors-and-limits)

### [The Run object](#run-object)

A Run: its status, timestamps and, once it has one, its output.

ExampleCopy

    {
      "change_report": {
        "columns_in": 3,
        "columns_out": 3,
        "lines": [
          "Step 1 · Mark as empty: Emptied 212 rows in Phone."
        ],
        "previous": null,
        "previous_counted_at": "2026-03-02T09:15:00Z",
        "rows_in": 4,
        "rows_out": 4,
        "steps": [
          {
            "columns": [
              "Phone"
            ],
            "columns_added": [
              "Phone"
            ],
            "columns_removed": [
              "Phone"
            ],
            "counted": true,
            "kind": "mark_empty",
            "made_columns": null,
            "new_or_changed": false,
            "number": 1,
            "previous": {
              "rows_after": 1204,
              "rows_before": 1204,
              "rows_changed": [
                {
                  "column": "Phone",
                  "rows": 200
                }
              ],
              "unread_rows": null
            },
            "rows_after": 1204,
            "rows_before": 1204,
            "rows_changed": [
              {
                "column": "Phone",
                "rows": 212
              }
            ],
            "step_key": "3f2a9c01b7d4e856-1",
            "swings": [
              {
                "column": "Phone",
                "count": 40,
                "count_name": "rows_changed",
                "previous": 12
              }
            ],
            "title": "Mark as empty",
            "unread_columns": [
              "Phone"
            ],
            "unread_rows": null
          }
        ]
      },
      "completed_at": "2026-10-07T14:02:19Z",
      "created_at": "2026-10-07T14:02:11Z",
      "destination_check": {
        "destination_id": "hubspot_contacts",
        "passed": false,
        "reasons": [
          {
            "count": 12,
            "field": "Email",
            "message": "The email address is incomplete.",
            "outcome": "rejected",
            "rule_id": "email_format"
          }
        ],
        "rows_checked": 1204,
        "rows_failing": 12
      },
      "error": null,
      "expires_at": "2026-10-07T14:32:19Z",
      "id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
      "output": {
        "download_url": "/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/output",
        "mime_type": "text/csv",
        "name": "invoices.csv",
        "size_bytes": 48213,
        "split_parts": 12
      },
      "reference_tables": [
        {
          "id": "7d1c9a52-3b0e-4c57-8f21-6a94e0b5d3c8",
          "name": "Product catalog",
          "rows": 1204,
          "updated_at": "2026-10-07T13:58:40+00:00"
        }
      ],
      "rows_written": 1204,
      "status": "succeeded",
      "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
      "truncated": false,
      "warnings": [
        {
          "code": "APPEND_LOCALE_DISAGREEMENT",
          "column": "Invoice total",
          "count": 12,
          "expected_source_file": "January",
          "message": "12 values in this part read differently from the first file.",
          "part": 2,
          "step": 2,
          "output_rows": 500,
          "summary_rows": 480,
          "file_column": "invoice_total",
          "how": "normalised",
          "sample": [
            [
              "SKU-1042"
            ]
          ],
          "rows": 12,
          "values": 3,
          "checked": 4000,
          "left": 250,
          "count_name": "rows_changed",
          "previous": 12
        }
      ]
    }

Attributes

*   `change_report`objectoptionalnullable
    
    What each step did to the file, in counts and English lines only: no cell and no value read from a row. Null until the Run succeeds.
    
    \+ Show attributes (8)
    
*   `completed_at`stringdate-timeoptionalnullable
    
    When the Run finished; null while it is running.
    
*   `created_at`stringdate-timerequired
    
    When the Run was accepted.
    
*   `destination_check`objectoptionalnullable
    
    Whether the output file passes the system the Template uploads to, counts only. Null when the Template names no system and until the Run succeeds.
    
    \+ Show attributes (5)
    
*   `error`objectoptionalnullable
    
    Why the Run failed; null unless it did.
    
    \+ Show attributes (6)
    
*   `expires_at`stringdate-timeoptionalnullable
    
    30 minutes after the Run finished, or 3 days when a Webhook receives it; null while it is running.
    
*   `id`stringrequired
    
    The Run's id, `run_` followed by 32 hex digits.
    
*   `output`objectoptionalnullable
    
    The output file; null until the Run succeeds.
    
    \+ Show attributes (5)
    
*   `reference_tables`arrayoptional
    
    The Reference Tables the Run's Join Steps read, as they were when the Run started: id, name, last change and row count. No cell.
    
    \+ Show attributes (4)
    
*   `rows_written`integeroptionalnullable
    
    Rows in the output file; null until the Run succeeds.
    
*   `status`running | succeeded | failedrequired
    
    Where the Run is now.
    
*   `template_id`stringrequired
    
    The Template the Run applied.
    
*   `truncated`booleanoptional
    
    True when the output was cut at the plan's row limit.
    
*   `warnings`arrayoptional
    
    Warnings the Run succeeded despite; empty when there are none.
    
    \+ Show attributes (18)
    

## Webhook events

What your receiver gets when a Run finishes. DocTransform sends each event as a POST with a JSON body to the URL of a Webhook you added in your account. Every event has the same shape, described at the end of this group.

[Webhooks guide](/en/docs/api/webhooks)

### [A Run succeeded](#webhook-run-succeeded)

POST`run.succeeded`

Sent when a Run finishes and its output file is ready. The body carries a download link that needs no API key until it expires.

Body sent to your URLCopy

    {
      "type": "run.succeeded",
      "timestamp": "2026-09-27T10:15:00Z",
      "data": {
        "run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
        "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
        "status": "succeeded",
        "download_url": "https://doctransform.xyz/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/download?expires=1790763300&signature=0000000000000000000000000000000000000000000000000000000000000000",
        "expires_at": "2026-09-30T10:15:00Z",
        "error": null
      }
    }

Body [An event body](#event-envelope-object)

### [A Run failed](#webhook-run-failed)

POST`run.failed`

Sent when a Run ends without an output file. The body says why, in a fixed code and one plain sentence.

Body sent to your URLCopy

    {
      "type": "run.failed",
      "timestamp": "2026-09-27T10:15:00Z",
      "data": {
        "run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
        "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
        "status": "failed",
        "download_url": null,
        "expires_at": null,
        "error": {
          "code": "PIPELINE_FAILED",
          "message": "The pipeline failed while running the Template."
        }
      }
    }

Body [An event body](#event-envelope-object)

### [A test event](#webhook-test)

POST`webhook.test`

Sent only when you press Send test event in your account, to check your receiver. It describes a made-up Run and its link does not work.

Body sent to your URLCopy

    {
      "type": "webhook.test",
      "timestamp": "2026-09-27T10:15:00+00:00",
      "data": {
        "run_id": "run_test",
        "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
        "status": "succeeded",
        "download_url": "https://doctransform.xyz/api/v1/runs/run_test/download?expires=1790590500&signature=0000000000000000000000000000000000000000000000000000000000000000",
        "expires_at": "2026-09-28T10:15:00+00:00",
        "error": null
      }
    }

Body [An event body](#event-envelope-object)

### [The event body](#event-envelope-object)

What every Webhook event carries: what happened, when, and the details of the Run. Never a row, a cell or a file name.

ExampleCopy

    {
      "type": "run.succeeded",
      "timestamp": "2026-09-27T10:15:00Z",
      "data": {
        "run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
        "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
        "status": "succeeded",
        "download_url": "https://doctransform.xyz/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/download?expires=1790763300&signature=0000000000000000000000000000000000000000000000000000000000000000",
        "expires_at": "2026-09-30T10:15:00Z",
        "error": null
      }
    }

Attributes

*   `data`objectrequired
    
    The details of the event. It names the Run and the Template by id and never carries a row, a cell, a column name or a file name.
    
    \+ Show attributes (6)
    
*   `timestamp`stringdate-timerequired
    
    When the event was created, as a UTC date and time.
    
*   `type`stringrequired
    
    What happened: `run.succeeded`, `run.failed`, or `webhook.test` for the test event you send from your account.
    

## Reference tables

### [List reference tables](#list-reference-tables)

GET`/reference-tables`

Returns your account's reference tables: name, columns, row count, last change and the templates that use each. Never a row.

Scope `reference_tables:read`

GET/reference-tablesCopy

curlPythonNode.js

    curl "https://doctransform.xyz/api/v1/reference-tables" \
      -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"

Response200Copy

    {
      "data": [
        {
          "columns": [
            "SKU",
            "Category",
            "Brand"
          ],
          "id": "rt_8d1f0c2a4b6e4a9fb3c7e5d2a1f09b64",
          "name": "Catalog",
          "rows": 1840,
          "updated_at": "2026-10-06T22:15:40Z",
          "used_by": [
            {
              "id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
              "name": "Monthly invoices"
            }
          ]
        }
      ]
    }

Returns [landing.docs.apiReference.returns.reference-tableList](#reference-table-object)

Errors (8)

*   401[API\_KEY\_MISSING](/en/docs/api/errors-and-limits#API_KEY_MISSING)
*   401[API\_KEY\_INVALID](/en/docs/api/errors-and-limits#API_KEY_INVALID)
*   403[INSUFFICIENT\_SCOPE](/en/docs/api/errors-and-limits#INSUFFICIENT_SCOPE)
*   403[JOIN\_FILES\_NOT\_AVAILABLE](/en/docs/api/errors-and-limits#JOIN_FILES_NOT_AVAILABLE)
*   403[JOIN\_FILES\_LIMIT\_EXCEEDED](/en/docs/api/errors-and-limits#JOIN_FILES_LIMIT_EXCEEDED)
*   403[NO\_SUBSCRIPTION](/en/docs/api/errors-and-limits#NO_SUBSCRIPTION)
*   429[CONCURRENCY\_LIMIT\_REACHED](/en/docs/api/errors-and-limits#CONCURRENCY_LIMIT_REACHED)
*   429[RATE\_LIMITED](/en/docs/api/errors-and-limits#RATE_LIMITED)

[See every error code and the limits](/en/docs/api/errors-and-limits)

### [Replace a reference table's rows](#replace-reference-table-rows)

PUT`/reference-tables/{table_id}/rows`

Swaps every row of one table for the rows of the file you send, all or nothing. A file that drops a column a template reads answers 409 REFERENCE\_TABLE\_COLUMN\_IN\_USE and replaces nothing.

Scope `reference_tables:write`

PUT/reference-tables/{table\_id}/rowsCopy

curlPythonNode.js

    curl -X PUT "https://doctransform.xyz/api/v1/reference-tables/{table_id}/rows" \
      -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
      -F "file=@/path/to/your/file.csv"

Response200Copy

    {
      "columns": [
        "SKU",
        "Category",
        "Brand"
      ],
      "id": "rt_8d1f0c2a4b6e4a9fb3c7e5d2a1f09b64",
      "name": "Catalog",
      "rows": 1840,
      "updated_at": "2026-10-06T22:15:40Z",
      "warnings": [
        {
          "code": "JOIN_REPEATED_KEYS",
          "columns": [
            "SKU"
          ],
          "count": 3
        }
      ]
    }

Path parameters

*   `table_id`stringrequired
    
    The id of the Reference Table, as the list returns it.
    

Body (multipart/form-data)

*   `file`filerequired
    
    The table's new rows, column names in the first row: .csv, .txt, .xlsx, .xls, within the same size, row and column caps as saving a table.
    

Errors (30)

*   401[API\_KEY\_MISSING](/en/docs/api/errors-and-limits#API_KEY_MISSING)
*   401[API\_KEY\_INVALID](/en/docs/api/errors-and-limits#API_KEY_INVALID)
*   403[INSUFFICIENT\_SCOPE](/en/docs/api/errors-and-limits#INSUFFICIENT_SCOPE)
*   403[JOIN\_FILES\_NOT\_AVAILABLE](/en/docs/api/errors-and-limits#JOIN_FILES_NOT_AVAILABLE)
*   403[JOIN\_FILES\_LIMIT\_EXCEEDED](/en/docs/api/errors-and-limits#JOIN_FILES_LIMIT_EXCEEDED)
*   403[NO\_SUBSCRIPTION](/en/docs/api/errors-and-limits#NO_SUBSCRIPTION)
*   404[TEMPLATE\_NOT\_FOUND](/en/docs/api/errors-and-limits#TEMPLATE_NOT_FOUND)
*   404[RUN\_NOT\_FOUND](/en/docs/api/errors-and-limits#RUN_NOT_FOUND)
*   404[REFERENCE\_TABLE\_ID\_NOT\_FOUND](/en/docs/api/errors-and-limits#REFERENCE_TABLE_ID_NOT_FOUND)
*   409[IDEMPOTENCY\_KEY\_REUSED](/en/docs/api/errors-and-limits#IDEMPOTENCY_KEY_REUSED)
*   409[REFERENCE\_TABLE\_COLUMN\_IN\_USE](/en/docs/api/errors-and-limits#REFERENCE_TABLE_COLUMN_IN_USE)
*   413[FILE\_COUNT\_LIMIT\_EXCEEDED](/en/docs/api/errors-and-limits#FILE_COUNT_LIMIT_EXCEEDED)
*   413[FILE\_TOO\_LARGE](/en/docs/api/errors-and-limits#FILE_TOO_LARGE)
*   413[ROW\_LIMIT\_EXCEEDED](/en/docs/api/errors-and-limits#ROW_LIMIT_EXCEEDED)
*   415[UNSUPPORTED\_FILE\_TYPE](/en/docs/api/errors-and-limits#UNSUPPORTED_FILE_TYPE)
*   422[INVALID\_PARSE\_PARAMS](/en/docs/api/errors-and-limits#INVALID_PARSE_PARAMS)
*   422[INVALID\_IDEMPOTENCY\_KEY](/en/docs/api/errors-and-limits#INVALID_IDEMPOTENCY_KEY)
*   422[INVALID\_COLUMN\_MAPPING](/en/docs/api/errors-and-limits#INVALID_COLUMN_MAPPING)
*   422[TEMPLATE\_OP\_REFUSED](/en/docs/api/errors-and-limits#TEMPLATE_OP_REFUSED)
*   422[REFERENCE\_TABLE\_NOT\_FOUND](/en/docs/api/errors-and-limits#REFERENCE_TABLE_NOT_FOUND)
*   422[REFERENCE\_TABLE\_COLUMN\_MISSING](/en/docs/api/errors-and-limits#REFERENCE_TABLE_COLUMN_MISSING)
*   422[REFERENCE\_TABLE\_REFUSED](/en/docs/api/errors-and-limits#REFERENCE_TABLE_REFUSED)
*   422[TEMPLATE\_COLUMNS\_MISSING](/en/docs/api/errors-and-limits#TEMPLATE_COLUMNS_MISSING)
*   422[TEMPLATE\_OUTPUT\_AS\_SOURCE](/en/docs/api/errors-and-limits#TEMPLATE_OUTPUT_AS_SOURCE)
*   422[TEMPLATE\_TAKES\_ONE\_FILE](/en/docs/api/errors-and-limits#TEMPLATE_TAKES_ONE_FILE)
*   422[JOIN\_FILE\_MISSING](/en/docs/api/errors-and-limits#JOIN_FILE_MISSING)
*   422[JOIN\_FILE\_COLUMNS\_MISSING](/en/docs/api/errors-and-limits#JOIN_FILE_COLUMNS_MISSING)
*   422[RUN\_FILES\_AMBIGUOUS](/en/docs/api/errors-and-limits#RUN_FILES_AMBIGUOUS)
*   429[CONCURRENCY\_LIMIT\_REACHED](/en/docs/api/errors-and-limits#CONCURRENCY_LIMIT_REACHED)
*   429[RATE\_LIMITED](/en/docs/api/errors-and-limits#RATE_LIMITED)

[See every error code and the limits](/en/docs/api/errors-and-limits)

### [The Reference Table object](#reference-table-object)

A saved Reference Table: its columns and size, never a row.

ExampleCopy

    {
      "columns": [
        "SKU",
        "Category",
        "Brand"
      ],
      "id": "rt_8d1f0c2a4b6e4a9fb3c7e5d2a1f09b64",
      "name": "Catalog",
      "rows": 1840,
      "updated_at": "2026-10-06T22:15:40Z",
      "used_by": [
        {
          "id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
          "name": "Monthly invoices"
        }
      ]
    }

Attributes

*   `columns`arrayrequired
    
    The table's column names, in order.
    
*   `id`stringrequired
    
    The table's id; send it to replace its rows.
    
*   `name`stringrequired
    
    The name the table was saved under.
    
*   `rows`integerrequired
    
    How many rows the table holds.
    
*   `updated_at`stringdate-timerequired
    
    When the table's rows last changed.
    
*   `used_by`arrayrequired
    
    The Templates with a Join Step on this table.
    
    \+ Show attributes (2)
