# Référence API Templates & Champs

> Créez et gérez des Templates d'extraction et leurs Champs (les colonnes produites par l'extraction), parcourez les modèles prédéfinis intégrés et contrôlez l'ordre des champs de sortie pour l'API ImageToTable.ai v1.

Un **Template** est une liste sauvegardée et réutilisable de **Champs** à extraire d'un document — un champ par colonne de sortie. Passez l'`id` d'un Template à [Lancer le traitement d'un lot](/developers/reference/batches#start-processing-a-batch) au lieu de lister vos champs à chaque appel. Vous pouvez aussi créer un Template à partir d'un [modèle prédéfini](#list-presets) intégré, ou ignorer les Templates et passer des `fields` ad-hoc directement à `process` pour une exécution unique.

## Lister les templates

Renvoie vos templates sauvegardés, chacun avec sa liste de champs complète et ordonnée.

`GET /api/v1/templates`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| limit | query, optionnel | entier | 1–100. Par défaut 50. |
| page_token | query, optionnel | chaîne | Curseur opaque provenant du next_page_token d'une réponse précédente. Voir Pagination . |

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `invalid_parameter` — `limit` ou `page_token` incorrect.

## Créer un modèle

Deux façons de créer un modèle en un seul point d'accès : de zéro (en clonant éventuellement les champs d'un autre modèle via `base_template_id`), ou à partir d'un préréglage intégré via `preset_id`.

`POST /api/v1/templates`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| name | corps (JSON) | chaîne | Requis sauf si preset_id est fourni (dans ce cas, le nom du préréglage est utilisé, désambiguïsé par un suffixe horodaté si vous avez déjà un modèle portant ce nom). |
| preset_id | corps (JSON) | chaîne, facultatif | Construire le modèle (et ses champs) à partir d'un préréglage intégré — voir Lister les préréglages pour les ID valides. |
| base_template_id | corps (JSON) | entier, facultatif | Utilisé uniquement quand preset_id n'est pas fourni — clone les champs de ce modèle existant dans le nouveau. |

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `missing_parameter` (`param: "name"`) — pas de `name` ni de `preset_id`.
- `invalid_parameter` (`param: "name"`) — un modèle avec ce nom existe déjà (uniquement pour la création sans préréglage).
- `invalid_parameter` (`param: "preset_id"`) — ID de préréglage inconnu.
- `internal_error`

## Supprimer un modèle

Supprime un modèle et tous ses champs (cascade — aucun appel de nettoyage séparé nécessaire). Cela n'affecte pas les documents qui ont déjà utilisé ce modèle lors d'un appel `process` antérieur ; leurs résultats déjà extraits restent inchangés.

`DELETE /api/v1/templates/{id}`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| id | chemin | entier | Le modèle à supprimer. |

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `template_not_found`
- `internal_error`

## Lister les préréglages

Listes de champs intégrées pour les types de documents courants (factures, reçus, relevés bancaires, etc.) — transmettez l'`id` d'un préréglage comme `preset_id` à [Créer un modèle](#create-a-template) pour obtenir un modèle fonctionnel sans avoir à lister les champs manuellement. Les préréglages sont une configuration statique, pas des lignes de base de données — il n'est pas possible d'en créer, modifier ou supprimer via l'API.

`GET /api/v1/presets`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| category | requête, optionnel | chaîne | Filtrer par catégorie (ex. "Finance & Comptabilité" ). Omettre pour lister toutes les catégories. |
| limit | requête, optionnel | entier | 1–100. Par défaut 50. |
| page_token | requête, optionnel | chaîne | Curseur opaque provenant du next_page_token d'une réponse précédente. |

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `invalid_parameter` — `limit` ou `page_token` incorrect.

## Lister et créer des champs

`fields` est le nom public v1 de ce que l'interface produit appelle « règles de correspondance » — un champ par colonne de sortie, dans l'ordre où l'extraction les émettra. `GET` renvoie tous les champs du modèle, déjà triés par `sort_order`. `POST` ajoute un nouveau champ à la fin.

`GET POST /api/v1/templates/{id}/fields`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| id | chemin | entier | Le modèle auquel ces champs appartiennent. |
| name | corps (JSON), POST uniquement | chaîne | Requis. Doit être unique dans ce modèle — voir erreurs ci-dessous. |
| format_requirement | corps (JSON), POST uniquement | chaîne, facultatif | Indice en texte libre sur le format attendu (ex. "YYYY-MM-DD" , "Nombre" ). |

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `template_not_found`
- `missing_parameter` (`param: "name"`) — POST uniquement.
- `duplicate_field_name` — un champ avec ce `name` existe déjà sur ce modèle.
- `internal_error`

## Mettre à jour et supprimer un champ

`PUT` renomme un champ (et remplace son `format_requirement`) — il s'agit d'un remplacement complet, pas d'une mise à jour partielle, donc incluez les deux valeurs même si une seule a changé. `DELETE` le supprime.

`PUT DELETE /api/v1/templates/{id}/fields/{field_id}`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| id | chemin | entier | Le modèle auquel appartient ce champ. |
| field_id | chemin | entier | Le champ à mettre à jour ou supprimer. |
| name | corps (JSON), PUT uniquement | chaîne | Requis. Nouveau nom. |
| format_requirement | corps (JSON), PUT uniquement | chaîne, facultatif | Nouvel indice de format — omettez-le et il sera effacé en chaîne vide, pas laissé inchangé. |

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `template_not_found` — le modèle n'existe pas / ne vous appartient pas, ou (avec un message le précisant) le `field_id` n'est pas sur ce modèle.
- `missing_parameter` (`param: "name"`) — PUT uniquement.
- `duplicate_field_name` — PUT uniquement, renommage avec un nom déjà utilisé par un autre champ sur ce modèle.
- `internal_error`

## Réorganiser les champs

Définit explicitement l'ordre des champs, qui détermine l'ordre des colonnes en sortie dans `line_items` et dans les exportations Excel/Word. Les ID de la liste qui n'appartiennent pas à ce modèle sont ignorés silencieusement, sans rejeter la requête entière.

`PATCH /api/v1/templates/{id}/fields/order`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| id | chemin | entier | Le modèle à réorganiser. |
| field_ids | corps (JSON) | tableau d'entiers | Tous les ID de champ de ce modèle, dans l'ordre souhaité. Requis. |

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `template_not_found`
- `invalid_parameter` (`param: "field_ids"`) — ce n'est pas une liste d'entiers.
- `internal_error`

## Code Examples

### Lister les modèles

GET /api/v1/templates

**cURL**

```bash
curl https://imagetotable.ai/api/v1/templates \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/templates",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates", {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

### Réponse

```json
{
  "data": [
    {
      "id": 42,
      "name": "Invoice Template",
      "created_at": "2026-06-01T10:00:00+00:00",
      "fields": [
        {
          "id": 101,
          "name": "invoice_number",
          "format_requirement": "",
          "sort_order": 1,
          "template_id": 42,
          "created_at": "2026-06-01T10:00:00+00:00"
        },
        {
          "id": 102,
          "name": "invoice_date",
          "format_requirement": "YYYY-MM-DD",
          "sort_order": 2,
          "template_id": 42,
          "created_at": "2026-06-01T10:00:00+00:00"
        }
      ]
    }
  ],
  "has_more": false,
  "next_page_token": null
}
```

### Créer un modèle — à partir de zéro

POST /api/v1/templates

La première des deux méthodes — juste un `name`, sans champs pour l'instant. Ajoutez des champs ensuite avec [Lister et créer des champs](#list-and-create-fields), ou clonez les champs d'un autre modèle dans le même appel via `base_template_id`.

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/templates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Invoice Template"}'
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/templates",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"name": "My Invoice Template"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "My Invoice Template" }),
});
console.log(await response.json());
```

### Réponse

```json
{
  "template": {
    "id": 44,
    "name": "My Invoice Template",
    "created_at": "2026-07-16T09:00:00+00:00",
    "fields": []
  }
}
```

### Créer un modèle — à partir d'un préréglage

POST /api/v1/templates

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/templates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset_id": "finance_invoice_general"}'
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/templates",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"preset_id": "finance_invoice_general"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ preset_id: "finance_invoice_general" }),
});
console.log(await response.json());
```

### Réponse

```json
{
  "template": {
    "id": 43,
    "name": "Invoice",
    "created_at": "2026-07-16T09:00:00+00:00",
    "fields": [
      {
        "id": 201,
        "name": "Merchant Name",
        "format_requirement": "String",
        "sort_order": 1,
        "template_id": 43,
        "created_at": "2026-07-16T09:00:00+00:00"
      }
    ]
  }
}
```

### Supprimer un modèle

DELETE /api/v1/templates/{id}

**cURL**

```bash
curl -X DELETE https://imagetotable.ai/api/v1/templates/43 \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://imagetotable.ai/api/v1/templates/43",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.status_code)
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates/43", {
  method: "DELETE",
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(response.status);
```

### Réponse

204 Aucun contenu — corps vide.

### Lister les préréglages

GET /api/v1/presets

**cURL**

```bash
curl "https://imagetotable.ai/api/v1/presets?category=Finance%20%26%20Accounting" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/presets",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    params={"category": "Finance & Accounting"},
)
print(response.json())
```

**Javascript**

```javascript
const url = new URL("https://imagetotable.ai/api/v1/presets");
url.searchParams.set("category", "Finance & Accounting");

const response = await fetch(url, {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

### Réponse

```json
{
  "data": [
    {
      "id": "finance_invoice_general",
      "category": "Finance & Accounting",
      "name": "Invoice",
      "fields": [
        {"name": "Invoice Number", "format_requirement": "DocumentNumber"},
        {"name": "Invoice Date", "format_requirement": "YYYY-MM-DD"},
        {"name": "Total Amount", "format_requirement": "Number"}
      ]
    }
  ],
  "has_more": false,
  "next_page_token": null
}
```

### Lister / créer des champs

POST /api/v1/templates/{id}/fields

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/templates/42/fields \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "vendor_name", "format_requirement": "String"}'
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/templates/42/fields",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"name": "vendor_name", "format_requirement": "String"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates/42/fields", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "vendor_name", format_requirement: "String" }),
});
console.log(await response.json());
```

### Réponse

```json
{
  "field": {
    "id": 103,
    "name": "vendor_name",
    "format_requirement": "String",
    "sort_order": 103,
    "template_id": 42,
    "created_at": "2026-07-16T09:05:00+00:00"
  }
}
```

### Mettre à jour un champ

PUT /api/v1/templates/{id}/fields/{field_id}

**cURL**

```bash
curl -X PUT https://imagetotable.ai/api/v1/templates/42/fields/103 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "vendor_name", "format_requirement": "Company name, no suffix"}'
```

**Python**

```python
import os
import requests

response = requests.put(
    "https://imagetotable.ai/api/v1/templates/42/fields/103",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"name": "vendor_name", "format_requirement": "Company name, no suffix"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates/42/fields/103", {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "vendor_name", format_requirement: "Company name, no suffix" }),
});
console.log(await response.json());
```

### Réponse

```json
{
  "field": {
    "id": 103,
    "name": "vendor_name",
    "format_requirement": "Company name, no suffix",
    "sort_order": 103,
    "template_id": 42,
    "created_at": "2026-07-16T09:05:00+00:00"
  }
}
```

### Supprimer un champ

DELETE /api/v1/templates/{id}/fields/{field_id}

**cURL**

```bash
curl -X DELETE https://imagetotable.ai/api/v1/templates/42/fields/103 \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://imagetotable.ai/api/v1/templates/42/fields/103",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.status_code)
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates/42/fields/103", {
  method: "DELETE",
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(response.status);
```

### Réponse

204 Aucun contenu — corps vide.

### Réorganiser les champs

PATCH /api/v1/templates/{id}/fields/order

**cURL**

```bash
curl -X PATCH https://imagetotable.ai/api/v1/templates/42/fields/order \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_ids": [102, 101, 103]}'
```

**Python**

```python
import os
import requests

response = requests.patch(
    "https://imagetotable.ai/api/v1/templates/42/fields/order",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"field_ids": [102, 101, 103]},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates/42/fields/order", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ field_ids: [102, 101, 103] }),
});
console.log(await response.json());
```

### Réponse

```json
{
  "data": [
    {"id": 102, "name": "invoice_date", "format_requirement": "YYYY-MM-DD", "sort_order": 1, "template_id": 42, "created_at": "2026-06-01T10:00:00+00:00"},
    {"id": 101, "name": "invoice_number", "format_requirement": "", "sort_order": 2, "template_id": 42, "created_at": "2026-06-01T10:00:00+00:00"},
    {"id": 103, "name": "vendor_name", "format_requirement": "Company name, no suffix", "sort_order": 3, "template_id": 42, "created_at": "2026-07-16T09:05:00+00:00"}
  ],
  "has_more": false,
  "next_page_token": null
}
```

---

Source: https://imagetotable.ai/fr/developers/reference/templates-fields