What content type to use when calling the API?

The Content-Type header in an HTTP request is used to indicate the media type or MIME (Multipurpose Internet Mail Extensions) type of the resource being sent in the body of the request. It tells the server what kind of data is being sent in the request payload, so that the server can process it appropriately. Two commonly used values are:

• application/json: Used for JSON data
• multipart/form-data: Used for sending binary data or files in a form

The necessity to specify the Content-Type header depends on the type of HTTP request and whether it includes a message body or not. The Content-Type header is mandatory for requests that include a message body, such as POST and PUT requests, but it’s not needed for requests that don’t include one, such as GET and DELETE requests.

For DocuGenerate’s API, ensuring that your requests use the correct content type is crucial for successful communication. Read on to see what content type you can use when creating or updating a template or when generating or updating a document.

Creating or updating a template

Please make sure to use the following header when creating or updating a template:

Content-Type: multipart/form-data

When calling the POST /template or the PUT /template/{id} endpoint, the content type needs to be multipart/form-data to accommodate the file parameter, which expects the binary representation of the uploaded template file:

curl -X 'POST' \
  'https://api.docugenerate.com/v1/template' \
  -H 'Authorization: 491c000c5fad32ed7787005b0723ad55' \
  -H 'Accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@Invoice.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document' \
  -F 'name=Invoice' \
  -F 'delimiters={
  "left": "[",
  "right": "]"
}' \
  -F 'enhanced_syntax=false'

The multipart/form-data content type is particularly useful when dealing with web forms that include file uploads. It allows the transmission of text and binary data as a single request, making it versatile for various data types.

Generating or updating a document

Similarly, when creating or updating a document, you can use one of the following headers:

Content-Type: application/json
Content-Type: multipart/form-data

In addition to the ability to use the multipart/form-data content type, the document generation endpoint also accepts the application/json content type.

Choosing between content types

If you need to pass a binary file containing data, it is mandatory to use the multipart/form-data content type. If your data is provided as JSON, you can use either application/json or multipart/form-data content type.

Using a data file
To generate documents in bulk from a template and an Excel file containing the data, use the multipart/form-data content type when calling the POST /document endpoint:

curl -X 'POST' \
  'https://api.docugenerate.com/v1/document' \
  -H 'Authorization: 491c000c5fad32ed7787005b0723ad55' \
  -H 'Accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'template_id=B7mRfQIxjAu4Mm3IwJVz' \
  -F 'name=Invoice' \
  -F 'page_break=true' \
  -F 'single_file=true' \
  -F 'output_format=.pdf' \
  -F 'file=@Data.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'

Using JSON data
If the data is provided as JSON, then either of the content types can be used.
For multipart/form-data, the data parameter contains the string representation of the JSON object (obtained with JSON.stringify() in JavaScript for example):

curl -X 'POST' \
  'https://api.docugenerate.com/v1/document' \
  -H 'Authorization: 491c000c5fad32ed7787005b0723ad55' \
  -H 'Accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'template_id=B7mRfQIxjAu4Mm3IwJVz' \
  -F 'data=[{"Invoice No":"INV-1001","Invoice Date":"2023-12-15","Total": "$200"},{"Invoice No":"INV-1002","Invoice Date":"2023-12-16","Total":"$500"}]' \
  -F 'name=Invoice' \
  -F 'page_break=true' \
  -F 'single_file=true' \
  -F 'output_format=.pdf'

For application/json, the whole request payload is a JSON object and contains the data property as part of it, which can be an array of JSON objects (to generate multiple documents) or a single JSON object (to generate one document):

curl -X 'POST' \
  'https://api.docugenerate.com/v1/document' \
  -H 'Authorization: 491c000c5fad32ed7787005b0723ad55' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "template_id": "B7mRfQIxjAu4Mm3IwJVz",
  "data": [{
      "Invoice No": "INV-1001",
      "Invoice Date": "2023-12-15",
      "Total": "$200"
    },
    {
       "Invoice No": "INV-1002",
       "Invoice Date": "2023-12-16",
       "Total": "$500"
    }],
  "name": "Invoice",
  "output_format": ".pdf",
  "single_file": true,
  "page_break": true
}'

Likewise, when calling the PUT /document/{id} endpoint to update an existing document, either one of the content types can be used.