DocTransform

Référence de l'API

Chaque endpoint de l'API publique, avec sa requête et un exemple de réponse.

URL de base
https://doctransform.xyz/api/v1
Authentification
Authorization: Bearer · Comment obtenir une clé d'API
Versionnage
Une seule version, dans l'URL de base. Ce que nous retirons continue de fonctionner au moins 12 mois après avoir été marqué avec les en-têtes Deprecation et Sunset.
Réponses
Ignorez tout champ que vous ne reconnaissez pas : nous ajoutons des champs sans préavis.
OpenAPI 3.1
· doctransform.xyz/api/v1/openapi.json

Modèles

Lister les modèles

GET/templates

Renvoie les modèles de votre compte. Utilisez l'id d'un modèle pour créer une exécution.

Permission templates:read

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

L'objet Template

Un modèle enregistré qu'une exécution peut appliquer.

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

Attributs

  • descriptionstringfacultatifpeut être nul

    What the Template does, when its owner wrote one.

  • idstringobligatoire

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

  • namestringfacultatifpeut être nul

    The name the Template was saved under.

  • output_formatstringfacultatifpeut être nul

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

Exécutions

Créer une exécution

POST/templates/{template_id}/runs

Exécute un modèle sur un fichier, plus un fichier pour chaque fichier de jonction que le modèle lit, associés par en-tête, pas par ordre. Répond 201 avec l'exécution terminée si elle s'achève en 30 secondes environ, sinon 202 pendant qu'elle se poursuit. Envoyez une Idempotency-Key et une nouvelle tentative n'est jamais facturée deux fois. Une exécution terminée consomme une exportation de votre quota mensuel ; une exécution refusée, échouée ou rejouée n’en consomme aucune.

Permission 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"
Réponse201
{
  "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
    }
  ]
}

Paramètres de chemin

  • template_idstringobligatoire

    The id of the Template to run.

En-têtes

  • Idempotency-Keystringfacultatif

    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.

Corps (multipart/form-data)

  • column_mappingstringfacultatif

    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.

  • delimiterstringfacultatif

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

  • filefileobligatoire

    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_rowintegerfacultatif

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

Renvoie Un objet Run

Erreurs (33)

Voir tous les codes d'erreur et les limites

Consulter une exécution

GET/runs/{run_id}

Renvoie l'état d'une exécution. Interrogez jusqu'à ce qu'elle soit succeeded ou failed.

Permission runs:read

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

Télécharger le résultat

GET/runs/{run_id}/output

Télécharge le fichier produit par une exécution terminée.

Permission 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"
Réponse200

Fichier binaire. Le Content-Type suit le format de sortie du modèle.

Paramètres de chemin

  • run_idstringobligatoire

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

Renvoie Le fichier de sortie

Erreurs (11)

Voir tous les codes d'erreur et les limites

Télécharger le résultat depuis un lien

GET/runs/{run_id}/download

Télécharge le fichier d'un Run terminé depuis un lien pré-signé. Aucune clé d'API requise : le lien est public par conception et expire, ne le partagez qu'avec qui doit avoir le fichier.

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

Fichier binaire. Le Content-Type suit le format de sortie du modèle.

Paramètres de chemin

  • run_idstringobligatoire

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

Renvoie Le fichier de sortie

Erreurs (7)

Voir tous les codes d'erreur et les limites

L'objet Run

Une exécution : son statut, ses horodatages et, une fois prêt, son fichier de sortie.

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

Attributs

  • change_reportobjectfacultatifpeut être nul

    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-timefacultatifpeut être nul

    When the Run finished; null while it is running.

  • created_atstringdate-timeobligatoire

    When the Run was accepted.

  • destination_checkobjectfacultatifpeut être nul

    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.

  • errorobjectfacultatifpeut être nul

    Why the Run failed; null unless it did.

  • expires_atstringdate-timefacultatifpeut être nul

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

  • idstringobligatoire

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

  • outputobjectfacultatifpeut être nul

    The output file; null until the Run succeeds.

  • reference_tablesarrayfacultatif

    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_writtenintegerfacultatifpeut être nul

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

  • statusrunning | succeeded | failedobligatoire

    Where the Run is now.

  • template_idstringobligatoire

    The Template the Run applied.

  • truncatedbooleanfacultatif

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

  • warningsarrayfacultatif

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

Événements webhook

Ce que reçoit votre récepteur quand un Run se termine. DocTransform envoie chaque événement en POST avec un corps JSON à l'URL d'un webhook ajouté dans votre compte. Tous les événements ont la même forme, décrite à la fin de ce groupe.

Guide des webhooks

Un Run a réussi

POSTrun.succeeded

Envoyé quand un Run se termine et que son fichier de sortie est prêt. Le corps contient un lien de téléchargement qui n'exige aucune clé d'API jusqu'à son expiration.

Corps envoyé à votre 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
  }
}

Un Run a échoué

POSTrun.failed

Envoyé quand un Run se termine sans fichier de sortie. Le corps en donne la raison par un code fixe et une phrase simple.

Corps envoyé à votre 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."
    }
  }
}

Un événement de test

POSTwebhook.test

Envoyé seulement quand vous appuyez sur Envoyer un événement de test dans votre compte, pour vérifier votre récepteur. Il décrit un Run inventé et son lien ne fonctionne pas.

Corps envoyé à votre 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
  }
}

Le corps de l'événement

Ce que porte chaque événement webhook : ce qui s'est passé, quand, et les détails du Run. Jamais une ligne, une cellule ou un nom de fichier.

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

Attributs

  • dataobjectobligatoire

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

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

  • typestringobligatoire

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

Tables de référence

Lister les tables de référence

GET/reference-tables

Renvoie les tables de référence de votre compte : nom, colonnes, nombre de lignes, dernière modification et modèles qui les utilisent. Jamais une ligne.

Permission reference_tables:read

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

Remplacer les lignes d'une table de référence

PUT/reference-tables/{table_id}/rows

Échange toutes les lignes d'une table contre celles du fichier envoyé, tout ou rien. Un fichier qui retire une colonne lue par un modèle reçoit 409 REFERENCE_TABLE_COLUMN_IN_USE et ne remplace rien.

Permission 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"
Réponse200
{
  "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
    }
  ]
}

L'objet Reference Table

Une table de référence enregistrée : ses colonnes et sa taille, jamais une ligne.

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

Attributs

  • columnsarrayobligatoire

    The table's column names, in order.

  • idstringobligatoire

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

  • namestringobligatoire

    The name the table was saved under.

  • rowsintegerobligatoire

    How many rows the table holds.

  • updated_atstringdate-timeobligatoire

    When the table's rows last changed.

  • used_byarrayobligatoire

    The Templates with a Join Step on this table.