# テンプレート＆フィールド API リファレンス

> ImageToTable.ai v1 API で、抽出用テンプレートとそのフィールド（抽出が生成する列）の作成・管理、組み込みプリセットテンプレートの参照、出力フィールド順序の制御を行います。

**テンプレート**は、ドキュメントから抽出したい**フィールド**（出力列ごとに1つ）を保存して再利用できるリストです。テンプレートの`id`を[バッチ処理の開始](/developers/reference/batches#start-processing-a-batch)に渡すことで、毎回フィールドを再指定する必要がなくなります。組み込みの[プリセット](#list-presets)からテンプレートを作成することも、テンプレートを完全にスキップしてアドホックな`fields`を直接`process`に渡し、1回限りの実行を行うこともできます。

## テンプレート一覧

保存済みのテンプレートを、各テンプレートの完全なフィールドリスト（順序付き）とともに返します。

`GET /api/v1/templates`

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| limit | クエリ（省略可） | 整数 | 1～100。デフォルトは50。 |
| page_token | クエリ（省略可） | 文字列 | 前回のレスポンスの next_page_token から取得するオペークカーソル。 ページネーション を参照。 |

### 発生するエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラーハンドリング](/developers/guides/errors)を参照してください。
- `invalid_parameter` — `limit`または`page_token`が不正です。

## テンプレートを作成する

1つのエンドポイントでテンプレートを作成する方法は2つあります。ゼロから作成する方法（`base_template_id`を使用して別のテンプレートのフィールドをオプションで複製）と、`preset_id`を使用して組み込みプリセットから作成する方法です。

`POST /api/v1/templates`

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| name | body (JSON) | string | preset_id が指定されていない場合は必須です（指定された場合はプリセットの名前が使用され、その名前のテンプレートが既に存在する場合はタイムスタンプサフィックスで重複回避されます）。 |
| preset_id | body (JSON) | string, オプション | 組み込みプリセットからテンプレート（およびそのフィールド）を作成します。有効なIDについては プリセット一覧 を参照してください。 |
| base_template_id | body (JSON) | integer, オプション | preset_id が指定されていない場合のみ使用されます。既存のテンプレートのフィールドを新しいテンプレートに複製します。 |

### 発生するエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラーハンドリング](/developers/guides/errors)を参照してください。
- `missing_parameter` (`param: "name"`) — `name`と`preset_id`の両方がありません。
- `invalid_parameter` (`param: "name"`) — この名前のテンプレートが既に存在します（プリセット以外の作成パスのみ）。
- `invalid_parameter` (`param: "preset_id"`) — 不明なプリセットIDです。
- `internal_error`

## テンプレートの削除

テンプレートとそのすべてのフィールドを削除します（カスケード — 別途クリーンアップ呼び出しは不要）。過去の`process`呼び出しでこのテンプレートを使用したドキュメントには影響しません。既に抽出された結果は変更されません。

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

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| id | path | integer | 削除するテンプレート。 |

### 発生しうるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラーハンドリング](/developers/guides/errors)を参照。
- `template_not_found`
- `internal_error`

## プリセット一覧

一般的なドキュメントタイプ（請求書、領収書、銀行取引明細書など）向けの組み込みフィールドリストです。プリセットの`id`を[テンプレート作成](#create-a-template)の`preset_id`として渡すと、フィールドを手動で列挙しなくても動作するテンプレートを取得できます。プリセットは静的設定であり、データベース行ではありません。APIを通じて作成、編集、削除することはできません。

`GET /api/v1/presets`

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| category | query, optional | string | カテゴリでフィルタリング（例： "Finance & Accounting" ）。省略すると全カテゴリを表示。 |
| limit | query, optional | integer | 1～100。デフォルトは50。 |
| page_token | query, optional | string | 前回のレスポンスの next_page_token から取得したオペークカーソル。 |

### 発生しうるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラーハンドリング](/developers/guides/errors)を参照してください。
- `invalid_parameter` — `limit`または`page_token`が不正です。

## フィールドの一覧取得と作成

`fields`は、製品UIで「マッチルール」と呼ばれるもののv1-public名です。出力列ごとに1つのフィールドが、抽出時に出力される順序で並びます。`GET`はテンプレート上のすべてのフィールドを`sort_order`でソートして返します。`POST`は新しいフィールドを末尾に追加します。

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

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| id | パス | 整数 | これらのフィールドが属するテンプレート。 |
| name | ボディ（JSON）、POSTのみ | 文字列 | 必須。このテンプレート内で一意である必要があります。以下のエラーを参照してください。 |
| format_requirement | ボディ（JSON）、POSTのみ | 文字列、オプション | 期待される値の形式に関する自由形式のヒント（例： "YYYY-MM-DD" 、 "Number" ）。 |

### 発生しうるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラーハンドリング](/developers/guides/errors)を参照してください。
- `template_not_found`
- `missing_parameter`（`param: "name"`） — POSTのみ。
- `duplicate_field_name` — この`name`を持つフィールドがすでにこのテンプレートに存在します。
- `internal_error`

## フィールドの更新と削除

`PUT` はフィールド名を変更し（`format_requirement` も置き換えます）— 部分更新ではなく完全置換のため、1つだけ変更した場合でも両方の値を含める必要があります。`DELETE` はフィールドを削除します。

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

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| id | パス | 整数 | このフィールドが属するテンプレート。 |
| field_id | パス | 整数 | 更新または削除するフィールド。 |
| name | ボディ (JSON)、PUTのみ | 文字列 | 必須。新しい名前。 |
| format_requirement | ボディ (JSON)、PUTのみ | 文字列、オプション | 新しい形式ヒント — 省略すると空文字列にクリアされ、変更なしのままにはなりません。 |

### 発生しうるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラーハンドリング](/developers/guides/errors) を参照してください。
- `template_not_found` — テンプレートが存在しないか、あなたのものではありません（または、その旨のメッセージとともに、`field_id` がこのテンプレートに存在しません）。
- `missing_parameter` (`param: "name"`) — PUTのみ。
- `duplicate_field_name` — PUTのみ。このテンプレート上の別のフィールドがすでに持っている名前に変更しようとした場合。
- `internal_error`

## フィールドの並び替え

フィールドの順序を明示的に設定します。これにより、`line_items` および Excel/Word エクスポートにおける出力列の順序が決まります。リスト内にこのテンプレートに属さない ID が含まれている場合、リクエスト全体を拒否するのではなく、暗黙的に無視されます。

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

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| id | path | integer | 並び替え対象のテンプレート。 |
| field_ids | body (JSON) | array of integers | このテンプレート上のすべてのフィールドIDを、表示したい順序で指定します。必須。 |

### 発生しうるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラーハンドリング](/developers/guides/errors)を参照してください。
- `template_not_found`
- `invalid_parameter` (`param: "field_ids"`) — 整数のリストではありません。
- `internal_error`

## Code Examples

### テンプレート一覧

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

### レスポンス

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

### テンプレートを作成 — ゼロから

POST /api/v1/templates

2つの方法のうちの1つ目 — `name`のみで、まだフィールドはありません。 フィールドは後から[フィールドの一覧と作成](#list-and-create-fields)で追加するか、同じ呼び出し内で`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());
```

### レスポンス

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

### テンプレートの作成 — プリセットから

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

### レスポンス

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

### テンプレートを削除

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

### レスポンス

204 No Content — 空のボディ。

### プリセット一覧

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

### レスポンス

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

### フィールドの一覧 / 作成

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

### レスポンス

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

### フィールドを更新

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

### レスポンス

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

### フィールドを削除

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

### レスポンス

204 No Content — 空のボディ。

### フィールドの並び替え

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

### レスポンス

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