{"openapi":"3.0.0","paths":{"/v1/template":{"post":{"operationId":"createTemplate","summary":"Create template","description":"Create a template from a `.docx`, `.doc`, `.odt`, `.rtf`, `.txt`, `.sql` or `.html` file.

\nMake sure to use the `multipart/form-data` content type when making the request.

\nThis is required for submitting the binary `file` containing the template.","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Template file in the `.docx`, `.doc`, `.odt`, `.rtf`, `.txt`, `.sql` or `.html` format.","example":""},"name":{"type":"string","description":"The template’s name. If not provided, it will be initialized with the name of the uploaded template file.","example":""},"delimiters":{"type":"object","description":"Delimiters used to detect the tags. If not provided, they will be determined automatically.
For example, if the tags defined in the template are `[Name]`, `[Address]`, etc., then the left delimiter is `[` and the right delimiter is `]`.","properties":{"left":{"type":"string","description":"Left delimiter for the tags.","example":"["},"right":{"type":"string","description":"Right delimiter for the tags.","example":"]"}}},"region":{"type":"string","enum":["us","eu","uk","au"],"description":"The physical location where the template and its generated documents are stored.
This value is optional. If omitted, the account's default region will be used.
Possible values are `us` (United States), `eu` (European Union), `uk` (United Kingdom), and `au` (Australia).","default":"us"},"enhanced_syntax":{"type":"boolean","description":"Flag to determine if nested properties of objects and logical & mathematical operators can be used for this template. The default value is `false`.
Enabling this flag make it possible to use tags like `[item.name]` in the template, where `item` is an object containing the `name` property.","default":false},"versioning_enabled":{"type":"boolean","description":"Flag to enable template file versioning, preserving previous versions when a new file is uploaded.
The default value is `true` if the versioning feature is available, otherwhise the default value is `false`.
The template versioning feature is available only with the Premium and Business plans.","default":false}},"required":["file"]}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"401":{"description":"Unauthorized"}},"tags":["Template"],"security":[{"API Key":[]}]},"get":{"operationId":"queryTemplates","summary":"List templates","description":"List all templates, ordered by the `created` time in descending order.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}}},"401":{"description":"Unauthorized"}},"tags":["Template"],"security":[{"API Key":[]}]}},"/v1/template/{id}":{"get":{"operationId":"getTemplate","summary":"Get template","description":"Get a template by `id`.","parameters":[{"name":"id","required":true,"in":"path","description":"ID of the template.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Template not found"}},"tags":["Template"],"security":[{"API Key":[]}]},"put":{"operationId":"updateTemplate","summary":"Update template","description":"Update a template by `id`.","parameters":[{"name":"id","required":true,"in":"path","description":"ID of the template.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Template file in the `.docx`, `.doc`, `.odt`, `.rtf`, `.txt`, `.sql` or `.html` format.
If provided, the new template will be processed and will replace the current template.
Unless specified explicitely, the current template delimiters will be used for processing.","example":""},"name":{"type":"string","description":"The template’s name. If provided, it will be override the current name of the template.","example":""},"delimiters":{"type":"object","description":"Delimiters used to detect the tags. If provided, the template will be re-processed to determine the tags based on the new delimiters.","properties":{"left":{"type":"string","description":"Left delimiter for the tags.","example":"["},"right":{"type":"string","description":"Right delimiter for the tags.","example":"]"}}},"region":{"type":"string","enum":["us","eu","uk","au"],"description":"The physical location where the template and its generated documents are stored.
If the specified region is different from the current template's region, the template will be moved to the new region.
Documents generated after the change will be stored in the new region, while existing documents will remain unaffected.
Possible values are `us` (United States), `eu` (European Union), `uk` (United Kingdom), and `au` (Australia).","default":"us"},"enhanced_syntax":{"type":"boolean","description":"Flag to determine if nested properties of objects and logical & mathematical operators can be used for this template.
Enabling this flag make it possible to use tags like `[item.name]` in the template, where `item` is an object containing the `name` property.","default":false},"versioning_enabled":{"type":"boolean","description":"Flag to enable template file versioning, preserving previous versions when a new file is uploaded.
The template versioning feature is available only with the Premium and Business plans.","default":false}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Template not found"}},"tags":["Template"],"security":[{"API Key":[]}]},"delete":{"operationId":"deleteTemplate","summary":"Delete template","description":"Delete a template by `id`.","parameters":[{"name":"id","required":true,"in":"path","description":"ID of the template.","schema":{"type":"string"}}],"responses":{"204":{"description":"Template successfully deleted"},"401":{"description":"Unauthorized"},"404":{"description":"Template not found"}},"tags":["Template"],"security":[{"API Key":[]}]}},"/v1/document":{"post":{"operationId":"generateDocument","summary":"Generate document","description":"Generate a document based on a template and a data set.

\nIt is possible to specify one of the following values for the `Content-Type` header when making the request:\n- `multipart/form-data` : using this content type is mandatory if you pass a binary `file` containing the data

\n- `application/json` : if you pass the `data` as JSON, then either one the content types can be used

\n\nTo control how the browser handles the generated document, specify a value for the `Content-Disposition` header in your request:\n- `attachment` : the document will be downloaded by the browser (by default if no value is provided)

\n- `inline` : the document will be displayed directly in the browser (if supported by the browser)

\n\nYou can also specify one of the following values for the `Accept` header, depending on how you want to receive the generated document:\n- `application/json` : the generated document is stored in the cloud and the response is a JSON object following the Document schema

\n- `application/octet-stream` : the generated document is not stored in the cloud and the response represents the document in binary format

\n\nIn case of the binary format response, the server will return two additional headers:\n- `Content-Disposition` : which specifies the filename of the generated document

\n- `X-Document-Id` : which contains the unique ID associated with the generated document

","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"template_id":{"type":"string","description":"ID of the template to use for generating the document.","example":""},"data":{"oneOf":[{"type":"array","items":{"type":"object"}},{"type":"object"}],"description":"Data that will be used to generate documents based on the template.
The expected format is an array of JSON objects or a single JSON object.
A document will be generated for each object by replacing the tags from the template with the object's values.
Either the `data` or `file` parameter may be provided in the request.","example":{}},"file":{"type":"string","format":"binary","description":"Data file in the `.xlsx`, `.xls`, `.ods`, `.csv` or `.tsv` format.
A document will be generated for each row in the file by replacing the tags from the template with the row's values.
Either the `data` or `file` parameter may be provided in the request.","example":""},"sheet":{"type":"string","description":"If a spreadsheet `file` is uploaded, this parameter represents the name of the sheet to be used to extract the data from.
If the `sheet` value is not specified, then the first sheet in the spreadsheet will be used.","example":""},"name":{"type":"string","description":"The document’s name. If not provided, it will be initialized with the template’s name.
This is a logical name for identifying the document and is different from the `output_name` which specifies the filename of the generated document. ","example":""},"output_name":{"type":"string","description":"The filename without extension of the generated document. If not provided, it will be initialized based on the document’s name.
For example, if `output_name`=`invoice` and `output_format`=`.pdf` then the filename of the generated document will be `invoice.pdf`.","example":""},"output_format":{"type":"string","enum":[".docx",".doc",".odt",".txt",".html",".png",".pdf",".pdf/a-1b",".pdf/a-2b",".pdf/a-3b"],"description":"Output format of the generated document. If no format is specified, then the default format is `.docx`.
The supported formats are `.docx`, `.doc`, `.odt`, `.txt`, `.html`, `.png`, `.pdf`, `.pdf/a-1b`, `.pdf/a-2b` and `.pdf/a-3b`.
If the format is `.png`, then only the first page is exported. This is useful for generating document thumbnails for example.
The `.pdf/a-1b`, `.pdf/a-2b` and `.pdf/a-3b` formats allow selecting the PDF/A version for archival purposes.","default":".docx"},"output_quality":{"type":"integer","description":"Specifies the quality of the generated document if `output_format` is `.pdf` (or a PDF/A version) or `.png`. A higher value results in higher quality and file size.
The lower the value, the less good is the image compression quality and the bigger is the file size. The minimum value is `1`.
The higher the value, the better is the image compression quality and the smaller is the file size. The maximum value is `100`, which is also the default.","minimum":1,"maximum":100,"default":100},"single_file":{"type":"boolean","description":"If the flag is `true`, then all the generated documents will be combined in a single file with the `output_format` format.
If the flag is `false`, then for each data item a separate document will be generated with the `output_format` format and the all the files will be included in a `.zip` archive.
The flag is ignored if there is only one data item, so to generate a `.zip` archive multiple data items are required. By default, the flag value is `true`.","default":true},"page_break":{"type":"boolean","description":"Flag indicating whether to add a page break in the document after each data row. The default value is `true`.
The flag only applies if `single_file` is `true`.","default":true},"merge_with":{"oneOf":[{"type":"string","format":"uri"},{"type":"array","items":{"type":"string","format":"uri"}}],"description":"PDF file(s) to be merged at the end of the generated document, specified as a URL or a Base64-encoded data URI, or an array of such values.
If any document specified by a URL is not found or is not a PDF file, then that file will be ignored.
If the flag `single_file` is `false`, then the PDF file(s) are merged at the end of each generated document.
If multiple files are provided, they will be merged in the order they appear in the array.
This parameter is only applicable if `output_format` is `.pdf` (or a PDF/A version).","example":""},"attach":{"oneOf":[{"type":"string","format":"uri"},{"type":"array","items":{"type":"string","format":"uri"}}],"description":"File(s) to be attached to the generated document, specified as a URL or a Base64-encoded data URI, or an array of such values.
If a URL is provided, the filename will be automatically determined from the URL.
If a data URI is used, the filename can be specified with the `name` property in the URI (e.g., `data:text/xml;name=invoice.xml;base64,...`).
If no filename is specified in the data URI, the file will be named `attachment` with an extension matching the MIME type (e.g., `attachment.xml` for `text/xml`).
If the flag `single_file` is `false`, then the file(s) are attached to each generated document.
If multiple files are provided, they will be attached in the order they appear in the array.
This parameter is only applicable if `output_format` is `.pdf` (or a PDF/A version).","example":""}},"required":["template_id"]}},"application/json":{"schema":{"type":"object","properties":{"template_id":{"type":"string","description":"ID of the template to use for generating the document.","example":""},"data":{"oneOf":[{"type":"array","items":{"type":"object"}},{"type":"object"}],"description":"Data that will be used to generate documents based on the template.
The expected format is an array of JSON objects or a single JSON object.
A document will be generated for each object by replacing the tags from the template with the object's values.
Either the `data` or `file` parameter may be provided in the request.","example":{}},"file":{"type":"string","format":"binary","description":"Data file in the `.xlsx`, `.xls`, `.ods`, `.csv` or `.tsv` format.
A document will be generated for each row in the file by replacing the tags from the template with the row's values.
Either the `data` or `file` parameter may be provided in the request.","example":""},"sheet":{"type":"string","description":"If a spreadsheet `file` is uploaded, this parameter represents the name of the sheet to be used to extract the data from.
If the `sheet` value is not specified, then the first sheet in the spreadsheet will be used.","example":""},"name":{"type":"string","description":"The document’s name. If not provided, it will be initialized with the template’s name.
This is a logical name for identifying the document and is different from the `output_name` which specifies the filename of the generated document. ","example":""},"output_name":{"type":"string","description":"The filename without extension of the generated document. If not provided, it will be initialized based on the document’s name.
For example, if `output_name`=`invoice` and `output_format`=`.pdf` then the filename of the generated document will be `invoice.pdf`.","example":""},"output_format":{"type":"string","enum":[".docx",".doc",".odt",".txt",".html",".png",".pdf",".pdf/a-1b",".pdf/a-2b",".pdf/a-3b"],"description":"Output format of the generated document. If no format is specified, then the default format is `.docx`.
The supported formats are `.docx`, `.doc`, `.odt`, `.txt`, `.html`, `.png`, `.pdf`, `.pdf/a-1b`, `.pdf/a-2b` and `.pdf/a-3b`.
If the format is `.png`, then only the first page is exported. This is useful for generating document thumbnails for example.
The `.pdf/a-1b`, `.pdf/a-2b` and `.pdf/a-3b` formats allow selecting the PDF/A version for archival purposes.","default":".docx"},"output_quality":{"type":"integer","description":"Specifies the quality of the generated document if `output_format` is `.pdf` (or a PDF/A version) or `.png`. A higher value results in higher quality and file size.
The lower the value, the less good is the image compression quality and the bigger is the file size. The minimum value is `1`.
The higher the value, the better is the image compression quality and the smaller is the file size. The maximum value is `100`, which is also the default.","minimum":1,"maximum":100,"default":100},"single_file":{"type":"boolean","description":"If the flag is `true`, then all the generated documents will be combined in a single file with the `output_format` format.
If the flag is `false`, then for each data item a separate document will be generated with the `output_format` format and the all the files will be included in a `.zip` archive.
The flag is ignored if there is only one data item, so to generate a `.zip` archive multiple data items are required. By default, the flag value is `true`.","default":true},"page_break":{"type":"boolean","description":"Flag indicating whether to add a page break in the document after each data row. The default value is `true`.
The flag only applies if `single_file` is `true`.","default":true},"merge_with":{"oneOf":[{"type":"string","format":"uri"},{"type":"array","items":{"type":"string","format":"uri"}}],"description":"PDF file(s) to be merged at the end of the generated document, specified as a URL or a Base64-encoded data URI, or an array of such values.
If any document specified by a URL is not found or is not a PDF file, then that file will be ignored.
If the flag `single_file` is `false`, then the PDF file(s) are merged at the end of each generated document.
If multiple files are provided, they will be merged in the order they appear in the array.
This parameter is only applicable if `output_format` is `.pdf` (or a PDF/A version).","example":""},"attach":{"oneOf":[{"type":"string","format":"uri"},{"type":"array","items":{"type":"string","format":"uri"}}],"description":"File(s) to be attached to the generated document, specified as a URL or a Base64-encoded data URI, or an array of such values.
If a URL is provided, the filename will be automatically determined from the URL.
If a data URI is used, the filename can be specified with the `name` property in the URI (e.g., `data:text/xml;name=invoice.xml;base64,...`).
If no filename is specified in the data URI, the file will be named `attachment` with an extension matching the MIME type (e.g., `attachment.xml` for `text/xml`).
If the flag `single_file` is `false`, then the file(s) are attached to each generated document.
If multiple files are provided, they will be attached in the order they appear in the array.
This parameter is only applicable if `output_format` is `.pdf` (or a PDF/A version).","example":""}},"required":["template_id"]}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}},"application/octet-stream":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Unauthorized"}},"tags":["Document"],"security":[{"API Key":[]}]},"get":{"operationId":"queryDocuments","summary":"List documents for a template","description":"List all documents generated from the template `template_id`.

\nThe `template_id` should be provided as a query parameter.

\nResults are ordered by the `created` time in descending order.","parameters":[{"name":"template_id","required":true,"in":"query","description":"ID of the template that was used to generate the documents.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Document"}}}}},"401":{"description":"Unauthorized"}},"tags":["Document"],"security":[{"API Key":[]}]}},"/v1/document/{id}":{"get":{"operationId":"getDocument","summary":"Get document","description":"Get a document by `id`.","parameters":[{"name":"id","required":true,"in":"path","description":"ID of the document.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Document not found"}},"tags":["Document"],"security":[{"API Key":[]}]},"put":{"operationId":"updateDocument","summary":"Update document","description":"Update a document by `id`.","parameters":[{"name":"id","required":true,"in":"path","description":"ID of the document.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The document’s name.","example":""}},"required":["name"]}},"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The document’s name.","example":""}},"required":["name"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Document not found"}},"tags":["Document"],"security":[{"API Key":[]}]},"delete":{"operationId":"deleteDocument","summary":"Delete document","description":"Delete a document by `id`.","parameters":[{"name":"id","required":true,"in":"path","description":"ID of the document.","schema":{"type":"string"}}],"responses":{"204":{"description":"Document successfully deleted"},"401":{"description":"Unauthorized"},"404":{"description":"Document not found"}},"tags":["Document"],"security":[{"API Key":[]}]}}},"info":{"title":"DocuGenerate API Reference","description":"Sign Up for a new account and get \n\t\t\tyour unique API Key from the Developers tab in the Settings page.

\n\t\t\tTo authenticate, you'll need to pass the API Key in the Authorization header when making HTTP requests:

\n\t\t\t      `Authorization: `

\n\t\t\tGet started in 2 simple steps:
\n\t\t\t
    \n\t\t\t\t
  1. Call `POST http://localhost:3000/v1/template` to create a document template with tags in places where you want to have dynamic text.
    2. \n\t\t\t\t
  2. Call `POST http://localhost:3000/v1/document` to generate documents by replacing all the tags in the template with the values from the data input.
    3. \n\t\t\t
\n\t\t\t

\n\t\t\tRegional API endpoints: \n\t\t\tUnited States |\n\t\t\tEuropean Union |\n\t\t\tUnited Kingdom |\n\t\t\tAustralia \n\t\t\t

","version":"1.8.4","contact":{"name":"DocuGenerate","url":"https://www.docugenerate.com","email":"support@docugenerate.com"}},"tags":[{"name":"Template","description":""},{"name":"Document","description":""}],"servers":[{"url":"https://api.docugenerate.com","description":"Default API endpoint (United States)"},{"url":"https://api.{region}.docugenerate.com","description":"Regional API endpoints","variables":{"region":{"default":"us","enum":["us","eu","uk","au"]}}}],"components":{"securitySchemes":{"API Key":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"Delimiters":{"type":"object","properties":{"left":{"type":"string","description":"Left delimiter for the tags.","example":"["},"right":{"type":"string","description":"Right delimiter for the tags.","example":"]"}},"required":["left","right"]},"Tags":{"type":"object","properties":{"valid":{"description":"List of the valid tags extracted from the template. The values can either be simple strings or objects.
\nIn the case of more complex structures like lists or tables, they are represented as objects containing a single key-value pair.
\nTake the following table defined in a template as an example:

\n`[#Items][Name][Quantity][/]`

\nIn this instance, the tag representation is an object that corresponds to the structure of the table:

\n`[{\"Items\": [\"Name\", \"Quantity\"]}]`.","example":["Invoice No","Company Name","Street Address","City","State","Zip Code","Invoice Date","Due Date","Sub Total","Total"],"default":[],"type":"array","items":{"type":"object"}},"invalid":{"description":"List of the invalid tags extracted from the template.\nFor example, unclosed tags will appear as invalid.","example":[],"default":[],"type":"array","items":{"type":"string"}}},"required":["valid","invalid"]},"Template":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the template.","example":"CctvL5PkbEifvnkDh6L0"},"created":{"type":"number","description":"Time at which the template was created. Measured in milliseconds since the Unix epoch.","example":1711172339868},"updated":{"type":"number","description":"Time at which the template was updated. Measured in milliseconds since the Unix epoch.","example":1711172339868},"name":{"type":"string","description":"The template’s name.","example":"Business Invoice"},"page_count":{"type":"number","description":"The template’s number of pages.","example":1},"delimiters":{"description":"Delimiters used to detect the tags. For example, if the tags defined in the template are\n[Name], [Address], etc., then the left delimiter is '[' and the right delimiter is ']'.","allOf":[{"$ref":"#/components/schemas/Delimiters"}]},"tags":{"description":"Tags extracted from the template, grouped by valid and invalid.\nIf the template contains at least one invalid tag, then it cannot be used to generate documents.","allOf":[{"$ref":"#/components/schemas/Tags"}]},"filename":{"type":"string","description":"The filename of the uploaded template file.","example":"Business Invoice.docx"},"format":{"type":"string","description":"The format of the uploaded template.","example":".docx"},"region":{"type":"string","description":"The physical location where the template and its generated documents are stored.\nPossible values are \"us\" (United States), \"eu\" (European Union), \"uk\" (United Kingdom), and \"au\" (Australia).","example":"us"},"template_uri":{"type":"string","description":"Download link of the uploaded template file.","example":"https://firebasestorage.googleapis.com/v0/b/storage.us.docugenerate.com/o/templates%2FtwdXgHpSBaWgL0P5udd4%2FBusiness%20Invoice.docx?alt=media&token=3c3f9d69-e990-416f-b072-282cfba888d3"},"preview_uri":{"type":"string","description":"Download link of the template converted to .pdf format.","example":"https://firebasestorage.googleapis.com/v0/b/storage.us.docugenerate.com/o/templates%2FtwdXgHpSBaWgL0P5udd4%2FBusiness%20Invoice.pdf?alt=media&token=2e3f0320-f3e6-44c6-b8a4-838b74782f99"},"image_uri":{"type":"string","description":"Download link of an image in .png format of the template's first page.","example":"https://firebasestorage.googleapis.com/v0/b/storage.us.docugenerate.com/o/templates%2FtwdXgHpSBaWgL0P5udd4%2FBusiness%20Invoice.png?alt=media&token=63e78a3e-cac0-4519-b83d-dd02a3ec79ae"},"enhanced_syntax":{"type":"boolean","description":"Flag to determine if nested properties of objects and logical & mathematical operators can be used for this template.","example":false,"default":false},"versioning_enabled":{"type":"boolean","description":"Flag to enable template versioning, preserving previous versions when a new file is uploaded.","example":false,"default":false}},"required":["id","created","updated","name","page_count","delimiters","tags","filename","format","region","template_uri","preview_uri","image_uri","enhanced_syntax","versioning_enabled"]},"Document":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the document.","example":"dWaTxGd6FxT6RvqcAltC"},"template_id":{"type":"string","description":"The id of the template used to generate the document.","example":"CctvL5PkbEifvnkDh6L0"},"created":{"type":"number","description":"Time at which the document was created. Measured in milliseconds since the Unix epoch.","example":1711172421222},"name":{"type":"string","description":"The document’s name.","example":"Invoice N°65-090-7669"},"data_length":{"type":"number","description":"Length of the data object used to generate the document.","example":1},"filename":{"type":"string","description":"The filename of the generated document.","example":"Invoice N°65-090-7669.pdf"},"format":{"type":"string","description":"The format of the generated document.","example":".pdf"},"document_uri":{"type":"string","description":"Download link of the generated document.","example":"https://firebasestorage.googleapis.com/v0/b/storage.us.docugenerate.com/o/documents%2FoSbgxHyMexmvCJ9bJA4K%2FBusiness%20Invoice.pdf?alt=media&token=3ec01b53-fac4-4f6a-a92a-e097da949493"}},"required":["id","template_id","created","name","data_length","filename","format","document_uri"]}}}}