---
title: "Create training request"
method: POST
path: "/fields/{field_id}/train"
tags: ["Training"]
---

# Create training request

`POST /fields/{field_id}/train`

## Request

- Base URL: `https://us.app.zuva.ai/api/v2`
- URL: `https://us.app.zuva.ai/api/v2/fields/{field_id}/train`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/zuva/apis/zuva-docai/docs/fields/:field_id/train/post.ts> (a function with typed inputs; its response is checked against the schema)

Starts training on a field and returns the request id.

The `start` and `end` locations refer to the positions of the first and last characters of an example
text span that the model should learn to extract. The character positions must be given in terms of
Zuva's OCR representation of the document, which can be obtained from the [GET OCR layouts](#get-ocr-layouts)
endpoint.

## Path parameters

- `field_id` string, required

## Request body

- FieldTrainingRequest[]
  - `file_id` integer[], required
  - `locations` Location[], required
    - `end` integer, required
    - `start` integer, required

## Response `202`

The status of the training request

- TrainingRequestStatus
  - `error` HttpError
    - `error` HttpErrorDetails, required
      - `code` string, required: A unique string identifying the error.
      - `message` string, required: An error message providing more details and potential steps to resolve.
  - `field_id` string, required
  - `request_id` string, required
  - `status` 'queued' | 'processing' | 'complete' | 'failed', required
  - `span_issues` SpanIssue[]
    - `file_id` string
    - `span_problems` SpanProblems[]
      - `index` integer
      - `spans` Spans[]
        - `end` integer
        - `start` integer
        - `label` integer
      - `issue_type` string

## Other responses

- `400`: Invalid request body
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Field not found.
- `409`: Conflict: training request ongoing
- `500`: Internal Server Error

## Changes

- **2023-12-13** `51f2a4c5de2e`: 1 info
  - added the optional property `span_issues` to the response with the `202` status
- **2022-12-13** `7cace20deba7`: 1 breaking
  - the `items/file_id` request property type changed from `string` to `array`

[Operation history](https://skmtc.dev/zuva/apis/zuva-docai/changes/fields/:field_id/train/post.md)

---

[API](https://skmtc.dev/zuva/apis/zuva-docai.md) - [All operations](https://skmtc.dev/zuva/apis/zuva-docai/llms.txt) - [OpenAPI document](https://skmtc.dev/zuva/apis/zuva-docai/revisions/7397ad071d55?raw)