> ## 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.

# document.received

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

<ResponseField name="event" type="string" required>
  The event type: `document.received`
</ResponseField>

<ResponseField name="document" type="object" required>
  The received document object

  <Expandable title="document">
    <ResponseField name="id" type="string" required>
      Unique identifier for the document
    </ResponseField>

    <ResponseField name="externalId" type="string" nullable>
      External identifier for the document, if one was provided at creation
    </ResponseField>

    <ResponseField name="filename" type="string" required>
      Original filename of the document
    </ResponseField>

    <ResponseField name="leadId" type="string" required>
      ID of the lead this document belongs to
    </ResponseField>

    <ResponseField name="externalLeadId" type="string" required>
      External ID of the lead this document belongs to, if one was provided at creation
    </ResponseField>

    <ResponseField name="signedUrl" type="string" required>
      Pre-signed URL for accessing the document (expires after 1 hour)
    </ResponseField>

    <ResponseField name="size" type="number">
      File size in bytes
    </ResponseField>

    <ResponseField name="mimeType" type="string">
      MIME type of the document (e.g., `application/pdf`, `image/jpeg`)
    </ResponseField>

    <ResponseField name="messageId" type="string" nullable>
      ID of the message that contained this document (if applicable)
    </ResponseField>

    <ResponseField name="metadata" type="object" nullable>
      Additional metadata about the document
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when the document was created
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="workspaceId" type="string" required>
  ID of the workspace this event belongs to
</ResponseField>

## 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

<ResponseExample>
  ```json theme={null}
  {
    "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"
    },
    "workspaceId": "6048d78a-584a-4f1e-9e39-e011ca4cc48c"
  }
  ```
</ResponseExample>