import { Callout } from "zudoku/ui/Callout";

# 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

```
{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.

<Callout type="caution" title="The type has to be set in the client as of 20.5">
An attachment is only fetched during printing when its `Type` is `URL`, and the API page does not set it - an entry created through the API is left with a blank type and contributes nothing to the printed document. Until the API sets the type, open the **Document Attachments** page of the sales or purchase document and set `Type` to `URL` on the entry the API created.
</Callout>

## Example

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

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

Once the type of the entry is `URL`, the attachment is printed with sales order `101005`, 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.

## See also

- [365 business PDF - Overview](readme.mdx)
- [Extensibility Events](extensibility-events.mdx)
- [Documentation - Document Attachments](../../en-us/365-business-pdf/document-attachments.md)