DocTransform

API reference

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

Base URL
https://doctransform.xyz/api/v1
Authentication
Authorization: Bearer · How to get an API key
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
· doctransform.xyz/api/v1/openapi.json

Templates

List templates

GET/templates

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

Scope templates:read

GET/templates
curl "https://doctransform.xyz/api/v1/templates" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"
Response200
{
  "data": [
    {
      "description": "Cleans the billing export and keeps the paid invoices.",
      "id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
      "name": "Monthly invoices",
      "output_format": "csv"
    }
  ]
}

The Template object

A saved Template a Run can apply.

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

Attributes

  • descriptionstringoptionalnullable

    What the Template does, when its owner wrote one.

  • idstringrequired

    The Template's id; send it to create a Run.

  • namestringoptionalnullable

    The name the Template was saved under.

  • output_formatstringoptionalnullable

    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

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}/runs
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"
Response201
{
  "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_idstringrequired

    The id of the Template to run.

Headers

  • Idempotency-Keystringoptional

    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_mappingstringoptional

    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.

  • delimiterstringoptional

    The one character that separates the columns of a delimited text file. The delimiter is detected when omitted.

  • filefilerequired

    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_rowintegeroptional

    Which row holds the column names, 0-based. The header is detected when omitted.

Returns A Run object

Errors (33)

See every error code and the limits

Retrieve a 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}
curl "https://doctransform.xyz/api/v1/runs/{run_id}" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"
Response200
{
  "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
    }
  ]
}

Download the output

GET/runs/{run_id}/output

Downloads the file a finished run produced.

Scope runs:read

GET/runs/{run_id}/output
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.

Download from a link

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}/download
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_idstringrequired

    The id of the Run, as returned when it was created.

Returns The output file

Errors (7)

See every error code and the limits

The Run object

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

Example
{
  "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_reportobjectoptionalnullable

    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.

  • completed_atstringdate-timeoptionalnullable

    When the Run finished; null while it is running.

  • created_atstringdate-timerequired

    When the Run was accepted.

  • destination_checkobjectoptionalnullable

    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.

  • errorobjectoptionalnullable

    Why the Run failed; null unless it did.

  • expires_atstringdate-timeoptionalnullable

    30 minutes after the Run finished, or 3 days when a Webhook receives it; null while it is running.

  • idstringrequired

    The Run's id, run_ followed by 32 hex digits.

  • outputobjectoptionalnullable

    The output file; null until the Run succeeds.

  • reference_tablesarrayoptional

    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.

  • rows_writtenintegeroptionalnullable

    Rows in the output file; null until the Run succeeds.

  • statusrunning | succeeded | failedrequired

    Where the Run is now.

  • template_idstringrequired

    The Template the Run applied.

  • truncatedbooleanoptional

    True when the output was cut at the plan's row limit.

  • warningsarrayoptional

    Warnings the Run succeeded despite; empty when there are none.

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

A Run succeeded

POSTrun.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 URL
{
  "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
  }
}

A Run failed

POSTrun.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 URL
{
  "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."
    }
  }
}

A test event

POSTwebhook.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 URL
{
  "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
  }
}

The event body

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

Example
{
  "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

  • dataobjectrequired

    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.

  • timestampstringdate-timerequired

    When the event was created, as a UTC date and time.

  • typestringrequired

    What happened: run.succeeded, run.failed, or webhook.test for the test event you send from your account.

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-tables
curl "https://doctransform.xyz/api/v1/reference-tables" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"
Response200
{
  "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"
        }
      ]
    }
  ]
}

Replace a reference table's 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}/rows
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"
Response200
{
  "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
    }
  ]
}

The Reference Table object

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

Example
{
  "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

  • columnsarrayrequired

    The table's column names, in order.

  • idstringrequired

    The table's id; send it to replace its rows.

  • namestringrequired

    The name the table was saved under.

  • rowsintegerrequired

    How many rows the table holds.

  • updated_atstringdate-timerequired

    When the table's rows last changed.

  • used_byarrayrequired

    The Templates with a Join Step on this table.