Upload Documents

const formData = new FormData();
formData.append("leadId", "a9d0a790-201b-47e9-84ed-cc7eed1270c5");
formData.append("files", file1); // File or Blob
formData.append("files", file2);
// Optional: formData.append('leadChecklistItemId', '<lead-checklist-item-id>');
// Optional: per-file metadata (must match the number of files)
formData.append(
  "metadata",
  JSON.stringify([
    { externalId: "doc-1", name: "document.pdf" },
    { externalId: "doc-2", name: "statement.xlsx" },
  ]),
);

const response = await fetch("https://api-v2.getomni.ai/api/v1/documents", {
  method: "POST",
  headers: {
    "x-api-key": "<your-api-key>",
  },
  body: formData,
});
const data = await response.json();
console.log(data);

import requests

import json

url = "https://api-v2.getomni.ai/api/v1/documents"
headers = {"x-api-key": "<your-api-key>"}
data = {
    "leadId": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    # Optional: per-file metadata (must match the number of files)
    "metadata": json.dumps([
        {"externalId": "doc-1", "name": "document.pdf"},
        {"externalId": "doc-2", "name": "statement.xlsx"},
    ]),
}
# Optional: data["leadChecklistItemId"] = "<lead-checklist-item-id>"
files = [
    ("files", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ("files", ("statement.xlsx", open("statement.xlsx", "rb"), "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")),
]
response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())

curl --request POST \
  --url 'https://api-v2.getomni.ai/api/v1/documents' \
  --header 'x-api-key: <your-api-key>' \
  --form 'leadId=a9d0a790-201b-47e9-84ed-cc7eed1270c5' \
  --form 'files=@/path/to/document.pdf' \
  --form 'files=@/path/to/statement.xlsx' \
  --form 'metadata=[{"externalId":"doc-1","name":"document.pdf"},{"externalId":"doc-2","name":"statement.xlsx"}]'
# Optional: --form 'leadChecklistItemId=<lead-checklist-item-id>'

{
  "success": true,
  "documents": [
    {
      "id": "b1e2c3d4-5f6a-7890-bcde-f12345678901",
      "externalId": "doc-1",
      "filename": "document.pdf",
      "size": 102400,
      "url": "https://...",
      "mimeType": "application/pdf",
      "uploadedAt": "2026-01-30T02:00:00.000Z",
      "associatedChecklistItemId": null
    },
    {
      "id": "c2d3e4f5-6a7b-8901-cdef-23456789012a",
      "externalId": "doc-2",
      "filename": "statement.xlsx",
      "size": 204800,
      "url": "https://...",
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "uploadedAt": "2026-01-30T02:00:00.000Z",
      "associatedChecklistItemId": null
    }
  ],
  "actionLogId": "7de43760-d12d-4bcc-931a-f728ef1a3e3b"
}

POST

api

documents

const formData = new FormData();
formData.append("leadId", "a9d0a790-201b-47e9-84ed-cc7eed1270c5");
formData.append("files", file1); // File or Blob
formData.append("files", file2);
// Optional: formData.append('leadChecklistItemId', '<lead-checklist-item-id>');
// Optional: per-file metadata (must match the number of files)
formData.append(
  "metadata",
  JSON.stringify([
    { externalId: "doc-1", name: "document.pdf" },
    { externalId: "doc-2", name: "statement.xlsx" },
  ]),
);

const response = await fetch("https://api-v2.getomni.ai/api/v1/documents", {
  method: "POST",
  headers: {
    "x-api-key": "<your-api-key>",
  },
  body: formData,
});
const data = await response.json();
console.log(data);

import requests

import json

url = "https://api-v2.getomni.ai/api/v1/documents"
headers = {"x-api-key": "<your-api-key>"}
data = {
    "leadId": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    # Optional: per-file metadata (must match the number of files)
    "metadata": json.dumps([
        {"externalId": "doc-1", "name": "document.pdf"},
        {"externalId": "doc-2", "name": "statement.xlsx"},
    ]),
}
# Optional: data["leadChecklistItemId"] = "<lead-checklist-item-id>"
files = [
    ("files", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ("files", ("statement.xlsx", open("statement.xlsx", "rb"), "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")),
]
response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())

curl --request POST \
  --url 'https://api-v2.getomni.ai/api/v1/documents' \
  --header 'x-api-key: <your-api-key>' \
  --form 'leadId=a9d0a790-201b-47e9-84ed-cc7eed1270c5' \
  --form 'files=@/path/to/document.pdf' \
  --form 'files=@/path/to/statement.xlsx' \
  --form 'metadata=[{"externalId":"doc-1","name":"document.pdf"},{"externalId":"doc-2","name":"statement.xlsx"}]'
# Optional: --form 'leadChecklistItemId=<lead-checklist-item-id>'

{
  "success": true,
  "documents": [
    {
      "id": "b1e2c3d4-5f6a-7890-bcde-f12345678901",
      "externalId": "doc-1",
      "filename": "document.pdf",
      "size": 102400,
      "url": "https://...",
      "mimeType": "application/pdf",
      "uploadedAt": "2026-01-30T02:00:00.000Z",
      "associatedChecklistItemId": null
    },
    {
      "id": "c2d3e4f5-6a7b-8901-cdef-23456789012a",
      "externalId": "doc-2",
      "filename": "statement.xlsx",
      "size": 204800,
      "url": "https://...",
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "uploadedAt": "2026-01-30T02:00:00.000Z",
      "associatedChecklistItemId": null
    }
  ],
  "actionLogId": "7de43760-d12d-4bcc-931a-f728ef1a3e3b"
}

This endpoint uploads documents for a lead. Behavior matches the in-app Document Vault: files are stored in S3, a SYSTEM_NOTE and DOCUMENT_UPLOAD action log are created, documents are saved to Mastra memory, and the document workflow runs (validation, extraction, etc.). You can optionally associate uploads with a checklist item via leadChecklistItemId. Maximum 10 files per request; each file up to 100MB.

Authentication

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

Request Body (multipart/form-data)

string

required

The Omni lead ID. The lead must exist and belong to your workspace.

file

required

One or more files to upload. Use the form field name files. Up to 10 files; each file up to 100MB.

string

Optional. Omni lead checklist item ID to associate the uploaded documents with. The item must belong to the lead.

object[]

Optional. Per-file metadata, index-aligned with files. When provided, its length must match the number of files. With multipart/form-data, send as a JSON-stringified form field.Each entry supports:

externalId (string, optional): your own identifier to persist on the document. Returned on the response.
name (string, optional): overrides the uploaded filename.

Response

boolean

Whether the request succeeded

array

Array of uploaded document objects: id, externalId, filename, size, url (presigned), mimeType, uploadedAt, associatedChecklistItemId.

string

The ID of the DOCUMENT_UPLOAD action log entry for this upload

const formData = new FormData();
formData.append("leadId", "a9d0a790-201b-47e9-84ed-cc7eed1270c5");
formData.append("files", file1); // File or Blob
formData.append("files", file2);
// Optional: formData.append('leadChecklistItemId', '<lead-checklist-item-id>');
// Optional: per-file metadata (must match the number of files)
formData.append(
  "metadata",
  JSON.stringify([
    { externalId: "doc-1", name: "document.pdf" },
    { externalId: "doc-2", name: "statement.xlsx" },
  ]),
);

const response = await fetch("https://api-v2.getomni.ai/api/v1/documents", {
  method: "POST",
  headers: {
    "x-api-key": "<your-api-key>",
  },
  body: formData,
});
const data = await response.json();
console.log(data);

import requests

import json

url = "https://api-v2.getomni.ai/api/v1/documents"
headers = {"x-api-key": "<your-api-key>"}
data = {
    "leadId": "a9d0a790-201b-47e9-84ed-cc7eed1270c5",
    # Optional: per-file metadata (must match the number of files)
    "metadata": json.dumps([
        {"externalId": "doc-1", "name": "document.pdf"},
        {"externalId": "doc-2", "name": "statement.xlsx"},
    ]),
}
# Optional: data["leadChecklistItemId"] = "<lead-checklist-item-id>"
files = [
    ("files", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ("files", ("statement.xlsx", open("statement.xlsx", "rb"), "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")),
]
response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())

curl --request POST \
  --url 'https://api-v2.getomni.ai/api/v1/documents' \
  --header 'x-api-key: <your-api-key>' \
  --form 'leadId=a9d0a790-201b-47e9-84ed-cc7eed1270c5' \
  --form 'files=@/path/to/document.pdf' \
  --form 'files=@/path/to/statement.xlsx' \
  --form 'metadata=[{"externalId":"doc-1","name":"document.pdf"},{"externalId":"doc-2","name":"statement.xlsx"}]'
# Optional: --form 'leadChecklistItemId=<lead-checklist-item-id>'

{
  "success": true,
  "documents": [
    {
      "id": "b1e2c3d4-5f6a-7890-bcde-f12345678901",
      "externalId": "doc-1",
      "filename": "document.pdf",
      "size": 102400,
      "url": "https://...",
      "mimeType": "application/pdf",
      "uploadedAt": "2026-01-30T02:00:00.000Z",
      "associatedChecklistItemId": null
    },
    {
      "id": "c2d3e4f5-6a7b-8901-cdef-23456789012a",
      "externalId": "doc-2",
      "filename": "statement.xlsx",
      "size": 204800,
      "url": "https://...",
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "uploadedAt": "2026-01-30T02:00:00.000Z",
      "associatedChecklistItemId": null
    }
  ],
  "actionLogId": "7de43760-d12d-4bcc-931a-f728ef1a3e3b"
}

Get Document Create Spread

Getting Started

Leads

Documents

Spreads

Artifacts

Analytics

Webhooks

Authentication

Request Body (multipart/form-data)

Response

​Authentication

​Request Body (multipart/form-data)

​Response

Authentication

Request Body (multipart/form-data)

Response