Document Split Event

The DOCUMENT_SPLIT event fires when a splitter finishes. It carries every segment the splitter produced, including the file id of each one, so you can follow the children downstream without polling.

When It Triggers

When a split run reaches COMPLETED. A split that produced no usable segments still fires this event with segmentCount of 0 -- it completed, it just found nothing to keep.

This is a splitter event, routed to subscriptions by splitter route.

Payload Structure

Response200

{
  "eventId": "evt_split_201",
  "eventType": "DOCUMENT_SPLIT",
  "timestamp": "2024-01-15T10:35:02Z",
  "organizationId": "org_xyz789",
  "projectId": "proj_abc123",
  "splitterId": "spl_123abc",
  "splitId": "split_456def",
  "fileId": "file_789ghi",
  "data": {
    "status": "completed",
    "sourcePageCount": 4,
    "segmentCount": 2,
    "segments": [
      {
        "segmentIndex": 0,
        "pageStart": 1,
        "pageEnd": 2,
        "detectedType": "COMMERCIAL_INVOICE",
        "confidence": 0.9,
        "outputFileId": "file_child_1",
        "outputType": "FILE",
        "discarded": false
      },
      {
        "segmentIndex": 1,
        "pageStart": 3,
        "pageEnd": 4,
        "detectedType": "DELIVERY_NOTE",
        "confidence": 0.85,
        "outputFileId": "file_child_2",
        "outputType": "UNCLASSIFIED_FILE",
        "discarded": false
      }
    ]
  }
}

Payload Fields

Field	Type	Description
`eventId`	string	Unique event identifier. Use for idempotency.
`eventType`	string	Always `"DOCUMENT_SPLIT"`
`timestamp`	ISO 8601	When the split completed (UTC)
`organizationId`	string	Your organization identifier
`projectId`	string	The project the splitter belongs to
`splitterId`	string	The splitter that ran
`splitId`	string	This split run
`fileId`	string	The source file that was split
`data.status`	`"completed"`	Always `"completed"` for this event
`data.sourcePageCount`	number \| null	Pages in the source document
`data.segmentCount`	number	Segments kept (discarded segments are not counted)
`data.segments`	array	Every segment, including discarded ones

Segment fields

Field	Type	Description
`segmentIndex`	number	Position in the source document, from `0`
`pageStart`	number	First page of the segment, 1-based and inclusive
`pageEnd`	number	Last page of the segment, inclusive
`detectedType`	string \| null	What the splitter thinks the segment is
`confidence`	number	How confident it is, 0--1
`outputFileId`	string \| null	The file created for this segment. `null` when the segment was discarded.
`outputType`	`"FILE"` \| `"UNCLASSIFIED_FILE"`	`UNCLASSIFIED_FILE` means the segment went on to a classifier; `FILE` means it went straight to a deployment.
`discarded`	boolean	Whether the splitter dropped this segment

Following the children

fileId at the top level is the source document. The children are data.segments[].outputFileId.

A segment whose outputType is UNCLASSIFIED_FILE is handed to a classifier next -- its outputFileId is the same id you will see on the resulting DOCUMENT_CLASSIFIED event, so you can join the two without any extra lookup.

Handling the Event

function handleDocumentSplit(event) {
const { fileId, data } = event

console.log(`${fileId} split into ${data.segmentCount} segments`)

for (const segment of data.segments) {
  if (segment.discarded) continue
  trackChild(segment.outputFileId, {
    parentFileId: fileId,
    pages: [segment.pageStart, segment.pageEnd],
    detectedType: segment.detectedType,
  })
}
}