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 templates belonging to a Unit
curl -X GET https://documotor.com/api/files/{{UnitId}}/contents \
-H "Authorization: Basic MD5(UnitId:ApiKey)" \
-d '' \DocuMotor is using basic authorization, with the Auth value being an MD5Hash of UnitId:ApiKey. To create an API key see the unit management page.
External Data
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.
Remember, all api calls must contain the authorization header.
External validation
GET api/external/authorize/unit/{unitId} Returns ‘401 Unauthorized’ if the UnitId in the endpoint does not match with the UnitId/Api key used in the Authorization header
Getting tagged templates, with a specific tag, by Unit Id
POST api/external/units/{unitId}/external/ This call can return all templates with a specific External Data kind that belongs to a unit.
To get all templates with the tag ‘Tag 1’, add the following JSON snippet to the body of the request:
{
"ExternalDataKind": "Tag 1"
}Which will yield a response like this:
[{
"Id":"TemplateId",
"Name":"TemplateName",
"ExternalDataTags":["Tag 1", "Tag 2"]
},{
"Id":"TemplateId",
"Name":"TemplateName",
"ExternalDataTags":["Tag 1"]
}]List templates by unit id, stage id, external tag
GET api/external/list/templatesReturns a filtered list of folders, versioned templates and templates. The filter is based on the following query parameters.
| Parameter | Type | Description |
| parent | string | Id of the folder to start the search in. Will default to the root folder of the unit. |
| tag | string | If set, only templates and versioned templates with the tag will be returned. |
| stageId | string | If set, only versioned templates that has a template with the stage will be returned. |
| tree | boolean | The request will also search sub folders if set to true. Will default to false. |
| flat | boolean | Flatten the result instead of returning the hierarchical order. |
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.
Example of an URL with all parameters defined:
api/external/list/templates?parent=folderId&tag=tagName&stageId=stageId&tree=trueExample of the output
[
{
"fileType": 0,
"kind": null,
"children": [
{
"fileType": 2,
"kind": 0,
"children": null,
"externalDataTags": [
"file with tag 1",
"file with Templates:according"
],
"id": "id",
"name": "file with ttag"
}
],
"externalDataTags": null,
"id": "id",
"name": "some folder"
},
{
"fileType": 2,
"kind": 0,
"children": null,
"externalDataTags": [
"FinancialReport_approved",
"Template:EnglishUk_approved"
],
"id": "id",
"name": "Financial report"
}
]Get list of Templates By unit Id, with external data tags
GET api/external/units/{unitId}/templatesReturns a list of all templates, with their external data tags, belonging to a unit, example below:
[{
"Id":"TemplateId",
"Name":"TemplateName",
"ExternalDataTags":["Tag 1", "Tag 2"]
},{
"Id":"TemplateId",
"Name":"TemplateName",
"ExternalDataTags":["Tag 1"]
},{
"Id":"TemplateId",
"Name":"TemplateName",
"ExternalDataTags":["Tag 3"]
}]Get external data for a template
POST api/external/templates/{templateId}/data 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:
{
"ExternalDataKind": "Tag 1"
}This will yield a response with like so:
{
"FileAddress":{
"Template":"TemplateId",
"ObjectType":"ExternalData"
}
"Data":"Data as string"
}Add External Data
POST api/external/templates/{templateId} 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:
{
"ExternalDataKind": "Tag 1",
"Data":"My own external data"
}Remove External Data
POST api/external/templates/{templateId}/remove To remove external data from a template, make a call to this endpoint, with the tag in the body of the request:
{
"ExternalDataKind": "Tag 1"
}Links
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.
Get a direct link to a Template
GET api/link/template/{templateId} This endpoint gets a link to the edit page of a template, example below:
https://www.documotor.com/organization/{Organization}/unit/{Unit}/templates/{UnitTemplateDirectory}/edit/{templateId}Get a direct Link to a Unit
GET api/link/unit/{unitId} This endpoint gets a link to the templates tab of the selected folder:
https://www.documotor.com/organization/{Organization}/unit/{Unit}/templates/{UnitTemplateDirectory}Files
Get folder contents
GET api/files/{folderId}/contents Templates in DocuMotor are saved in a folder structure. To list all templates in a folder, use this call.
The response will return an array of objects like this:
{
"Id":"",
"Name":"",
"FileType":"",
"Kind":""
}Get direct file link
GET api/files/{itemId}/link Returns a direct link to the template file, be it YAML, Pptx or Docx.
Get file info
GET api/files/{itemId} To read info about a template file, use this call, it will return a value like below.
{
"FileName":"",
"ContentType":""
}Upload new template file
POST api/files/{itemId} 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”.
Templates
Get Template information
GET api/template/{templateId} This endpoint returns information about the TemplateId provided in the URL, example response can look like this:
{
"Id":"Id",
"Name":"Name of Template",
"FileType":"Folder/File",
"TemplateKind":"Optional, otherwise it returns Word, Powerpoint or YAML"
}Generate document from template
POST api/template/{templateId}/generate To generate a document from a template, use this call. As with all other calls, the authorization must be in the header.
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:
{
"Sender": "Lars Hansen",
"Message": "Welcome to the DocuMotor documentation",
"Recipients": [
"Klaus",
"Hanne",
"Peter"
]
}Versioned templates
For versioned templates specify the id of the stage for which to generate the document in the header as “stageId”:{stageId}.
Enforce PDF output
To enforce PDF output append specify the header “Accept” with the value being “application/pdf”.
Backup API
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.
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.
List of backups
GET api/backupGets a list of all backups in the unit used for authentication.
Successful response: 200
Response content: list of backups ids (string[])
Create backup
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.
POST api/backup/createBody:
{ "displayName": string } Accepts: application/json
Successful response: 202 Accepted
Response content: Object with log id of the created task.
{ "logId": string } Restore backup
Adds a task for restoring a backup to the global queue. Use the log id to track the status of the task.
PUT api/backup/{backupId}/restoreParameter “backupId” – the id of the backup to restore.
Successful response: 202 accepted
Response content:
{ "logId": string } Download backup
Downloads the provided backup as a zip file.
GET api/backup/{backupId}/downloadParameter “backupId” – the id of the backup to restore.
Successful response: 200
Response content: byte[]/stream
Upload backup
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.
POST api/backup/uploadSuccessful response: 200
Response content:
{ "backupId": string } Backup log info
Gets the info of the log. It contains the data regarding a specific backup task with relevant information included in the response.
Use this endpoint to check the status of the task using the log id received from Upload or Create endpoints.
GET api/backup/log/{logId}Parameter logId is the id of the log to get info of.
Successful response: 200
Response content:
{
"id": string, // Id of log.
"displayName": string, // The display name of the associated backup.
"backupId": string or null, // The id of the associated backup.
"retryCount": int, // Number of times the task has been retried.
"backupType": string, // The type of backup task, can be Create or RestoreUnit.
"status": string, // The current status of the task, can be Scheduled, Running, Failed, Completed or Cancelled.
"statusReason": string, // Message explaining the status.
"timeOfCreation": DateTime, // When the log was created.
"lastHeartbeat": DateTime or null // Heartbeat used to determine if a running task has timed out.
} Backup info
Gets the info of the backup.
GET api/backup/log/{backupId}Successful response: 200
Response content:
{
"id": string, // The id of the backup
"displayName": string, // The display name of the backup
"creationDate": DateTime // The creation date of the backup
}