Skip to main content
POST
/
api
/
v1
/
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);

{
  "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)

​
leadId
string
required
The Omni lead ID. The lead must exist and belong to your workspace.
​
files
file
required
One or more files to upload. Use the form field name files. Up to 10 files; each file up to 100MB.
​
leadChecklistItemId
string
Optional. Omni lead checklist item ID to associate the uploaded documents with. The item must belong to the lead.
​
metadata
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

​
success
boolean
Whether the request succeeded
​
documents
array
Array of uploaded document objects: id, externalId, filename, size, url (presigned), mimeType, uploadedAt, associatedChecklistItemId.
​
actionLogId
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);

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