Unattended Document Generation Using the Templafy API

About Unattended Document Generation

Templafy’s API provides an endpoint that allows a template hosted in Templafy to be generated without the need for the user to interact with the Templafy interface. Using this endpoint, ready to consume data originating from Templafy or an intermediary system can be injected into the template.

Sections in this article:

• Swagger Documentation
• How to Use the Templafy API to generate a document
• How to successfully generate a document
• What happens if document generation is unsuccessful? 

Prerequisites

Swagger Documentation

You can access the Templafy API Swagger documentation from this link: https://api.templafy.com/?urls.primaryName=Templafy%20Public%20API%20v2%20(preview)

How to Use the Templafy API to generate a document

How to create an API token for Unattended Document Generation

In order to interact with the API to generate documents, you must generate an API key in the Templafy Admin Center

1. Navigate to the account section
2. In the API Keys tab, click Create key
3. Provide a name to the key
4. Click Next
5. Click Add scope and select
   • library.generate: to interact with the /generate endpoint
   • library.read or library.readwrite (optional): to retrieve the folder or asset IDs
6. Click Create
7. Click Copy key

Document Generation Endpoint

The /generate endpoint allows for the generation of documents from the Templafy Template libraries (Documents, Presentation, and Spreadsheets) and Text Elements. Each document created requires its own API call. The API call will return information about the file along with a download URL. This download URL will only be valid for a short amount of time.

For Documents:

POST  https://<tenantId>.api.templafy.com/v2/libraries/{spaceId}/documents/assets/{assetId}/generate

Schema:

• email (required): Email address to identify user in Templafy
• data (optional): Data to be used in file generation

Returns:

• downloadUrl (string): Temporary access URL for generated file
• fileSize (integer): File size in bytes
• checksum (string): MD5 checksum of the bytes
• mimeType (string): Mime type of the generated file
• fileExtension (string): Suffix to the name of the file

For Presentations:

POST  https://<tenantId>.api.templafy.com/v2/libraries/{spaceId}/presentations/assets/{assetId}/generate

Schema:

• email (required): Email address to identify user in Templafy
• data (optional): Data to be used in file generation

Returns:

• downloadUrl (string): Temporary access URL for generated file
• fileSize (integer): File size in bytes
• checksum (string): MD5 checksum of the bytes
• mimeType (string): Mime type of the generated file
• fileExtension (string): Suffix to the name of the file

For Spreadsheets:

POST  https://<tenantId>.api.templafy.com/v2/libraries/{spaceId}/spreadsheets/assets/{assetId}/generate

Schema:

• email (required): Email address to identify user in Templafy
• data (optional): Data to be used in file generation

Returns:

• downloadUrl (string): Temporary access URL for generated file
• fileSize (integer): File size in bytes
• checksum (string): MD5 checksum of the bytes
• mimeType (string): Mime type of the generated file
• fileExtension (string): Suffix to the name of the file

For Text Elements:

POST  https://<tenantId>.api.templafy.com/v2/libraries/{spaceId}/text-elements/assets/{assetId}/generate

Schema:

• email (required): Email address to identify user in Templafy
• data (optional): Data to be used in file generation

Returns:

• downloadUrl (string): Temporary access URL for generated file
• fileSize (integer): File size in bytes
• checksum (string): MD5 checksum of the bytes
• mimeType (string): Mime type of the generated file
• fileExtension (string): Suffix to the name of the file

How to send Data

The data that is sent in the API request must be "ready" to consume in combination with HostSystem bindings. Data cannot be transformed by using the API. Data can, however, be used in combination with all Dynamics capabilities, including looking up values from data sources, or external data sources.

The format of the sent data should follow the below example:

  "data": {
    "Language": "en-us",
    "StringField1": "Data Value 1",
    "StringField2": "Data value 2",
    "NumberField": 0003,
    "BooleanField": true,
    "DateField1": "2023-05-29T20:00:00", 
    "DateField2": "20230529"
  }

How to successfully generate a document

A dynamic document, presentation, or spreadsheet will successfully be created via API if the following are true:

• HostSystem bindings can be used to retrieve the data from the request payload in the response form as a default value or in the smart fields.  {{HostSystem.FieldName}} can be used to reference data from the API in the template, but "FieldName" must match exactly between the API request and the template.
• Each required field in the template response form must have a default value. This default value may be a HostSystem binding to include values passed from the API call.

What happens if document generation is unsuccessful? 

If one of the required form fields from the document doesn't have a default value, the unattended document generation will fail and result in a 400 error. The error message returned will contain a link to open the failed presentation, document, or spreadsheet in the Templafy document creation flow. 

The two most common errors are:

• 400 Bad Request: The document being generated contains a form without default values set. This prevents the document, spreadsheet, or presentation from being generated without user interaction. 
• 500 InternalServerError: This is a general error message that could mean a number of things. Some common causes of this error could be:
  • The document references a field with a HostSystem binding that is not present in the API request data.
  • The API request includes a null as a field's value
  • General issue with Templafy's service

Related articles