{"id":717,"date":"2021-02-19T12:23:36","date_gmt":"2021-02-19T12:23:36","guid":{"rendered":"http:\/\/167.71.55.215\/?page_id=717"},"modified":"2023-03-21T09:33:04","modified_gmt":"2023-03-21T09:33:04","slug":"api-reference","status":"publish","type":"page","link":"https:\/\/info.documotor.com\/?page_id=717","title":{"rendered":"API reference"},"content":{"rendered":"\n

DocuMotor has a wide selection of endpoints that can help you integrate DocuMotor into your system. This reference contains a description of the endpoints available, and the requirements to use them.<\/p>\n\n\n\n

Authorization<\/h2>\n\n\n\n

For all API calls, an authorization header is necessary, the following CURL request is an example of a API Call to get the templates belonging to a Unit<\/p>\n\n\n\n

curl -X GET https:\/\/documotor.com\/api\/files\/{{UnitId}}\/contents \\\n -H \"Authorization: Basic MD5(UnitId:ApiKey)\" \\\n -d '' \\<\/code><\/pre>\n\n\n\n
DocuMotor is using basic authorization, with the Auth value being an MD5Hash of UnitId:ApiKey<\/code>. To create an API key see the unit management page<\/a>.<\/p>\n\n\n\n
External Data<\/h2>\n\n\n\n
There are several external data endpoints, external data can be used to customize how your templates are structured, or save additional data with your template.<\/p>\n\n\n\n
Remember, all api calls must <\/strong>contain the authorization header.<\/p>\n\n\n\n
External validation<\/h3>\n\n\n\n
GET api\/external\/authorize\/unit\/{unitId} <\/code><\/pre>\n\n\n\n
Returns ‘401 Unauthorized’ if the UnitId in the endpoint does not match with the UnitId\/Api key used in the Authorization header<\/p>\n\n\n\n
Getting tagged templates, with a specific tag, by Unit Id<\/h3>\n\n\n\n
POST api\/external\/units\/{unitId}\/external\/ <\/code><\/pre>\n\n\n\n
This call can return all templates with a specific External Data kind that belongs to a unit.<\/p>\n\n\n\n
To get all templates with the tag ‘Tag 1’, add the following JSON snippet to the body of the request:<\/p>\n\n\n\n
{\n     \"ExternalDataKind\": \"Tag 1\"\n}<\/code><\/pre>\n\n\n\n
Which will yield a response like this:<\/p>\n\n\n\n
[{\n     \"Id\":\"TemplateId\",\n     \"Name\":\"TemplateName\",\n     \"ExternalDataTags\":[\"Tag 1\", \"Tag 2\"]\n },{\n     \"Id\":\"TemplateId\",\n     \"Name\":\"TemplateName\",\n     \"ExternalDataTags\":[\"Tag 1\"]\n }]<\/code><\/pre>\n\n\n\n
List templates by unit id, stage id, external tag<\/h3>\n\n\n\n
GET api\/external\/list\/templates<\/code><\/pre>\n\n\n\n
Returns a filtered list of folders, versioned templates and templates. The filter is based on the following query parameters.<\/p>\n\n\n\n
Parameter<\/td>Type<\/td>Description<\/td><\/tr>
parent<\/td>string<\/td>Id of the folder to start the search in. Will default to the root folder of the unit.<\/td><\/tr>
tag<\/td>string<\/td>If set, only templates and versioned templates with the tag will be returned.<\/td><\/tr>
stageId<\/td>string<\/td>If set, only versioned templates that has a template with the stage will be returned.  <\/td><\/tr>
tree<\/td>boolean<\/td>The request will also search sub folders if set to true. Will default to false.<\/td><\/tr>
flat<\/td>boolean<\/td>Flatten the result instead of returning the hierarchical order.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
When tag and stageId is defined, the endpoint will list all templates that have both the tag and are assigned to the defined stage id. <\/p>\n\n\n\n
Example of an URL with all parameters defined:<\/p>\n\n\n\n
api\/external\/list\/templates?parent=folderId&tag=tagName&stageId=stageId&tree=true<\/code><\/pre>\n\n\n\n
Example of the output<\/p>\n\n\n\n
[\n\t{\n\t\t\"fileType\": 0,\n\t\t\"kind\": null,\n\t\t\"children\": [\n\t\t\t{\n\t\t\t\t\"fileType\": 2,\n\t\t\t\t\"kind\": 0,\n\t\t\t\t\"children\": null,\n\t\t\t\t\"externalDataTags\": [\n\t\t\t\t\t\"file with tag 1\",\n\t\t\t\t\t\"file with Templates:according\"\n\t\t\t\t],\n\t\t\t\t\"id\": \"id\",\n\t\t\t\t\"name\": \"file with ttag\"\n\t\t\t}\n\t\t],\n\t\t\"externalDataTags\": null,\n\t\t\"id\": \"id\",\n\t\t\"name\": \"some folder\"\n\t},\n\t{\n\t\t\"fileType\": 2,\n\t\t\"kind\": 0,\n\t\t\"children\": null,\n\t\t\"externalDataTags\": [\n\t\t\t\"FinancialReport_approved\",\n\t\t\t\"Template:EnglishUk_approved\"\n\t\t],\n\t\t\"id\": \"id\",\n\t\t\"name\": \"Financial report\"\n\t}\n]<\/code><\/pre>\n\n\n\n
Get list of Templates By unit Id, with external data tags<\/h3>\n\n\n\n
GET api\/external\/units\/{unitId}\/templates<\/code><\/pre>\n\n\n\n
Returns a list of all templates, with their external data tags, belonging to a unit, example below:<\/p>\n\n\n\n
[{\n     \"Id\":\"TemplateId\",\n     \"Name\":\"TemplateName\",\n     \"ExternalDataTags\":[\"Tag 1\", \"Tag 2\"]\n },{\n     \"Id\":\"TemplateId\",\n     \"Name\":\"TemplateName\",\n     \"ExternalDataTags\":[\"Tag 1\"]\n },{\n     \"Id\":\"TemplateId\",\n     \"Name\":\"TemplateName\",\n     \"ExternalDataTags\":[\"Tag 3\"]\n }]<\/code><\/pre>\n\n\n\n
Get external data for a template<\/h3>\n\n\n\n
POST api\/external\/templates\/{templateId}\/data <\/code><\/pre>\n\n\n\n
To get the external data associated with a template by tag, this call can be used. Add the External to the body of the request as seen below:<\/p>\n\n\n\n
{\n     \"ExternalDataKind\": \"Tag 1\"\n}<\/code><\/pre>\n\n\n\n
This will yield a response with like so:<\/p>\n\n\n\n
{\n     \"FileAddress\":{\n         \"Template\":\"TemplateId\",\n         \"ObjectType\":\"ExternalData\"\n     }\n     \"Data\":\"Data as string\"\n}<\/code><\/pre>\n\n\n\n
Add External Data<\/h3>\n\n\n\n
POST api\/external\/templates\/{templateId} <\/code><\/pre>\n\n\n\n
To add external data to a template, again, the tag needs to be added to the body of the request, as well as a data property:<\/p>\n\n\n\n
{\n     \"ExternalDataKind\": \"Tag 1\",\n     \"Data\":\"My own external data\"\n}<\/code><\/pre>\n\n\n\n
Remove External Data<\/h3>\n\n\n\n
POST api\/external\/templates\/{templateId}\/remove <\/code><\/pre>\n\n\n\n
To remove external data from a template, make a call to this endpoint, with the tag in the body of the request:<\/p>\n\n\n\n
{\n     \"ExternalDataKind\": \"Tag 1\"\n}<\/code><\/pre>\n\n\n\n
Links<\/h2>\n\n\n\n
In your own integrations you might want the option to link directly to the Template or Unit on DocuMotor, these endspoints can be used to achieve this.<\/p>\n\n\n\n
Get a direct link to a Template<\/h3>\n\n\n\n
GET api\/link\/template\/{templateId} <\/code><\/pre>\n\n\n\n
This endpoint gets a link to the edit page of a template, example below:<\/p>\n\n\n\n
https:\/\/www.documotor.com\/organization\/{Organization}\/unit\/{Unit}\/templates\/{UnitTemplateDirectory}\/edit\/{templateId}<\/code><\/pre>\n\n\n\n
Get a direct Link to a Unit<\/h3>\n\n\n\n
GET api\/link\/unit\/{unitId} <\/code><\/pre>\n\n\n\n
This endpoint gets a link to the templates tab of the selected folder:<\/p>\n\n\n\n
https:\/\/www.documotor.com\/organization\/{Organization}\/unit\/{Unit}\/templates\/{UnitTemplateDirectory}<\/code><\/pre>\n\n\n\n
Files<\/h2>\n\n\n\n
Get folder contents<\/h3>\n\n\n\n
GET api\/files\/{folderId}\/contents <\/code><\/pre>\n\n\n\n
Templates in DocuMotor are saved in a folder structure. To list all templates in a folder, use this call.<\/p>\n\n\n\n
The response will return an array of objects like this:<\/p>\n\n\n\n
{\n     \"Id\":\"\",\n     \"Name\":\"\",\n     \"FileType\":\"\",\n     \"Kind\":\"\"\n}<\/code><\/pre>\n\n\n\n
Get direct file link<\/h3>\n\n\n\n
GET api\/files\/{itemId}\/link <\/code><\/pre>\n\n\n\n
Returns a direct link to the template file, be it YAML, Pptx or Docx.<\/p>\n\n\n\n
Get file info<\/h3>\n\n\n\n
GET api\/files\/{itemId} <\/code><\/pre>\n\n\n\n
To read info about a template file, use this call, it will return a value like below.<\/p>\n\n\n\n
{\n     \"FileName\":\"\",\n     \"ContentType\":\"\"\n }<\/code><\/pre>\n\n\n\n
Upload new template file<\/h3>\n\n\n\n
POST api\/files\/{itemId} <\/code><\/pre>\n\n\n\n
To replace a template through the API, this endpoint can be used. The file (YAML, Pptx, Docx) is inserted into the request as a Formfile with the name “File”.<\/p>\n\n\n\n
Templates<\/h2>\n\n\n\n
Get Template information<\/h3>\n\n\n\n
GET api\/template\/{templateId} <\/code><\/pre>\n\n\n\n
This endpoint returns information about the TemplateId provided in the URL, example response can look like this:<\/p>\n\n\n\n
{\n     \"Id\":\"Id\",\n     \"Name\":\"Name of Template\",\n     \"FileType\":\"Folder\/File\",\n     \"TemplateKind\":\"Optional, otherwise it returns Word, Powerpoint or YAML\"\n}<\/code><\/pre>\n\n\n\n
Generate document from template<\/h3>\n\n\n\n
POST api\/template\/{templateId}\/generate <\/code><\/pre>\n\n\n\n
To generate a document from a template, use this call. As with all other calls, the authorization must be in the header.<\/p>\n\n\n\n
The body of the request, this time, is the JSON data you want to use in your template to generate the document, content for a letter could be something like this, for example:<\/p>\n\n\n\n
{\n     \"Sender\": \"Lars Hansen\",\n     \"Message\": \"Welcome to the DocuMotor documentation\",\n     \"Recipients\": [\n         \"Klaus\",\n         \"Hanne\",\n         \"Peter\"\n     ]\n}<\/code><\/pre>\n\n\n\n
Versioned templates<\/h4>\n\n\n\n
For versioned templates specify the id of the stage for which to generate the document in the header as “stageId”:{stageId}.<\/p>\n\n\n\n
Enforce PDF output<\/h4>\n\n\n\n
To enforce PDF output append specify the header “Accept” with the value being “application\/pdf”. <\/p>\n\n\n\n
Backup API<\/h2>\n\n\n\n
The following endpoints have been added to DocuMotor. All of the endpoints use the usual authentication for public API’s.
All actions are performed on the unit used in authentication.<\/p>\n\n\n\n
If a request fails, it will return status 422 and have the error message as plain text in the response body.
If a task fails, the associated log will have Failed as its status and the error message in reason phrase.<\/p>\n\n\n\n
List of backups<\/h3>\n\n\n\n
GET api\/backup<\/code><\/pre>\n\n\n\n
Gets a list of all backups in the unit used for authentication.<\/p>\n\n\n\n
Successful response: <\/strong>200<\/p>\n\n\n\n
Response content<\/strong>: list of backups ids (string[])<\/p>\n\n\n\n
Create backup<\/h3>\n\n\n\n
Adds a task for creating a backup to the global queue. Use the log id to track the status of the task. The id of the created backup will be added to the log, it should only be used after the task has completed.<\/p>\n\n\n\n
POST api\/backup\/create<\/code><\/pre>\n\n\n\n
Body<\/strong>: <\/p>\n\n\n\n
{   \"displayName\": string } <\/code><\/pre>\n\n\n\n
Accepts<\/strong>: application\/json<\/p>\n\n\n\n
Successful response: 202 Accepted<\/p>\n\n\n\n
Response content<\/strong>: Object with log id of the created task.<\/p>\n\n\n\n
{   \"logId\": string } <\/code><\/pre>\n\n\n\n
Restore backup<\/h3>\n\n\n\n
Adds a task for restoring a backup to the global queue. Use the log id to track the status of the task.<\/p>\n\n\n\n
PUT api\/backup\/{backupId}\/restore<\/code><\/pre>\n\n\n\n
Parameter <\/strong>“backupId” – the id of the backup to restore.<\/p>\n\n\n\n
Successful response<\/strong>: 202 accepted <\/p>\n\n\n\n
Response content: <\/p>\n\n\n\n
{   \"logId\": string } <\/code><\/pre>\n\n\n\n
Download backup<\/h3>\n\n\n\n
Downloads the provided backup as a zip file.<\/p>\n\n\n\n
GET api\/backup\/{backupId}\/download<\/code><\/pre>\n\n\n\n
Parameter <\/strong>“backupId” – the id of the backup to restore.<\/p>\n\n\n\n
Successful response<\/strong>: 200 <\/p>\n\n\n\n
Response content: byte[]\/stream<\/p>\n\n\n\n
Upload backup<\/h3>\n\n\n\n
Uploads a backup zip file to the unit. Backup id, creation date and display name is stored in the zip file and will be used when creating the backup.
The same backup can not be uploaded to the same unit, unless it has been deleted. <\/p>\n\n\n\n
POST api\/backup\/upload<\/code><\/pre>\n\n\n\n
Successful response<\/strong>: 200 <\/p>\n\n\n\n
Response content: <\/p>\n\n\n\n
{   \"backupId\": string } <\/code><\/pre>\n\n\n\n
Backup log info<\/h3>\n\n\n\n
Gets the info of the log. It contains the data regarding a specific backup task with relevant information included in the response. <\/p>\n\n\n\n
Use this endpoint to check the status of the task using the log id received from Upload or Create endpoints. <\/p>\n\n\n\n
GET api\/backup\/log\/{logId}<\/code><\/pre>\n\n\n\n
Parameter logId<\/strong> is the id of the log to get info of.<\/p>\n\n\n\n
Successful response: 200<\/p>\n\n\n\n
Response content:<\/p>\n\n\n\n
{ \n  \"id\": string,                      \/\/ Id of log. \n  \"displayName\": string,             \/\/ The display name of the associated backup. \n  \"backupId\": string or null,        \/\/ The id of the associated backup. \n  \"retryCount\": int,                 \/\/ Number of times the task has been retried. \n  \"backupType\": string,              \/\/ The type of backup task, can be Create or RestoreUnit. \n  \"status\": string,                  \/\/ The current status of the task, can be Scheduled, Running, Failed, Completed or Cancelled. \n  \"statusReason\": string,            \/\/ Message explaining the status. \n  \"timeOfCreation\": DateTime,        \/\/ When the log was created. \n  \"lastHeartbeat\": DateTime or null  \/\/ Heartbeat used to determine if a running task has timed out. \n} <\/code><\/code><\/pre>\n\n\n\n
Backup info<\/h3>\n\n\n\n
Gets the info of the backup.<\/p>\n\n\n\n
GET api\/backup\/log\/{backupId}<\/code><\/pre>\n\n\n\n
Successful response:  <\/strong>200<\/p>\n\n\n\n
Response content: <\/p>\n\n\n\n
{ \n  \"id\": string,              \/\/ The id of the backup \n  \"displayName\": string,     \/\/ The display name of the backup \n  \"creationDate\": DateTime   \/\/ The creation date of the backup \n} <\/code><\/code><\/pre>\n\n\n\n
<\/div>\n","protected":false},"excerpt":{"rendered":"
DocuMotor has a wide selection of endpoints that can help you integrate DocuMotor into your system. This reference contains a description of the endpoints available, and the requirements to use them. Authorization For all API calls, an authorization header is necessary, the following CURL request is an example of a API Call to get the […]<\/p>\n","protected":false},"author":2,"featured_media":0,"parent":31,"menu_order":4,"comment_status":"closed","ping_status":"closed","template":"","meta":[],"_links":{"self":[{"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/pages\/717"}],"collection":[{"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/info.documotor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=717"}],"version-history":[{"count":36,"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/pages\/717\/revisions"}],"predecessor-version":[{"id":5302,"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/pages\/717\/revisions\/5302"}],"up":[{"embeddable":true,"href":"https:\/\/info.documotor.com\/index.php?rest_route=\/wp\/v2\/pages\/31"}],"wp:attachment":[{"href":"https:\/\/info.documotor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=717"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}