document.received - OmniAI Docs

Triggered when a document is received.

Event Type

document.received

Description

This event is fired whenever a document is received by the agent, whether via email, SMS, portal upload, or API. Use this event to track document collection and trigger downstream processing.

Payload Structure

event

string

required

The event type: document.received

document

object

required

The received document object

Show document

string

required

Unique identifier for the document

externalId

string

External identifier for the document, if one was provided at creation

filename

string

required

Original filename of the document

leadId

string

required

ID of the lead this document belongs to

externalLeadId

string

required

External ID of the lead this document belongs to, if one was provided at creation

signedUrl

string

required

Pre-signed URL for accessing the document (expires after 1 hour)

size

number

File size in bytes

mimeType

string

MIME type of the document (e.g., application/pdf, image/jpeg)

messageId

string

ID of the message that contained this document (if applicable)

metadata

object

Additional metadata about the document

createdAt

string

ISO 8601 timestamp when the document was created

actor

object | null

Workspace user who uploaded this document. Returns null for documents not uploaded by a workspace user.

Show actor

type

enum

Type of actor

string

Unique identifier for the user

name

string | null

Name of the user

string

Email address of the user

workspaceId

string

required

ID of the workspace this event belongs to

Signed URLs

The signedUrl field provides temporary access to the document. Note that:

URLs expire after 1 hour
Request a new document via the API to get a fresh signed URL
URLs are pre-signed for secure access

Next Steps

After receiving this event, you may want to:

Download and process the document
Wait for the document.extracted event for extraction results
Update your system with the new document information

{
  "event": "document.received",
  "document": {
    "id": "a80e6241-327f-419d-bae1-a4806d1a7641",
    "externalId": "DOC-2025-001",
    "filename": "vital-checking-june-25.pdf",
    "leadId": "50713355-df73-4077-9d84-dcda6da5729c",
    "externalLeadId": "SF-00142",
    "signedUrl": "https://omniai-server-v2-dev.s3.us-east-2.amazonaws.com/...",
    "size": 153143,
    "mimeType": "application/pdf",
    "messageId": "1ae4c028-ae4d-4e6d-aebd-cde96fdd8b3f",
    "metadata": null,
    "createdAt": "2025-10-31T19:00:01.675Z"
  },
  "actor": {
    "type": "USER",
    "id": "8a1f6c2e-4b7d-4e2a-9c3f-1d5e6f7a8b9c",
    "name": "Jane Doe",
    "email": "jane@acme.com"
  },
  "workspaceId": "6048d78a-584a-4f1e-9e39-e011ca4cc48c"
}

​Event Type

​Description

​Payload Structure

​Signed URLs

​Next Steps

Event Type

Description

Payload Structure

Signed URLs

Next Steps