This tutorial shows how to use Plumsail Documents API.
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.
We recommend you to review the API reference. The API is split into a few sections:
Convert - All operations for converting documents.
Generate - All operations for creating documents from templates.
PDF - Utility operations on PDF files. For example, split, merge, and protect PDF files.
UserAPI - This method returns information about the current Plumsail account and subscription details.
Watermark - All operations for adding watermarks to PDF files.
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:
RestSharp for C#
Invoke-RestMethod cmdlets for PowerShell
request - Simplified HTTP client for node.js
Requests: HTTP for Humans for Python
Guzzle for PHP
There are two ways to work with API:
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.
This approach is good for processing a small amount of data and for testing purposes. If your request is can’t be processed in 30 seconds our service will return an error. Thus, if you want to process a large amount of data it is better to use the second option with jobs.
All jobs are placed under /jobs/ path. You may notice it in the API reference. The rest of the methods return results right in the response.
Below is the example of a curl request to create a document from the DOCX template without using jobs. The request returns the result immediately.
curl --location --request POST 'https://api.plumsail.com/api/v2/generate/from-docx' \
--header 'Authorization: YOUR_API_KEY' \
--form 'File=@/D:/Temp/template-file.docx' \
--form 'Data={ "firstName": "Derek", "lastName": "Clark"}' \
--form 'Locale=en-US'
--form 'Timezone=America/Los_Angeles'
You can specify several parameters:
Authorization header. Pass your API key as the value by replacing YOUR_API_KEY with your actual key.
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.
Data form value. It is a JSON object with values that will be applied to the document template.
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 formatter 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.
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:
curl --location --request POST 'https://api.plumsail.com/api/v2/generate/jobs/from-docx' \
--header 'Authorization: YOUR_API_KEY' \
--form 'File=@/D:/Temp/template-file.docx' \
--form 'Data={ "firstName": "Derek", "lastName": "Clark"}' \
--form 'Locale=en-US'
--form 'Timezone=America/Los_Angeles'
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://api.plumsail.com/api/v2/generate/jobs/from-docx/0HM0M6S9HO2SN72E293925ab",
"date": "Thu, 21 Sep 2017 16:11:07 GMT",
"x-jobid": "0HM0M6S9HO2SN72E293925ab",
"content-length": "0"
}
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/0HM0M6S9HO2SN72E293925ab
Where 0HM0M6S9HO2SN72E293925ab 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 see results.
{
"link": "https://URL_OF_THE_RESULT_FILE"
}