Notification Payloads

HTTP, FTP and SFTP channels receive the payload below as JSON unless a transformer reshapes it. Email channels receive a formatted mail built from the same data.

Structure

{
  "id": "4c1a9c0e-2f1d-4d3e-9a1b-7f0c2e8b5d21",
  "timestamp": "2026-10-25T09:14:03.120Z",
  "team_id": "team_123456",
  "project_id": "proj_123456",
  "step_id": "step_abc123",
  "event": "TASK_DISCARDED",
  "event_level": "TASK",
  "upload": { "...": "see Upload object" },
  "task": { "...": "see Task object, null for upload events" },
  "issue": { "...": "see Issue object, null unless reported or discarded" },
  "duplicate_of_upload_id": null
}

Field	Type	Description
id	String	Unique id of this notification. Use it to deduplicate.
timestamp	String	ISO 8601 time the notification was created.
team_id	String	Team that owns the project.
project_id	String	Project in which the event occurred.
step_id	String or null	Pipeline step of the task. null for upload events.
event	String	One of the events listed in Notification Events.
event_level	String	UPLOAD or TASK.
upload	Object	The upload. Always present.
task	Object or null	The task. Present for task events, null for upload events.
issue	Object or null	Reviewer message and issues. Present for TASK_REPORTED and TASK_DISCARDED, otherwise null.
duplicate_of_upload_id	String or null	Id of the earlier upload. Present for UPLOAD_DUPLICATE_DETECTED, otherwise null.

Upload object

{
  "id": "upl_abcdef123456",
  "name": "invoice.pdf",
  "status": "IN_REVIEW",
  "warning_type": null,
  "meta": [{ "name": "reference", "value": "INV-2026-001" }],
  "folder_id": "folder_123456",
  "created_at": "2026-10-25T09:12:40.000Z",
  "processed_at": null,
  "export_failed_at": null,
  "files": [
    {
      "id": "file_123",
      "name": "invoice.pdf",
      "content_type": "application/pdf",
      "base64": null
    }
  ]
}

Field	Type	Description
id	String	Upload id.
name	String	Upload name, usually the file name or mail subject.
status	String	PROCESSING, IN_REVIEW or COMPLETED.
warning_type	String or null	POTENTIAL_DUPLICATE_UPLOAD, ALL_ATTACHMENTS_FILTERED or null.
meta	Array	Metadata name/value pairs given at upload time.
folder_id	String	Folder the upload currently sits in.
created_at	String	When the upload was created.
processed_at	String or null	When the upload completed. null until then.
export_failed_at	String or null	When the last export attempt failed. null when the export succeeded or has not run.
files	Array	Files in the upload with id, name and content_type. base64 is null in notifications.

Task object

{
  "id": "tsk_123456",
  "name": "invoice.pdf",
  "created_at": "2026-10-25T09:12:41.000Z",
  "meta": [{ "name": "reference", "value": "INV-2026-001" }],
  "status": "DISCARDED",
  "step_type": "EXTRACT",
  "upload_id": "upl_abcdef123456",
  "project_id": "proj_123456",
  "approved": false,
  "failure_reason": null,
  "soft_fail_reason": null,
  "filter_verdict": "keep",
  "filter_score": 0.97,
  "exported_at": null,
  "export_failed_at": null,
  "last_opened_at": "2026-10-25T09:13:55.000Z"
}

Field	Type	Description
id	String	Task id.
name	String	Task name.
created_at	String	When the task was created.
meta	Array	Metadata inherited from the upload.
status	String	PROCESSING, REVIEWING, COMPLETED, FAILED, DISCARDED, FILTERED or UNPROCESSABLE.
step_type	String	Step type: GROUP, SEGMENT, CLASSIFY or EXTRACT.
upload_id	String	Upload the task belongs to.
project_id	String	Project id.
approved	Boolean	Whether a reviewer approved the task.
failure_reason	String or null	PARSING_FAILED, TIMED_OUT or UNKNOWN when status is FAILED.
soft_fail_reason	String or null	The recoverable error that sent the task to review, for example VALIDATION_FAILED or PREDICTING_ENTITIES_ERROR.
filter_verdict	String or null	keep or filter once the filter model has judged the task.
filter_score	Number or null	The filter model's score for keeping the task.
exported_at	String or null	When the task was exported.
export_failed_at	String or null	When the task's export last failed.
last_opened_at	String or null	When a reviewer last opened the task.

The notification task object does not include page contents or extracted values. Use the Tasks API with task.id to fetch them.

Issue object

Sent with TASK_REPORTED and TASK_DISCARDED. Both carry the reviewer's free-text message and the issues they ticked.

{
  "message": "Totals do not add up, please check page 2.",
  "issues": [{ "label": "Wrong value", "value": "total_amount" }],
  "reported_by": "user_123456"
}

Field	Type	Description
message	String or null	The reviewer's message. Can be empty.
issues	Array	Ticked issues as label / value pairs. Can be empty.
reported_by	String	Id of the user who reported or discarded.

Example: upload processed

{
  "id": "0b7e3f2a-6c7d-4a1e-8f3b-2d9c1e4a5b60",
  "timestamp": "2026-10-25T09:20:11.000Z",
  "team_id": "team_123456",
  "project_id": "proj_123456",
  "step_id": null,
  "event": "UPLOAD_PROCESSED",
  "event_level": "UPLOAD",
  "upload": {
    "id": "upl_abcdef123456",
    "name": "invoice.pdf",
    "status": "COMPLETED",
    "warning_type": null,
    "meta": [],
    "folder_id": "folder_processed",
    "created_at": "2026-10-25T09:12:40.000Z",
    "processed_at": "2026-10-25T09:20:10.000Z",
    "export_failed_at": null,
    "files": [{ "id": "file_123", "name": "invoice.pdf", "content_type": "application/pdf", "base64": null }]
  },
  "task": null,
  "issue": null,
  "duplicate_of_upload_id": null
}

Handling notifications

• Branch on event, not on upload.status or task.status: statuses describe the current state, events describe what just happened.
• Treat id as an idempotency key.
• Respond with a 2xx status quickly and do the work afterwards. A rejected or slow response is logged as a failed delivery and is not retried.