365 business PDF

Document Attachment API

Document attachments are the PDF documents the app places before or after a printed sales or purchase document. A user maintains them on the document itself; an application outside Business Central maintains them through the API page 5523591 bdev.Add Document Attachment.

The typical case is a document that lives elsewhere - a certificate from a quality management system, a data sheet from a PIM - and is to be printed together with the order confirmation without ever being stored in Business Central. The API registers the URL of the document; the app fetches it when the report is printed.

Endpoint

Code
{BaseUrl}/api/businessdev/addDocumentAttachment/v1.0/companies({companyId})/documentAttachments

Segment	Description
`{BaseUrl}`	The URL of the Business Central environment, for example `https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}`.
`{companyId}`	The `id` of the company, as returned by the `companies` endpoint.

The entity supports the usual OData verbs: GET to read, POST to create, PATCH to change, DELETE to remove an attachment.

Entity

Property	Type	Description
`id`	GUID	The `SystemId` of the entry and the OData key. Assigned on insert; use it to address an existing entry.
`type`	Integer	The table id of the document the attachment belongs to - `36` for `Sales Header`, `38` for `Purchase Header`.
`documentType`	Integer	The `Document Type` of that document as an integer - `0` Quote, `1` Order, `2` Invoice, `3` Credit Memo, `4` Blanket Order, `5` Return Order.
`documentNo`	Code[20]	The `No.` of the document.
`url`	Text[250]	The address of the PDF document. Must start with `http://` or `https://`.

The entity does not expose the Type and Rotation fields of bdev.Document Attachment, nor the Position No.. A new entry is appended behind the existing attachments of the document.

Version

The Type is derived from the content as of 20.6: an entry carrying a URL is typed as URL on insert. Up to and including 20.5 an entry created through the API stayed untyped and contributed nothing to the printed document - on those versions, set Type to URL on the Document Attachments page of the document afterwards.

Example

Code
POST {BaseUrl}/api/businessdev/addDocumentAttachment/v1.0/companies(9ee48135-93e1-ef11-9344-6045bde9ca09)/documentAttachments
Content-Type: application/json

Code
{
    "type": 36,
    "documentType": 1,
    "documentNo": "101005",
    "url": "https://example.com/datasheet.pdf"
}

The attachment is printed with sales order 101005 from then on, after the document itself - the printed document is appended at the end unless an entry of the type Document states another position among the attachments.

What happens when the document is printed

The app collects the attachments of the record being printed, fetches the URL entries over HTTP, and merges everything into one PDF. Two things are worth knowing:

A URL that cannot be fetched does not stop the print. The user receives a notification naming the URL, and the document is printed without that attachment.
Attachments are only added on a single print. When a user prints a batch of documents, the attachments of all of them are skipped.

Document Attachment API

Endpoint

Entity

Example

What happens when the document is printed

See also