# API-Referenz: Vorlagen & Felder

> Erstellen und verwalten Sie Extraktionsvorlagen und deren Felder (die Spalten, die die Extraktion erzeugt), durchsuchen Sie integrierte Preset-Vorlagen und steuern Sie die Reihenfolge der Ausgabefelder für die ImageToTable.ai v1 API.

Eine **Vorlage** ist eine gespeicherte, wiederverwendbare Liste von **Feldern**, die aus einem Dokument extrahiert werden sollen – ein Feld pro Ausgabespalte. Übergeben Sie die `id` einer Vorlage an [Starten der Batch-Verarbeitung](/developers/reference/batches#start-processing-a-batch), anstatt Ihre Felder bei jedem Aufruf erneut aufzulisten. Sie können eine Vorlage auch aus einem integrierten [Preset](#list-presets) erstellen oder Vorlagen ganz überspringen und Ad-hoc-`fields` direkt an `process` für einen einmaligen Durchlauf übergeben.

## Vorlagen auflisten

Gibt Ihre gespeicherten Vorlagen zurück, jede mit ihrer vollständigen, geordneten Feldliste.

`GET /api/v1/templates`

### Parameter

| Name | Ort | Typ | Beschreibung |
| --- | --- | --- | --- |
| limit | Abfrage, optional | integer | 1–100. Standard 50. |
| page_token | Abfrage, optional | string | Undurchsichtiger Cursor aus dem next_page_token einer vorherigen Antwort. Siehe Paginierung . |

### Mögliche Fehler

- `missing_api_key` / `invalid_api_key` / `plan_required` — siehe [Fehlerbehandlung](/developers/guides/errors).
- `invalid_parameter` — ungültiges `limit` oder `page_token`.

## Vorlage erstellen

Zwei Wege, eine Vorlage in einem Endpunkt zu erstellen: von Grund auf (optional durch Klonen der Felder einer anderen Vorlage via `base_template_id`) oder aus einer integrierten Voreinstellung via `preset_id`.

`POST /api/v1/templates`

### Parameter

| Name | Ort | Typ | Beschreibung |
| --- | --- | --- | --- |
| name | body (JSON) | string | Erforderlich, sofern preset_id nicht angegeben ist (in diesem Fall wird auf den Namen der Voreinstellung zurückgegriffen, ggf. mit einem Zeitstempel-Suffix, falls bereits eine Vorlage mit diesem Namen existiert). |
| preset_id | body (JSON) | string, optional | Erstellt die Vorlage (und ihre Felder) aus einer integrierten Voreinstellung — gültige IDs siehe Voreinstellungen auflisten . |
| base_template_id | body (JSON) | integer, optional | Nur verwendet, wenn preset_id nicht angegeben ist — klont die Felder dieser bestehenden Vorlage in die neue. |

### Mögliche Fehler

- `missing_api_key` / `invalid_api_key` / `plan_required` — siehe [Fehlerbehandlung](/developers/guides/errors).
- `missing_parameter` (`param: "name"`) — kein `name` und kein `preset_id`.
- `invalid_parameter` (`param: "name"`) — eine Vorlage mit diesem Namen existiert bereits (nur bei Erstellung ohne Voreinstellung).
- `invalid_parameter` (`param: "preset_id"`) — unbekannte Voreinstellungs-ID.
- `internal_error`

## Vorlage löschen

Löscht eine Vorlage und alle zugehörigen Felder (Kaskade – kein separater Bereinigungsaufruf nötig). Bereits mit dieser Vorlage in einem früheren `process`-Aufruf verarbeitete Dokumente bleiben unberührt; deren extrahierte Ergebnisse sind nicht betroffen.

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

### Parameter

| Name | Ort | Typ | Beschreibung |
| --- | --- | --- | --- |
| id | Pfad | integer | Die zu löschende Vorlage. |

### Mögliche Fehler

- `missing_api_key` / `invalid_api_key` / `plan_required` — siehe [Fehlerbehandlung](/developers/guides/errors).
- `template_not_found`
- `internal_error`

## Voreinstellungen auflisten

Integrierte Feldlisten für gängige Dokumenttypen (Rechnungen, Quittungen, Kontoauszüge und mehr) – übergeben Sie die `id` einer Voreinstellung als `preset_id` an [Vorlage erstellen](#create-a-template), um eine funktionsfähige Vorlage zu erhalten, ohne Felder manuell auflisten zu müssen. Voreinstellungen sind statische Konfigurationen, keine Datenbankeinträge – es gibt keine Möglichkeit, eine über die API zu erstellen, zu bearbeiten oder zu löschen.

`GET /api/v1/presets`

### Parameter

| Name | Ort | Typ | Beschreibung |
| --- | --- | --- | --- |
| category | Abfrage, optional | string | Filter auf eine Kategorie (z. B. "Finanzen & Buchhaltung" ). Ohne Angabe werden alle Kategorien aufgelistet. |
| limit | Abfrage, optional | integer | 1–100. Standard 50. |
| page_token | Abfrage, optional | string | Undurchsichtiger Cursor aus dem next_page_token einer vorherigen Antwort. |

### Mögliche Fehler

- `missing_api_key` / `invalid_api_key` / `plan_required` — siehe [Fehlerbehandlung](/developers/guides/errors).
- `invalid_parameter` — ungültiges `limit` oder `page_token`.

## Felder auflisten und erstellen

`fields` ist der v1-public-Name für das, was die Produkt-UI als „Match-Regeln“ bezeichnet – ein Feld pro Ausgabespalte, in der Reihenfolge, in der die Extraktion sie ausgibt. `GET` gibt jedes Feld der Vorlage zurück, bereits nach `sort_order` sortiert. `POST` fügt am Ende ein neues Feld hinzu.

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

### Parameter

| Name | Ort | Typ | Beschreibung |
| --- | --- | --- | --- |
| id | Pfad | integer | Die Vorlage, zu der diese Felder gehören. |
| name | Body (JSON), nur POST | string | Erforderlich. Muss innerhalb dieser Vorlage eindeutig sein – siehe Fehler unten. |
| format_requirement | Body (JSON), nur POST | string, optional | Freitext-Hinweis zum erwarteten Werteformat (z. B. "YYYY-MM-DD" , "Zahl" ). |

### Mögliche Fehler

- `missing_api_key` / `invalid_api_key` / `plan_required` — siehe [Fehlerbehandlung](/developers/guides/errors).
- `template_not_found`
- `missing_parameter` (`param: "name"`) — nur POST.
- `duplicate_field_name` — ein Feld mit diesem `name` existiert bereits in dieser Vorlage.
- `internal_error`

## Feld aktualisieren und löschen

`PUT` benennt ein Feld um (und ersetzt dessen `format_requirement`) – es handelt sich um eine vollständige Ersetzung, kein partielles Update, daher beide Werte angeben, auch wenn nur einer geändert wurde. `DELETE` entfernt es.

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

### Parameter

| Name | Ort | Typ | Beschreibung |
| --- | --- | --- | --- |
| id | Pfad | integer | Die Vorlage, zu der dieses Feld gehört. |
| field_id | Pfad | integer | Das zu aktualisierende oder zu löschende Feld. |
| name | Body (JSON), nur PUT | string | Erforderlich. Neuer Name. |
| format_requirement | Body (JSON), nur PUT | string, optional | Neuer Format-Hinweis – weglassen setzt ihn auf einen leeren String, nicht unverändert lassen. |

### Mögliche Fehler

- `missing_api_key` / `invalid_api_key` / `plan_required` – siehe [Fehlerbehandlung](/developers/guides/errors).
- `template_not_found` – die Vorlage existiert nicht/gehört nicht Ihnen, oder (mit entsprechender Meldung) die `field_id` ist nicht in dieser Vorlage.
- `missing_parameter` (`param: "name"`) – nur PUT.
- `duplicate_field_name` – nur PUT, wenn der neue Name bereits von einem anderen Feld dieser Vorlage verwendet wird.
- `internal_error`

## Felder neu anordnen

Legt die Feldreihenfolge explizit fest, die die Ausgabespaltenreihenfolge in `line_items` und in Excel/Word-Exporten bestimmt. IDs in der Liste, die nicht zu dieser Vorlage gehören, werden stillschweigend ignoriert, anstatt die gesamte Anfrage abzulehnen.

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

### Parameter

| Name | Ort | Typ | Beschreibung |
| --- | --- | --- | --- |
| id | Pfad | integer | Die umzuordnende Vorlage. |
| field_ids | Body (JSON) | Array von Integern | Jede Feld-ID dieser Vorlage in der gewünschten Reihenfolge. Erforderlich. |

### Mögliche Fehler

- `missing_api_key` / `invalid_api_key` / `plan_required` — siehe [Fehlerbehandlung](/developers/guides/errors).
- `template_not_found`
- `invalid_parameter` (`param: "field_ids"`) — keine Liste von Integern.
- `internal_error`

## Code Examples

### Vorlagen auflisten

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());
```

### Antwort

```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
}
```

### Vorlage erstellen – von Grund auf

POST /api/v1/templates

Die erste von zwei Möglichkeiten – nur ein `name`, noch keine Felder. Felder später mit [Felder auflisten und erstellen](#list-and-create-fields) hinzufügen oder im selben Aufruf über `base_template_id` die Felder einer anderen Vorlage übernehmen.

**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());
```

### Antwort

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

### Vorlage erstellen – aus einer Voreinstellung

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());
```

### Antwort

```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"
      }
    ]
  }
}
```

### Vorlage löschen

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);
```

### Antwort

204 No Content — leerer Body.

### Voreinstellungen auflisten

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());
```

### Antwort

```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
}
```

### Felder auflisten / erstellen

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());
```

### Antwort

```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"
  }
}
```

### Feld aktualisieren

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());
```

### Antwort

```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"
  }
}
```

### Feld löschen

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);
```

### Antwort

204 Kein Inhalt — leerer Body.

### Felder neu anordnen

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());
```

### Antwort

```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/de/developers/reference/templates-fields