API options ⚙️

Introduction

This page will explain all parameters of the request body that is consumed by the API. You can test different request bodies with our API Playground. If you want to send a request to the api from outside the API playground, you will need to add an API-key to your header.

Request parameters

The API only consumes POST requests with a valid JSON body. Your request header needs to contain your API-key as a x-api-key field.

POST Request Endpoint: docs.aeco.cloud/api/v0.4 HEADER: { x-api-key: YOUR API KEY } BODY: { "yourPostBody": "inJsonFormat" }

Request body parameters

parameterrequireddefaulttypedescription
templateIdyes-stringThe id of the template to which you want to make an API call
documentNamenothe document IdstringThe name of the document. This is relevant when opening your document as a google doc and copyTemplate is set to true. When copyTemplate is set to false the original name of the template will be used
copyTemplatenotruebooleanWhen set to true, the template will be copied and the copy will be manipulated by the instructions in the api call. When set to false the original template will be overwritten with the instructions in your API call. You should only set this option to false if you have a static document. Setting this to false makes your API call faster since the copy step is skipped. ⚠️ For copyTemplate = false to work you need to grant the api Editor access to your document instead of view access.
textSubstitutionsno-{placeholder: string, text: string}[]An array of placeholder/text pairs that will replace alll placeholders found in the document with the corresponding text.
imageSubstitutionsno-{placeholder: string,uri: string,size?: {height?: number,width?: number}}[]An array of placeholder/uri pairs that will replace all placeholders with the image in the uri. Optionally you can also provide a width and height (units are in pt).
conditionalSubstitutionsno-{start: string, end: string, display: boolean}[]An array of objects with start, end and display properties. Use the start and end properties to identify the start/end placeholders of the sections you want to display (by setting the display property to true or false).
tableSubstitutionsno-{start: string, data: string[[]]}[]An array of objects with start and data properties. The start value is the value used to identify the table in the document you want to fill in with data. The data array is an array of string values, with the first array in the array being the first row, the second array being the second row, etc. If these arrays have more items than the columns premade in the document, then the items with a index value higher than the length of the pre made number of columns will be ignored.

⚠️ Expected behaviour is to have a table with a number of columns and two rows. The first row is a header and can be premade in the document. The start identifier should be placed in the second row of this table. An example of this structure can be found in the API Playground.

⚠️ Styling the data should also happen in the document itself, by changing the styling of the second row of the table. The rows inserted with tableSubstitutions will inherit the styling of this second row.
returnTypeyes["pdf"]string[ ]A list of formats in which to export the document. Options are pdf, html, docx, googleDoc, pdfDownloadUrl, htmlDownloadUrl, docxDownloadUrl.

⚠️ The docx return type is still in development.

⚠️ if you request a downloadUrl, the document must be saved in a google drive (use the saveInGoogleDrive option) and the document will be made publicly available for 5 minutes.

⚠️ If you request the googleDoc you will also need to store it in a google drive (use the saveInGooGleDrive option) and a user will need access to this google drive in order to access the google document.
saveInGoogleDriveno-string[ ]A list of google drive folder ids in which the google doc version of the created document will be saved. This will only work if copyTemplate is set to true and access-document@aeco-docs-production.iam.gserviceaccount.com has editor access to the provided google drive folder. If no folders are provided, the document will be deleted from the server after being returned in the requested format.

Response body parameters

⚠️ Only the document types that are specified in the returnType array will be returned.

parametertypedescription
htmltext/htmlThe document converted to html formatting.
pdfapplication/pdfThe document in pdf as a base64 string.
docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.documentThe document in .docx format. ⚠️ This is still in development.
googleDocstringThe URL to the google document
htmlDownloadUrlstringA direct download link of the document in html format
pdfDownloadUrlstringA direct download link of the document in pdf format
docxDownloadUrlstringA direct download link of the document in docx format