Documentation › Use as REST API

Use as REST API

This tutorial shows how to use Plumsail Documents API.

Create an API key

Just follow the steps described in this topic. You will pass the API key as the Authorization HTTP header in your requests to the API.

Review reference for API that you want to call

You can find the API reference by one of these links depending on your data center location:

You can aslo change the region directly in the Swagger UI:

Swagger region selector

The API is split into a few sections depending on the type of operations. The links below are examples for the European Union region. Please remember to use links according to your region.

  • Archive - All operations for working with archives. For example, add files to a ZIP archive or extract files from it.

  • Convert - All operations for converting documents.

  • Docx - All operations for merging DOCX files.

  • Generate - All operations for creating documents from templates.

  • Pdf - Utility operations on PDF files. For example, split, merge, and protect PDF files.

  • Processes - Operations for starting Processes.

  • UserAPI - This method returns information about the current Plumsail account and subscription details.

  • Watermark - All operations for adding watermarks to PDF files.

  • Xlsx - All operations for merging XLSX files.

Use API from your programming language

Our API is REST-based. Thus, you can use any programming language that can execute web requests. For example, you would use C#, PowerShell, node.js, Python, PHP.

There are a lot of ready to use helper REST API clients for those languages. Here are just a few of them:

Learn two ways to call API

There are two ways to work with API:

  1. Call a method and get the result immediately

  2. Start a job and get the result once the job is finished

The first way is good for light operations. When execution of the method doesn’t take a lot of time. You just call an API method and receive a response with results.

The second way is good if you want to perform a long-running operation. For example, convert a large file. You just start a conversion job and then download the result once the job is finished.

Call a method and get the result immediately

This approach works well for processing a small amount of data or for testing purposes. If your request cannot be processed within 30 seconds, our service will return an error. Therefore, if you need to process a large amount of data, it’s better to use the second option with jobs.

All jobs are located under the /jobs/ path, as you can see in the API reference. The other methods return results directly in the response.

Below is an example of a curl request that creates a document from a DOCX template without using jobs. The request returns the result immediately.

Note

Please use the following URLs in the code for US and AU regions:

curl -X 'POST' \
 'https://eu-api.plumsail.com/api/v2/generate/from-docx' \
  -H 'accept: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'Locale=en-US' \
  -F 'Timezone=Europe/Budapest' \
  -F 'Engine=Classic' \
  -F 'Data={\"firstName\": \"Derek\", \"lastName\": \"Clark\"}' \
  -F 'File=@/D:/Temp/template-file.docx'

And this is HTTP representation for it:

POST https://eu-api.plumsail.com/api/v2/generate/from-docx
Authorization: YOUR_API_KEY
Accept: application/json
Content-Type: multipart/form-data

Locale: en-US
Timezone: Europe/Budapest
Engine: Classic
Data: {"firstName": "Derek", "lastName": "Clark"}
File: '/D:/Temp/template-file.docx'

You can specify several parameters:

  • Authorization header. Pass your API key as the value by replacing YOUR_API_KEY with your actual key.

  • Engine form value. It defines how your template is processed when generating a document. You can find more details about available engines in Modern vs. Classic DOCX engine.

  • Data form value. It is a JSON object with values that will be applied to the document template.

  • File form value. It is the path to your DOCX template file. If you have the file available online you can use the FileUrl parameter instead of the File. You can pass the URL of a file available for anonymous access.

  • Locale form value. Define the locale to format dates, numbers, and currencies in the resulting document.

  • Timezone form value. This parameter defines the current date and time for the {{@date}} token in the document. It’s also applied to the format function when its output is a date. The timezone identifiers follow the IANA standard format: {AREA}/{LOCATION}. You can find the complete list of available timezones here.

This is just an example. Other methods in the API may have different parameters but the Authorization header is required for all requests.

Once the request is executed you will get an object with the link property inside. It will contain the URL of the generated document. You can download it to see results.

{
  "link": "https://URL_OF_THE_RESULT_FILE"
}

You can use other programming languages to send requests to the API.

Start a job and get the result once the job is finished

You may notice that some methods in API reference are located under /jobs/ path. For example, the method below starts the job of creating a DOCX document from template:

/api/v2/generate/jobs/from-docx

The curl for starting the job is almost the same as in the previous section of this article. The only difference, we added the jobs part.

Note

Please use the following URLs in the code for US and AU regions:

curl -X 'POST' \
 'https://eu-api.plumsail.com/api/v2/generate/jobs/from-docx' \
  -H 'accept: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'Locale=en-US' \
  -F 'Timezone=Europe/Budapest' \
  -F 'Engine=Classic' \
  -F 'Data={\"firstName\": \"Derek\", \"lastName\": \"Clark\"}' \
  -F 'File=@/D:/Temp/template-file.docx'

And the same with the HTTP request representation:

POST https://eu-api.plumsail.com/api/v2/generate/jobs/from-docx
Authorization: YOUR_API_KEY
Accept: application/json
Content-Type: multipart/form-data

Locale: en-US
Timezone: Europe/Budapest
Engine: Classic
Data: {"firstName": "Derek", "lastName": "Clark"}
File: '/D:/Temp/template-file.docx'

Once the job is created the method returns response message Accepted with code 202. It means the job has been created and the generation of a document is in progress. There is the location header present in the response. It contains a URL where the result of job execution will be available. This is the example response:

{
    "status": "202",
    "location": "https://eu-api.plumsail.com/api/v2/generate/jobs/from-docx/0HNGIGCSUV9KB4f519cde",
    "date": "Fri,24 Oct 2025 12:33:45 GMT ",
    "x-jobid": "0HNGIGCSUV9KB4f519cde",
}

A URL with the result is usually the same as the URL of the original job plus ID of the job. Example:

https://api.plumsail.com/api/v2/generate/jobs/from-docx/0HNGIGCSUV9KB4f519cde

Where 0HNGIGCSUV9KB4f519cde is an ID of the job.

All you need to do now is to execute the GET request for the URL from the location header. If the result is not ready yet, it returns the Accepted message and 202 code with the same location header again. If the result is ready it returns an object with the link property inside. It will contain the URL of the generated document. You can download it to view the results.

{
  "link": "https://URL_OF_THE_RESULT_FILE"
}
Previous
Use utils actions in Integrately
Next
Examples API request using different programming languages