DocTransform

Runs

How a Run is created, how you know it finished and how to retry it without being charged twice.

Immediate answer or 202

POST /templates/{id}/runs waits up to 30 seconds for the Run to finish. If it does, you get 201 with the finished Run and its output is ready to download. Past 30 seconds you get 202, a Location header pointing at the Run and a Retry-After header telling you how long to wait before polling.

A CSV upload can send delimiter and header_row next to file, overriding the sniffed defaults for that one Run:

curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -F "file=@/path/to/your/file.csv" \
  -F "delimiter=;" \
  -F "header_row=0"

If a column was renamed, the Run answers TEMPLATE_COLUMNS_MISSING with missing_columns: each column the Template reads, with the file’s columns to choose from. Nothing is charged. Retry with column_mapping, a JSON object {"file column": "Template column"}, for that one Run only; it is never saved. A column that differs only in case, spaces or underscores is matched on its own and reported as a COLUMN_MATCHED warning.

Check the status

GET /runs/{id} answers the Run with its status: running, succeeded or failed. Poll it, waiting as long as Retry-After says, until it settles. Every field is in the API reference. Rather than polling, add a Webhook and DocTransform tells you when a Run finishes.

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

Download the result

GET /runs/{id}/output downloads the file. A finished Run’s output stays available for 30 minutes, or for 3 days when a Webhook receives the Run; after that, or for an unknown id, it answers RUN_NOT_FOUND.

curl "https://doctransform.xyz/api/v1/runs/run_abc/output" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -o result.csv

When a file cannot run

A Run has no running Dataset: every file it needs comes in the request. A request that cannot run is refused up front, never a failed Run to poll for.

A Template that names a system it uploads to adds a destination_check to the Run once it succeeds: passed, rows_checked, rows_failing and one reasons entry per failing rule, with its rule_id, the field header, the outcome, the count and a fixed message. It holds counts only, never a value from your file. A failing check does not fail the Run: the status, the status code and the charge are those of any succeeded Run, so a script can branch on passed before it uploads. It is null when the Template names no system and until the Run succeeds.

A succeeded Run also returns a change_report beside the output, one file or the ZIP of Split Parts: English lines with the rows changed per column, and the counts in steps. It holds counts and headers, never a value from your file. null until the Run succeeds.

Every succeeded Run keeps its counts on the Template. On the next Run, each step of the change_report carries last time’s counts in previous, matched by step_key; a new or edited step has new_or_changed instead. A count at least twice or at most half of last time’s, and at least 10 rows apart, is listed in swings and adds a CHANGE_COUNT_SWING warning to warnings. It never fails a Run. An Excel Run gains a last Changes tab; a CSV, JSON or XML Run returns your file as it is, not zipped like the app’s .zip, unless the Template has a File Split.

A Template with a File Split writes its output as Split Parts. A Run that writes two or more returns one application/zip named <name>.zip with one file per part; a Run that writes one part returns that file plain. output.split_parts counts the files, null without a File Split. A split into more than 100 parts fails the Run with FILE_SPLIT_TOO_MANY_PARTSand writes no file.

A Template with date steps needs no extra parameter. In a Time between dates step, an empty start or end reads as the UTC date the Run was created, so a replay of the same request counts to the same day. In a Date part step, month and weekday names come out in the step’s own name_language.

Send a Join File

A Template with a Join Step on a file sent with each Run needs that file in the request. Send it as one more file part: there is no field name to choose and no order to keep. The Run matches each part to the main file or to a Join File by the fit of its header, so the parts can come in any order:

curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -F "file=@/path/to/orders.csv" \
  -F "file=@/path/to/catalog.csv"

A Run that succeeds can carry join entries in warnings: JOIN_UNMATCHED_ROWS when rows found no match, JOIN_REPEATED_KEYS when the table repeats a key and each uses its first row, JOIN_CLOSE_MATCHES when rows were matched to a close spelling, and JOIN_CLOSE_MATCH_LIMIT when close matching stopped at its limit. Each carries counts. The few example values are in the 201 response that started the Run only: GET /runs/{id} and a replay with the same Idempotency-Key answer "sample": null with the counts alone.

The Run also lists reference_tables: the id, name, last update and row count of each table it read, as they were when it started. A table replaced while the Run was going does not change it.

Retry with Idempotency-Key

Send an Idempotency-Key header with the create request. A network retry of the same request replays the Run already started for that key instead of starting, and charging, a second one:

curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -H "Idempotency-Key: 3f2b9c1e-7a54-4d0e-9b61-0c8d5e2a41f7" \
  -F "file=@/path/to/your/file.csv"

Reusing a key with a different request answers IDEMPOTENCY_KEY_REUSED. A Run that settles as RUN_INTERRUPTED or RUN_TIMEOUT, or whose id answers RUN_NOT_FOUND, is safe to resubmit with the same key.