A nice feature which is explained fairly well in the Microsoft docs site but it is especially nice to have a working example. (https://docs.microsoft.com/en-us/dynamics-nav/api-reference/v1.0/api/dynamics_attachment_patch). The attachments API itself actually points to the “Incoming Documents” feature of BC, so terminology might catch you out. The scope of the API therefore covers whatever you can use “Incoming Document” for: Purchase Invoice/Credit, Sales Invoice/Credit and Journal lines.

You need to use to HTTP calls to make this one work and this is the pattern:

Firstly you POST a simple line to say what you are attaching to i.e. our Invoice/Credit record or our journal line. This must be the ID or SystemID value of that record. How this plays out in a practical sense will depend on how you implement the API with your solution. In the scenario where you create a purchase invoice and then have an attachment of that latched against it you will need to perform the creation of the purchase invoice record first – a follow up post on this. Here is how the first action looks:



{    “parentId”: “5a086bc7-195f-eb11-89f9-0022481ab2d5”,    “fileName”: “Example.pdf”}

How it looks in a HTTP client like Postman. Note that the “filename” property is just a value you choose. So if this was part of a solution you might do it as the invoice number or document no. of the journal line you created before this step

Now the PATCH part is where the order of this becomes very important. You need a value from the POST to do the PATCH…..😮

This is the response I get from doing the POST command. It is the ID value which is new to the story and is how I perform the actual attachment process. POST is just to create the Incoming Document record….penny drops 🙈

Once the above is known then the PATCH command shown in Microsoft Docs becomes very easy to follow. Here is the command: PATCH businesscentralPrefix/companies({companyId})/attachments(parentId={parentId},id={attachmentId})/content . Simply add the information we now know. So in my case, with the above screenshot, my “parentID” is 5a086bc7-195f-eb11-89f9-0022481ab2d5 and my “id” is 7a1f7c6c-1e5f-eb11-89f9-0022481ab2d5. Notice that the odata.etag has been provided from the previous POST step so you can add that in as well for the “Headers” of the PATCH command. Here is what I mean:

etag is there to track the changes – make sure someone else hasn’t modified the record since you last got it. It is possible to use a wildcard here if needs must

In postman at least the body of the PATCH command is something like below but in a real solution you just need to make sure you pass a binary file:

In postman if you are testing this you can select a file to work with and it will pop open your file explorer.

Once each of the mentioned are in place you can go ahead with the PATCH. You should get a 204 status response but there will be no body type output.

When you head over to BC though you will see your record, which started life as our ID no has an “Incoming Document” record against it.
Here is the record in the Incoming Documents table. Once posted a user will be able to view document as well.

3 thoughts on “Business Central Attachments with standard API – Part 1 Basic Explanation

  1. Hi, I’ve try your process but at PATCH step I get an error:
    “The input is not a valid Base-64 string as it contains a non-base 64 character, more than two padding characters, or an illegal character among the padding characters. CorrelationId: 5b6067f5-1691-46ed-bd99-f58dd3d489c9.”

    Do you guess why ?


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s