Templafy’s Public 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.
Prerequisites
|
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.
- Navigate to the account section.
- In the API Keys tab, click Create key.
- Provide a name to the key.
- Click Next.
- Click Add scopeand select:
-
library.generate
: to interact with the/generate
endpoint. -
library.read
orlibrary.readwrite
(optional): to retrieve the folder or asset IDs.
-
- Click Create.
- 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.
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.
- includePdf (optional): If value is
true
, the response will include a pdf download link.
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.
- pdfDownloadUrl (string): Temporary access URL for generated PDF file. Only available if the file was converted to PDF.
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.
- includePdf (optional): If value is
true
, the response will include a pdf download link.
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.
- pdfDownloadUrl (string): Temporary access URL for generated PDF file. Only available if the file was converted to PDF.
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.
- includePdf (optional): If value is
true
, the response will include a pdf download link.
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.
- pdfDownloadUrl (string): Temporary access URL for generated PDF file. Only available if the file was converted to PDF.
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.
Important
|
Note
|
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.
Note
Non-required form fields with a default value set will be populated in the document, and any non-required form fields without a default value set will remain blank in the created document.
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 most common errors are:
- 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.
Comments
Article is closed for comments.