DocTransform

API-Referenz

Jeder Endpunkt der öffentlichen API mit seiner Anfrage und einer Beispielantwort.

Basis-URL
https://doctransform.xyz/api/v1
Authentifizierung
Authorization: Bearer · So bekommst du einen API-Schlüssel
Versionierung
Eine Version, in der Basis-URL. Was wir abschaffen, funktioniert noch mindestens 12 Monate, nachdem wir es mit den Headern Deprecation und Sunset markiert haben.
Antworten
Ignoriere jedes Feld, das du nicht kennst: Wir fügen Felder ohne Vorwarnung hinzu.
OpenAPI 3.1
· doctransform.xyz/api/v1/openapi.json

Vorlagen

Vorlagen auflisten

GET/templates

Gibt die Vorlagen deines Kontos zurück. Nutze die ID einer Vorlage, um einen Lauf zu erstellen.

Berechtigung templates:read

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

Das Template-Objekt

Eine gespeicherte Vorlage, die ein Run anwenden kann.

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

Attribute

  • descriptionstringfreiwillignullbar

    What the Template does, when its owner wrote one.

  • idstringerforderlich

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

  • namestringfreiwillignullbar

    The name the Template was saved under.

  • output_formatstringfreiwillignullbar

    The file format a Run of this Template writes. A Template's Summary sheet is written only when this is xlsx.

Läufe

Einen Lauf erstellen

POST/templates/{template_id}/runs

Führt eine Vorlage auf einer Datei aus, plus je einer Datei für jede Verbindungsdatei, die die Vorlage liest, zugeordnet nach Kopfzeile, nicht nach Reihenfolge. Antwortet mit 201 und dem fertigen Lauf, wenn er in etwa 30 Sekunden endet, sonst mit 202, während er weiterläuft. Sende einen Idempotency-Key, dann wird eine Wiederholung nie doppelt berechnet. Ein abgeschlossener Lauf verbraucht einen Export deines Monatskontingents; ein abgelehnter, fehlgeschlagener oder wiederholter Lauf keinen.

Berechtigung 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"
Antwort201
{
  "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
    }
  ]
}

Pfadparameter

  • template_idstringerforderlich

    The id of the Template to run.

Header

  • Idempotency-Keystringfreiwillig

    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.

Anfragetext (multipart/form-data)

  • column_mappingstringfreiwillig

    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.

  • delimiterstringfreiwillig

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

  • filefileerforderlich

    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_rowintegerfreiwillig

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

Liefert Ein Run-Objekt

Fehler (33)

Alle Fehlercodes und Limits ansehen

Einen Lauf abrufen

GET/runs/{run_id}

Gibt den Status eines Laufs zurück. Frage ab, bis er succeeded oder failed ist.

Berechtigung runs:read

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

Das Ergebnis herunterladen

GET/runs/{run_id}/output

Lädt die Datei herunter, die ein beendeter Lauf erzeugt hat.

Berechtigung 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"
Antwort200

Binärdatei. Der Content-Type folgt dem Ausgabeformat der Vorlage.

Das Ergebnis über einen Link herunterladen

GET/runs/{run_id}/download

Lädt die Datei eines beendeten Laufs über einen vorsignierten Link herunter. Kein API-Schlüssel nötig: Der Link ist bewusst öffentlich und läuft ab, gib ihn also nur an Personen weiter, die die Datei haben sollen.

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

Binärdatei. Der Content-Type folgt dem Ausgabeformat der Vorlage.

Pfadparameter

  • run_idstringerforderlich

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

Liefert Die Ausgabedatei

Fehler (7)

Alle Fehlercodes und Limits ansehen

Das Run-Objekt

Ein Run: sein Status, seine Zeitstempel und, sobald vorhanden, seine Ausgabedatei.

Beispiel
{
  "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
    }
  ]
}

Attribute

  • change_reportobjectfreiwillignullbar

    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-timefreiwillignullbar

    When the Run finished; null while it is running.

  • created_atstringdate-timeerforderlich

    When the Run was accepted.

  • destination_checkobjectfreiwillignullbar

    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.

  • errorobjectfreiwillignullbar

    Why the Run failed; null unless it did.

  • expires_atstringdate-timefreiwillignullbar

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

  • idstringerforderlich

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

  • outputobjectfreiwillignullbar

    The output file; null until the Run succeeds.

  • reference_tablesarrayfreiwillig

    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_writtenintegerfreiwillignullbar

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

  • statusrunning | succeeded | failederforderlich

    Where the Run is now.

  • template_idstringerforderlich

    The Template the Run applied.

  • truncatedbooleanfreiwillig

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

  • warningsarrayfreiwillig

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

Webhook-Ereignisse

Was dein Empfänger erhält, wenn ein Run endet. DocTransform sendet jedes Ereignis als POST mit JSON-Inhalt an die URL eines Webhooks, den du in deinem Konto angelegt hast. Alle Ereignisse haben dieselbe Form, beschrieben am Ende dieser Gruppe.

Webhooks-Anleitung

Ein Run war erfolgreich

POSTrun.succeeded

Wird gesendet, wenn ein Run endet und seine Ausgabedatei bereit ist. Der Inhalt enthält einen Download-Link, der bis zu seinem Ablauf keinen API-Schlüssel braucht.

An deine URL gesendeter Inhalt
{
  "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
  }
}

Ein Run ist fehlgeschlagen

POSTrun.failed

Wird gesendet, wenn ein Run ohne Ausgabedatei endet. Der Inhalt nennt den Grund als festen Code und einen einfachen Satz.

An deine URL gesendeter Inhalt
{
  "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."
    }
  }
}

Ein Testereignis

POSTwebhook.test

Wird nur gesendet, wenn du in deinem Konto auf Testereignis senden drückst, um deinen Empfänger zu prüfen. Es beschreibt einen erfundenen Run, sein Link funktioniert nicht.

An deine URL gesendeter Inhalt
{
  "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
  }
}

Der Ereignis-Inhalt

Was jedes Webhook-Ereignis enthält: was passiert ist, wann und die Angaben zum Run. Nie eine Zeile, eine Zelle oder ein Dateiname.

Beispiel
{
  "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
  }
}

Attribute

  • dataobjecterforderlich

    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-timeerforderlich

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

  • typestringerforderlich

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

Referenztabellen

Referenztabellen auflisten

GET/reference-tables

Gibt die Referenztabellen deines Kontos zurück: Name, Spalten, Zeilenzahl, letzte Änderung und die Vorlagen, die sie nutzen. Nie eine Zeile.

Berechtigung reference_tables:read

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

Zeilen einer Referenztabelle ersetzen

PUT/reference-tables/{table_id}/rows

Tauscht alle Zeilen einer Tabelle gegen die Zeilen der gesendeten Datei, ganz oder gar nicht. Eine Datei, der eine Spalte fehlt, die eine Vorlage liest, wird mit 409 REFERENCE_TABLE_COLUMN_IN_USE abgewiesen und ersetzt nichts.

Berechtigung 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"
Antwort200
{
  "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
    }
  ]
}

Das Reference-Table-Objekt

Eine gespeicherte Referenztabelle: ihre Spalten und ihre Größe, nie eine Zeile.

Beispiel
{
  "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"
    }
  ]
}

Attribute

  • columnsarrayerforderlich

    The table's column names, in order.

  • idstringerforderlich

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

  • namestringerforderlich

    The name the table was saved under.

  • rowsintegererforderlich

    How many rows the table holds.

  • updated_atstringdate-timeerforderlich

    When the table's rows last changed.

  • used_byarrayerforderlich

    The Templates with a Join Step on this table.