Incoming Document Message Types

Parent Document: API_Reference.md Implementation Folder: app/src/Message Type/Implementations/IncomingDocument/

Overview

This document describes the Incoming Document message types in the Cloud Events API. These message types cover the full lifecycle of an Incoming Document in Business Central — from receiving a file, through optional additional attachments, processing into a purchase or journal document, to querying the document and its attachments.

Typical workflow:

1. Call Incoming.Document.Create to upload the main file and create the Incoming Document.
2. Optionally call Incoming.Document.Attach one or more times to add supplemental files.
3. Call Incoming.Document.Process to create a purchase invoice or journal entry from the document.
4. Call Incoming.Document.Get at any point to retrieve the current document state and all attachments.
5. Call Incoming.Document.SetDefault to change which attachment is the main (default) attachment.

Incoming.Document.Create

Direction: Inbound Object IDs: Codeunit 65419 (IncomingDoc Create Impl), Codeunit 65423 (IncomingDoc Create Help)

Purpose

Creates a new Incoming Document in Business Central with a main attachment. The file content must be provided as a Base64-encoded string together with the file name.

Request Format

{
  "specversion": "1.0",
  "type": "Incoming.Document.Create",
  "source": "MyApp v1.0",
  "data": "{\"fileName\":\"invoice.pdf\",\"fileContent\":\"<base64-encoded content>\"}"
}

Request Fields

Response Format

{
  "status": "Success",
  "entryNo": 1001,
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "lineNo": 10000,
  "description": "Purchase from Fabrikam",
  "documentDate": "2026-04-01",
  "dueDate": "",
  "vendorNo": "V10000",
  "vendorName": "Fabrikam Inc.",
  "documentStatus": "New",
  "dataExchangeType": "",
  "processed": false,
  "posted": false,
  "record": {},
  "error": []
}

Response Fields

Error Scenarios

Incoming.Document.Attach

Direction: Inbound Object IDs: Codeunit 65422 (IncomingDoc Attach Impl), Codeunit 65426 (IncomingDoc Attach Help)

Purpose

Adds a supplemental attachment to an existing Incoming Document. The target document is identified by its Entry No. or SystemId in the subject field. The file content must be provided as a Base64-encoded string.

Request Format

{
  "specversion": "1.0",
  "type": "Incoming.Document.Attach",
  "source": "MyApp v1.0",
  "subject": "1001",
  "data": "{\"fileName\":\"delivery-note.xml\",\"fileContent\":\"<base64-encoded content>\"}"
}

Or by SystemId:

{
  "subject": "{a1b2c3d4-e5f6-7890-abcd-ef1234567890}",
  "data": "{\"fileName\":\"delivery-note.xml\",\"fileContent\":\"<base64-encoded content>\"}"
}

Request Fields

Response Format

{
  "status": "Success",
  "entryNo": 1001,
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "lineNo": 20000,
  "description": "Purchase from Fabrikam",
  "documentDate": "2026-04-01",
  "dueDate": "2026-04-30",
  "vendorNo": "V10000",
  "vendorName": "Fabrikam Inc.",
  "documentStatus": "New",
  "dataExchangeType": "",
  "processed": false,
  "posted": false,
  "record": {},
  "error": []
}

Response Fields

Error Scenarios

Incoming.Document.Process

Direction: Inbound Object IDs: Codeunit 65425 (IncomingDoc Process Impl), Codeunit 65429 (IncomingDoc Process Help)

Purpose

Processes an Incoming Document using the standard Business Central OCR/document processing flow, which attempts to create a purchase invoice or a journal line from the document.

Request Format

{
  "specversion": "1.0",
  "type": "Incoming.Document.Process",
  "source": "MyApp v1.0",
  "subject": "1001"
}

Or by SystemId:

{
  "subject": "{a1b2c3d4-e5f6-7890-abcd-ef1234567890}"
}

Response Format

{
  "status": "Success",
  "record": {
    "tableNo": 38,
    "tableName": "Purchase Header",
    "tableCaption": "Purchase Header",
    "recordSystemId": "c3d4e5f6-a1b2-7890-abcd-ef1234567890"
  },
  "entryNo": 1001,
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

On failure, a "status": "Error" response is returned with an "error" array containing the BC error messages that prevented the document from reaching Status = Created.

Response Fields

record Object Fields

Error Message Object Fields

Each object in the error array has the following fields:

Error Scenarios

Incoming.Document.Get

Direction: Outbound Object IDs: Codeunit 65431 (IncomingDoc Get Impl), Codeunit 65430 (IncomingDoc Get Help)

Purpose

Retrieves header information and all file attachments for an existing Incoming Document. Attachments are grouped into a mainAttachment object and an additionalAttachments array. File content is returned as Base64-encoded strings.

Request Format

{
  "specversion": "1.0",
  "type": "Incoming.Document.Get",
  "source": "MyApp v1.0",
  "subject": "1001"
}

Or by SystemId:

{
  "subject": "{a1b2c3d4-e5f6-7890-abcd-ef1234567890}"
}

The subject field accepts either:

• An Entry No. (integer as text, e.g. "1001")
• A SystemId GUID (with or without braces)

Response Format

{
  "status": "Success",
  "entryNo": 1001,
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "description": "Purchase from Fabrikam",
  "documentDate": "2026-04-01",
  "dueDate": "2026-04-30",
  "vendorNo": "V10000",
  "vendorName": "Fabrikam Inc.",
  "documentStatus": "New",
  "dataExchangeType": "",
  "processed": false,
  "posted": false,
  "record": {
    "tableNo": 38,
    "tableName": "Purchase Header",
    "tableCaption": "Purchase Header",
    "recordSystemId": "c3d4e5f6-a1b2-7890-abcd-ef1234567890"
  },
  "error": [],
  "mainAttachment": {
    "lineNo": 10000,
    "fileName": "invoice.pdf",
    "fileContent": "<base64-encoded file content>"
  },
  "additionalAttachments": [
    {
      "lineNo": 20000,
      "fileName": "delivery-note.xml",
      "fileContent": "<base64-encoded file content>"
    }
  ]
}

Header Response Fields

record Object Fields

Attachment Fields (mainAttachment and additionalAttachments entries)

Notes

• The mainAttachment object is omitted from the response if the Incoming Document has no main attachment.
• The additionalAttachments array is empty ([]) if there are no additional attachments.
• The record object contains table metadata for the linked BC document (e.g. Purchase Header) when one exists. It is an empty object when no document is linked.
• The error array contains BC error messages saved against the Incoming Document. It is an empty array when no errors exist.
• File content is always Base64-encoded; the caller must decode before use.

Error Scenarios

Incoming.Document.SetDefault

Direction: Inbound Object IDs: Codeunit 65432 (IncomingDoc SetDef Impl), Codeunit 65433 (IncomingDoc SetDef Exec), Codeunit 65434 (IncomingDoc SetDef Help)

Purpose

Sets the default (main) attachment on an existing Incoming Document. The specified attachment is deleted and re-inserted as the first attachment (Line No. 10000) with the Main Attachment flag set to true. All other attachments are re-inserted after it in their original relative order.

Request Format

{
  "specversion": "1.0",
  "type": "Incoming.Document.SetDefault",
  "source": "MyApp v1.0",
  "subject": "1001",
  "data": "{\"lineNo\": 20000}"
}

Or by SystemId:

{
  "subject": "{a1b2c3d4-e5f6-7890-abcd-ef1234567890}",
  "data": "{\"lineNo\": 20000}"
}

Request Fields

Response Format

{
  "status": "Success",
  "entryNo": 1001,
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response Fields

Notes

• The Incoming Document must have at least 2 attachments. If fewer than 2 exist, an error is returned.
• All attachments are deleted and re-inserted: the specified attachment becomes Line No. 10000 (main), the rest follow at 20000, 30000, etc.
• File content (BLOB data) is preserved during the re-ordering.
• The original relative order of the non-default attachments is maintained.

Error Scenarios

© Origo – Cloud Events Base Extension