# Start a job

Scope `processing`. Upload every file first. Starting the same files again answers the job already running.

## Endpoint

`POST /v1/api/jobs/{id}/start`

## Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| id | path | string | Yes |

- **id:** The job's id, from the declare.

## Request body

Content type: `application/json`.

```json
{
  "productType": "mca"
}
```

## Responses

### 200

Already started with these files.

Content type: `application/json`.

```json
{
  "data": {
    "id": "",
    "state": "awaiting_start",
    "created": true,
    "job": {
      "id": "",
      "status": "started",
      "externalJobId": "",
      "idempotencyKey": "string",
      "requestedBy": "string",
      "requestedAt": "2026-01-01T00:00:00Z",
      "finishedAt": "2026-01-01T00:00:00Z",
      "finished": true,
      "events": [
        {
          "seq": 1,
          "event": "string",
          "at": "2026-01-01T00:00:00Z",
          "detail": {}
        }
      ],
      "documents": [
        {
          "id": "",
          "fileId": "",
          "fileName": "string",
          "documentType": "string",
          "attemptNo": 1,
          "outcome": "pending",
          "reason": "string",
          "contentSha256": "string",
          "at": "2026-01-01T00:00:00Z",
          "extractions": [
            {
              "jobId": "",
              "kind": "string",
              "source": "string",
              "engine": "string",
              "modelVersion": "string",
              "confidenceBps": 1,
              "fields": [
                {
                  "field": "string",
                  "value": "string",
                  "confidenceBps": 1,
                  "page": 1
                }
              ],
              "notes": [
                "string"
              ]
            }
          ]
        }
      ],
      "findings": "string"
    }
  }
}
```

### 201

Started.

Content type: `application/json`.

```json
{
  "data": {
    "id": "",
    "state": "awaiting_start",
    "created": true,
    "job": {
      "id": "",
      "status": "started",
      "externalJobId": "",
      "idempotencyKey": "string",
      "requestedBy": "string",
      "requestedAt": "2026-01-01T00:00:00Z",
      "finishedAt": "2026-01-01T00:00:00Z",
      "finished": true,
      "events": [
        {
          "seq": 1,
          "event": "string",
          "at": "2026-01-01T00:00:00Z",
          "detail": {}
        }
      ],
      "documents": [
        {
          "id": "",
          "fileId": "",
          "fileName": "string",
          "documentType": "string",
          "attemptNo": 1,
          "outcome": "pending",
          "reason": "string",
          "contentSha256": "string",
          "at": "2026-01-01T00:00:00Z",
          "extractions": [
            {
              "jobId": "",
              "kind": "string",
              "source": "string",
              "engine": "string",
              "modelVersion": "string",
              "confidenceBps": 1,
              "fields": [
                {
                  "field": "string",
                  "value": "string",
                  "confidenceBps": 1,
                  "page": 1
                }
              ],
              "notes": [
                "string"
              ]
            }
          ]
        }
      ],
      "findings": "string"
    }
  }
}
```

### 400

The job has no documents to process.

Content type: `application/json`.

```json
{
  "error": {
    "message": "string"
  }
}
```

### 401

No key, or an unknown or revoked one.

Content type: `application/json`.

```json
{
  "error": {
    "message": "string"
  }
}
```

### 402

A key issued from Settings → Developer, on a workspace without the Enterprise plan.

Content type: `application/json`.

```json
{
  "error": {
    "message": "string"
  }
}
```

### 403

The key was not given `processing`, or is a board key.

Content type: `application/json`.

```json
{
  "error": {
    "message": "string"
  }
}
```

### 404

No job or deal with that id that this key can reach.

Content type: `application/json`.

```json
{
  "error": {
    "message": "string"
  }
}
```

### 409

`would_supersede`: send `replace: true` to go ahead.

Content type: `application/json`.

```json
{
  "error": {
    "message": "string",
    "code": "would_supersede"
  },
  "superseded": [
    "string"
  ]
}
```
