> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getomni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Spread

> Start a financial spreading run for a lead

Start a financial spreading run for a lead. Omni classifies and extracts the lead's PDF financial documents (tax returns, income statements, balance sheets), consolidates them onto a standardized multi-period template, and produces a report and an Excel workbook. The run happens in the background and takes a few minutes; this endpoint returns immediately with the new run's id. Track it with [Get Spread](/api-reference/spreads/get-spread) or the [spread webhooks](/api-reference/webhooks/webhook-events).

## Authentication

Requires the `x-api-key` header with a valid workspace API key.

## Request Body

<ParamField body="leadId" type="string" required>
  The lead whose documents to spread.
</ParamField>

<ParamField body="documentIds" type="string[]" required={false}>
  Spread only these documents, a subset of the lead's documents. Every id must
  resolve to a document on the lead. Omit to spread all of the lead's PDF
  documents.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="spread" type="object">
  The created run, in the same shape as
  [Get Spread](/api-reference/spreads/get-spread). `status` is always
  `IN_PROGRESS`, and `artifacts` is empty until the run completes.
</ResponseField>

## Errors

<ResponseField name="400" type="error">
  No `leadId`; a `documentIds` value doesn't resolve to a document on the lead;
  or the resolved documents contain no PDFs.
</ResponseField>

<ResponseField name="404" type="error">
  The `leadId` isn't a lead in your workspace.
</ResponseField>

<ResponseField name="409" type="error">
  The lead already has a spread `IN_PROGRESS`. Wait for it to reach
  `COMPLETE` or `FAILED` before starting another.
</ResponseField>

<RequestExample>
  ```javascript Node.js theme={null}
  const options = {
    method: "POST",
    headers: {
      "x-api-key": "<your-api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      leadId: "b1f0a790-201b-47e9-84ed-cc7eed1270c5",
    }),
  };

  fetch("https://api-v2.getomni.ai/api/v1/spreads", options)
    .then((response) => response.json())
    .then((response) => console.log(response))
    .catch((err) => console.error(err));
  ```

  ```python Python theme={null}
  import requests

  url = "https://api-v2.getomni.ai/api/v1/spreads"
  headers = {
      "x-api-key": "<your-api-key>",
      "Content-Type": "application/json",
  }
  payload = {"leadId": "b1f0a790-201b-47e9-84ed-cc7eed1270c5"}

  response = requests.request("POST", url, headers=headers, json=payload)
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api-v2.getomni.ai/api/v1/spreads \
    --header 'x-api-key: <your-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "leadId": "b1f0a790-201b-47e9-84ed-cc7eed1270c5"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "spread": {
      "id": "9f1e2d3c-4b5a-6789-0abc-def012345678",
      "status": "IN_PROGRESS",
      "error": null,
      "leadId": "b1f0a790-201b-47e9-84ed-cc7eed1270c5",
      "documents": [
        {
          "id": "doc-a",
          "filename": "2023-tax-return.pdf",
          "status": "PROCESSING",
          "error": null
        },
        {
          "id": "doc-b",
          "filename": "2023-financials.pdf",
          "status": "PROCESSING",
          "error": null
        }
      ],
      "artifacts": [],
      "createdAt": "2026-07-23T18:04:00.000Z",
      "updatedAt": "2026-07-23T18:04:00.000Z"
    }
  }
  ```
</ResponseExample>