 API

With DiMaker's API, you can create files with personalized data and optionally deliver them to recipients. API requests can be initiated from another server or directly from a browser using CORS requests.

Getting Started

In the Integration – API Tokens section, obtain a Secure token for API requests and enable its usage. Additionally, you need to create a document with placeholders for personalized data, prepare an email template for distribution, and set up a folder in the Drive for the created files.

File Creation

To generate files, send POST-DATA, POST-, or GET requests to the address
https://dimaker.app/api/v1/create/
with the required parameters below.
Request encoding must be UTF-8, and required fields are marked with an asterisk.

• secure*

  Secure token (string, 36 characters)

• doc_id*

  ID of the document (string, 36 characters) to be used for file creation. The document ID can be found in the address bar when the document is opened. The document must not be in the trash but can reside in any folder within Documents.

• mask*

  A string containing all variables for replacement in the form of key (placeholder) - value (text for substitution). It can include data for creating multiple files (no limit on quantity).
  Example for a single file:
  [{"%name": "Ivanov", "%points":"100"}]
  Example for multiple files:
  [{"%name": "Ivanov", "%points":"100"}, {"%name": "Petrov", "%points":"200"}, {"%name": "Sidorov", "%points":"300"}]
  To specify an email address, use %email. For file names, use %filename. To send files to multiple email addresses, list them separated by commas. Email sending status in the Drive will be displayed based on the first address.
  Double quotes must be used as per standards. If a value contains quotes, they need to be escaped.

  For embedding an image, use either a direct link (http:// or https://) or a Base64-encoded image. In the latter case, the string should start with "data:image/".

  Alternative Method
  If sending a string is not an option, use query parameters for replacements. Each replacement variable must start with a "mask_" prefix, such as mask_name, and store the replacement value. The document will replace variables based on the suffix. For instance, mask_name corresponds to the variable %name. Specify the email address using mask_email and file name with mask_filename.

• mail_id

  Email template ID (string, 36 characters) to use for distribution. This ID can be obtained from the address bar when the template is open. If this parameter is not provided, no email will be sent.

• email_send

  Specifies when to send the email with the file. Possible values are:
  onfinish - Send all emails after creating all files (default)
  oncreate - Send emails immediately after each file is created. For a single file, onfinish and oncreate work the same.
  timeout - Schedule emails to be sent after a delay. In this case, you must also provide two parameters:
  email_timeout_value - Numeric duration for the delay (integer value)
  email_timeout_unit - Unit of time for the duration. Values can be "m" (minutes), "h" (hours), "d" (days).
  Alternatively, for exact sending time, pass a timestamp in email_timeout_timestamp (Unix time format). If both timeout and email_timeout_timestamp are provided, the timestamp takes priority.

• folder_id

  Drive folder ID (string, 36 characters) where files will be saved. If the folder does not exist, it will be created automatically during the first file generation.

• page_id

  Sheet number (number or string) to use if the document has multiple pages. You can pass a single number (first sheet is 0) or multiple sheet numbers separated by commas.

• result

  Determines the format of the returned result. Possible values are:

  • Not provided. Returns a string with the request result (see below).
  • link. On success, returns a string with the link to the created file (or the first file, in case of multiple files). To retrieve the file, use the provided link. File preparation can take 1-5 seconds per file. Until the file is ready, requests to this link will return a 404 error. If no file is created, a error string is returned (see below).
  • file. On success, returns the created file (only the first file in case of multiple files). Since file preparation takes 1-5 seconds, the response will only occur once the file is ready. A high API request load may increase file preparation time. If the file is not ready within 30 seconds, a 404 error is returned (though the file generation request will eventually complete). For frequent API requests, avoid using this parameter.

Result

The server will return a string with the following possible values:

• result

  The outcome of the request. Possible values are:
  error - The request encountered an error. No files were created.
  success - The files were successfully created. Depending on your API usage scenario, you can notify users about the successful creation or display a file download form.

• create_id

  Generation ID, available only on a successful request. Useful for further requests to the API.

• files

  An array containing the IDs of the created files, available only on a successful request. To retrieve the file in JPG format, use https://dimaker.app/getfile/{ID}/. To download as PDF, add pdf/ to the URL. While the file ID is returned immediately, file preparation may take 1-5 seconds per file. Until the file is ready, requests to https://dimaker.app/getfile/{ID}/ will return a 404 error.

• url

  A URL string for displaying a file download widget, available only on a successful request. Create an iframe using this URL. Directly navigating to the URL will not yield results. The domain of the site where the file is accessed must be configured correctly in the API settings.
  File creation takes approximately 1 second per file, plus a few seconds for group processing. You can display the widget iframe immediately after sending the request. If file creation is incomplete, a respective message will appear. Once the files are ready, download options will become available.
  To display the download widget in a modal overlay, create an iframe with the following additional styles: position:fixed; width:100%; height:100%; top:0; bottom:0; right:0; left:0; z-index:10000; background: rgba(0, 0, 0, 0.72); and append it to the body with the URL parameter ?view=modal.

• error_text

  Available only in case of an error. Text description of the error. Possible issues include invalid Secure token, replacement mask, document ID, email template ID, Drive folder ID, or a server-side error.

Example of successful request response:
{
"result":"success",
"create_id":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"url":"https://embed.dimaker.app/widgets/get/927ebf68-2f55-4b20-a18c-c1171ee113db/b4caf05b-6757-4d9c-b4bc-1924a9b31796/",
"files":[
"369dc61e-40c2-46c0-81f4-e31ca8c33cc2",
"d94c6efb-0076-438b-bb84-fead9c1ae556",
"716e1081-c8ee-442b-b0b0-0681b2ed5d90"
]
}

Creating Multiple Files in One Request

With one request, you can create multiple files from different documents. This can be useful, for example, when you need to generate certificates in multiple languages from different templates. By sending a single request, the server will handle the creation of all necessary files.

To make such a request, the doc_id field should be an array (use doc_id[] as the variable name). Accordingly, multiple doc_id[] variables can be used in a single request to generate multiple files. Other fields like mail_id, email_send, and folder_id can also be arrays to assign specific templates, send times, or save locations for each file. If customization is not needed, only the doc_id field needs to be an array.

For instance, to create two files from different documents and save them in separate folders on the Drive, you would use two doc_id[] variables and two folder_id[] variables (in the same order). Additionally, if both files should be sent in a single email, provide a single mail_id and configure email_send[] as "manual" first and "oncreate" afterward. This ensures the email is sent after both files have been created.

Sending a File to Yourself

The generated file can be sent to your account's email address immediately after creation. In the "Email Template" field, you can select a template to use for sending. You can create a dedicated template for such emails in the Email Templates section. By including the variable %data in the email body, a table containing all file data will be inserted at that location.

Deleting Files

To delete files, send POST-DATA, POST-, or GET requests to the address
https://dimaker.app/api/v1/drive/files/delete/
with the required parameters below.
Request encoding must be UTF-8, and required fields are marked with an asterisk.

• secure*

  Secure token (string, 36 characters)

• file_id

  ID of the file (string, 36 characters) to be deleted. The file ID can be found in the files array returned by the API during file creation. The file must not be in the trash.

  OR

• file_ids

  An array of file IDs (string, 36 characters each) if multiple files need to be deleted in a single request.

  OR

• create_id

  Generation ID (string, 36 characters) if the file was created via the API. The generation ID can be used instead of file_id or file_ids. This will remove all files associated with the generation ID. The generation ID is included in the create_id field returned during file creation.

• delete_forever

  Specifies whether to permanently delete the file without moving it to the trash. By default, files are moved to the trash. Valid values are:

  • 0 - Move to trash (default)
  • 1 - Permanently delete

  Files in the trash are automatically deleted after 60 days.

Example

Example of a correct request to delete files:
{
"secure":"b4caf05b-6757-4d9c-b4bc-1924a9b31796",
"file_id":"369dc61e-40c2-46c0-81f4-e31ca8c33cc2"
}

Result

The server will return a string with the following possible values:

• result

  The outcome of the request. Possible values are:
  error - The request encountered an error. No files were deleted.
  success - Successful request for file deletion.

• files

  An array containing the IDs of deleted files, available only on a successful request.

• error_text

  Available only in case of an error. Text description of the error. Possible issues include invalid Secure token, file ID, generation ID, or a server-side error.

Example of a successful request response:
{
"result":"success",
"files":["369dc61e-40c2-46c0-81f4-e31ca8c33cc2"]
}

---

Other Integrations