Process

POST https://api.visualpdf.com/v1/process

Process a pipeline by uploading files and executing the given tasks.

To send files to process as well as the tasks to be performed on these files, you must send the content in multipart/form-data format.

Parameters

Name	Description	Type	Required
files	One or more files to be processed. Each file should be an individual field in the multipart/form-data request. The field names will be the identifiers to use as reference in the tasks, if necessary.	File (multipart/form-data)	Yes
tasks	The tasks to run on the uploaded files with their options.	Array of task objects	Yes
options	Pipeline options (filenames, wait/async, archive, etc.).	Pipeline options object	No

Example

Request (NodeJS)

const myPDF = fs.readFileSync('@/path/to/a/doc.pdf');

const form = new FormData();
form.append('myPDF', myPDF);
form.append('tasks', [
  {
    tool: 'compress',
    options: { level: 'high' },
  },
]);

const requestResponse = await fetch(
  'https://api.visualpdf.com/v1/process',
  {
    method: 'POST',
    body: form,
    headers: { Authorization: `Bearer ${my_API_key}` },
  },
);

Response

{
  pipelineid: '6ecd8c99-4036-403d-bf84-cf8400f67836',
  duration: 823,
  files: [
    {
      name: 'compress_1',
      id: '40e6215d-b5c6-4896-987c-f30f3678f608',
      link: 'https://api.visualpdf.com/v1/download/40e6215d-b5c6-4896-987c-f30f3678f608',
    },
  ],
  status: 'succeeded',
  started: '2024-05-29T16:08:43.511Z',
}

Task object

Name	Description	Type	Required
tool	The identifier of a file processing tool, among those available.	String	Yes
options	Task options. Options vary from task to task.	Object	No
files	The indexes of the files to be processed by this task. By default all files will be taken into account. The index of a file is given by the result of the previous task, or the order of adding files to the query for the first task.	Array of numbers	No

Available tools

add-password: Add PDF password. options
compress: Compress PDF. options
crop-pages: Crop pages. options
delete-pages: Delete pages. options
duplicate-pages: Duplicate pages. options
excel-to-pdf: Excel to PDF. options
images-to-pdf: Images to PDF. options
merge: Merge PDFs. options
order-pages: Order pages. options
pdf-to-images: PDF to images. options
ppt-to-pdf: PowerPoint to PDF. options
remove-password: Remove PDF password. options
rotate-pages: Rotate pages. options
sign: Sign PDF. options
split: Split/extract PDF pages. options
watermark: Add watermark. options
word-to-pdf: Word to PDF. options

Task options

Add PDF password

Name	Description	Type	Required
password	The password that will be used to protect the access to the PDF.	String	Yes

Example

{
  tool: 'add-password',
  options: { password: 'my_sup3r_s3cr3t_pwd' },
}

Compress PDF

Name	Description	Type	Default
level	The level of compression used.	Compression level	medium

Compression levels

low: the PDF quality is remained
medium: images in the PDF may lose slightly quality. This is the default level
high: images in the PDF can lose a lot of quality

Example

{
  tool: 'compress',
  options: { level: 'high' },
}

Crop pages

Name	Description	Type	Required
pages	Page trimming instructions.	Array of page cropping instructions	True

Page cropping instruction

Inherits from Page instruction

Name	Description	Type	Examples	Required
page	Page index.	Number or shortcut	0, last	No, if range is set
range	Pages range.	Array of 2 numbers or shortcuts	[0, 2], ['last-1', 'last']	No, if page is set
box	Cropping box.	Array of coordinates and sizes ([left, top, width, height])	[20, 20, '50w', '70h']	No, if margins is set
margins	Margins of the 4 edges of the page to calculate the cropping area.	Array of sizes ([left, top, right, bottom])	[20, '10h', 20, '10h']	No, if box is set

Example

{
  tool: 'crop-pages',
  options: { pages: [{ page: 'all', box: [10, 20, 300, 200] }] },
}

Delete pages

Name	Description	Type	Required
pages	Pages or ranges to delete.	Array of page instructions	True

Example

{
  tool: 'delete-pages',
  options: { pages: [0, { range: ['last-1', 'last'] }] },
}

Duplicate pages

Name	Description	Type	Required
pages	Page duplication instructions.	Array of page duplication instructions	True

Page duplication instruction

Inherits from Page instruction

Name	Description	Type	Examples	Required	Default
page	Page index.	Number or shortcut	0, last	No, if range is set
range	Pages range.	Array of 2 numbers or shortcuts	[0, 2], ['last-1', 'last']	No, if page is set
duplicates	Number of duplicates to create.	Number	1, 5	No	1
group	When duplicating a range of pages, indicates whether the pages will be inserted consecutively (grouped) or each following its original page.	Boolean	true, false	No	true
position	The position at which the duplicate page will be inserted. In the case of a range duplication, indicates the position of the first duplicate (only if group = true).	Number or shortcut	0, last	No	The original page index + 1

Example

{
  tool: 'duplicate-pages',
  options: { pages: [{ page: 0, duplicates: 2, position: 'last' }] },
}

Excel to PDF

This tool does not offer additional options.

Example

{
  tool: 'excel-to-pdf',
}

Images to PDF

Name	Description	Type	Required	Default
page-size	The size of the generated pages. fit allows you to generate pages of the size of the images, A4 allows you to create an A4 page in which the image is inserted.	String (fit or A4)	No	fit
margins	Margins around images.	Size (for a common margin) or array of sizes ([left, top, right, bottom])	No	0
split	Whether a PDF is created for each image or a single PDF containing all images.	Boolean	No	false

Example

{
  tool: 'images-to-pdf',
  options: {
      'page-size': 'A4',
      margins: '10h',
    }
}

Merge PDFs

Name	Description	Type	Required	Example
order	The order in which the files will be merged. The values correspond to the indexes of the files resulting from the previous task (or the order of adding the files to the pipeline if this task is first).	Array of numbers	No	[1, 0, 2]

Example

{
  tool: 'merge',
  options: { order: [1, 0] },
}

Order pages

Name	Description	Type	Required
pages	Page ordering instructions.	Array of page ordering instructions	True

Page ordering instruction

Inherits from Page instruction

Name	Description	Type	Examples	Required
page	Page index.	Number or shortcut	0, last	No, if range is set
range	Pages range.	Array of 2 numbers or shortcuts	[0, 2], ['last-1', 'last']	No, if page is set
shift	The offset positions to apply to the page or range (positive to move to the end of the file, negative to shift to the beginning).	Number	1, -2	No, if position is set
position	The new position of the page or range. When using a range instruction, the given position indicates the position of the first page, and the next pages in the range will be moved following.	Number (index) or shortcut	2, last-1	No, if shift is set

Example

{
  tool: 'order-pages',
  options: { pages: [{ page: 0, shift: 2 }, { page: 'last', position: 0 }] },
}

PDF to images

Name	Description	Type	Required
pages	Pages or ranges to convert. By default, all the pages will be converted.	Array of page instructions	No

Example

{
  tool: 'pdf-to-images',
  options: { pages: ['all'] },
}

PowerPoint to PDF

This tool does not offer additional options.

Example

{
  tool: 'ppt-to-pdf',
}

Remove PDF password

Name	Description	Type	Required
password	The current password.	String	Yes

Example

{
  tool: 'remove-password',
  options: { password: 'pwd_t0_r3m0v3' },
}

Rotate pages

Name	Description	Type	Required
pages	Page rotation instructions	Array of page rotation instructions	True

Page rotation instruction

Inherits from Page instruction

Name	Description	Type	Examples	Required
page	Page index.	Number or shortcut	0, last	No, if range or current is set
range	Pages range.	Array of 2 numbers or shortcuts	[0, 2], ['last-1', 'last']	No, if page or current is set
current	All pages currently having this rotation value.	Number (0, 90, 180 or 270)	90	No, if page or range is set
rotation	The new rotation of the targeted pages	Number (0, 90, 180 or 270)	180	Yes

Example

{
  tool: 'rotate-pages',
  options: { pages: [{ page: 'all', rotation: 90 }] },
}

Sign PDF

Name	Description	Type	Required
signatures	Signatures to add	Array of signature instructions	True

Signature instruction

Name	Description	Type	Examples	Required	Default
pages	The pages on which to add the signature.	Array of page instructions	[0], [0, 'last'], [{range: [0, 3]}]	Yes
box	Rectangle in which the signature will be contained. Allows you to indicate the position and size of the signature. The signature will occupy as much space as possible in this rectangle and will be centered.	Array of coordinates and sizes ([left, top, width, height])	['90w', '80h', 200, 100]	Yes
file	The field name used in the multipart/form-data request for the signature file. Alternatively, use the text option to add a signature from text.	String	'my-signature'	No, if text is set
text	The text to use to generate a signature or any text content.	String	'Mr. John Doe'	No, if file is set
color	The color of the text in hexadecimal format. Only useful when using the text option.	String	#ff00ff	No	#000000
font	The font of the text, among those available. Only useful when using the text option.	String (font value)	special-elite	No	libre-baskerville
rotation	A rotation to apply to the signature, in degrees.	Number	25	No	0

Example

{
  tool: 'sign',
  options: {
    signatures: [
      {
        box: [30, 50, 150, 100],
        file: 'signature-1',
        pages: ['last'],
      },
    ],
  },
}

Split/extract PDF pages

Name	Description	Type	Examples	Required
cuts	Positions where to cut the original file.	Array of numbers (indexes of pages after which to cut) or shortcuts	[2, 5]	No, if files or interval is set
files	List of files to create from pages.	Array of split file instructions	[{pages: [0, 10]}]	No, if cuts or interval is set
interval	Page interval after which a new cut is created. For sintance, an interval of 2 allows the file to be split every 2 pages.	Number	2	No, if files or cuts is set

Split file instruction

Name	Description	Type	Examples	Required
pages	Pages or ranges to include in that file.	Array of page instructions	[0, 1], [{ range: [2, 8] }, 'last']	Yes

Example

{
  tool: 'split',
  options: { cuts: ['last/2'] },
}

Add watermark

Name	Description	Type	Required
watermarks	Watermarks to add	Array of watermark instructions	True

Watermark instruction

Name	Description	Type	Examples	Required	Default
pages	The pages on which to add the watermark.	Array of page instructions	['all'], [0, 'last'], [{range: [0, 3]}]	Yes
box	Rectangle in which the watermark will be contained. Allows you to indicate the position and size of the watermark. The watermark will occupy as much space as possible in this rectangle and will be centered.	Array of coordinates and sizes ([left, top, width, height])	['90w', '80h', 200, 100]	Yes
file	The field name used in the multipart/form-data request for the watermark file. Alternatively, use the text option to add a watermark from text.	String	'my-watermark'	No, if text is set
text	The text to use to generate a watermark.	String	'Mr. John Doe'	No, if file is set
color	The color of the text in hexadecimal format. Only useful when using the text option.	String	#ff00ff	No	#000000
font	The font of the text, among those available. Only useful when using the text option.	String (font value)	special-elite	No	libre-baskerville
rotation	A rotation to apply to the watermark, in degrees.	Number	45	No	0
opacity	Watermark opacity.	Number (between 0 and 1, 0 being full transparency, and 1 being full opacity)	0.5	No	1

Example

{
  tool: 'sign',
  options: {
    watermarks: [
      {
        box: ['50w', '50h', 300, 300],
        text: 'confidential',
        color: '#ff0000',
        font: 'special-elite',
        rotation: -45,
        opacity: 0.5,
        pages: ['all'],
      },
    ],
  },
}

Word to PDF

This tool does not offer additional options.

Example

{
  tool: 'word-to-pdf',
}

Pipeline options

Name	Description	Type	Default
format	The download format of files generated by the pipeline (separate files or archived in a zip file).	String, file or archive	file
file-names	Pipeline output file names. This array must be based on the order of the files output from the last task in the pipeline. You can include filename shortcuts.	Array of strings	None, file-names-pattern is used by default.
file-names-pattern	A pattern to generate the name of output files. You can include filename shortcuts. If the indicated pattern does not allow having all different file names, a {nb} prefix will be automatically applied.	String	{tool}_{nb}
archive-name	The name of the zip archive file, if format is archive. You can use file-names or file-names-pattern to customize the name of files inside the archive.	String	{tool}
mode	If the query waits for the pipeline to be processed completely to return a result or if the query triggers the pipeline (executed in the background) and immediately returns a result.	Wait mode	wait
webhook-url	Webhook called with a POST request when the pipeline is complete. Only taken into account when mode is async.	String
passwords	Input files passwords. Object whose keys are the names of the fields used for the multipart/form-data files and whose values are the associated passwords.	Object

Filename shortcuts

{nb}: the index of the file, according to the result of the last task
{date}: the current date when the file was generated by the API
{tool}: the name of the last tool of the pipeline

Wait modes

wait: the request will wait until the pipeline is completely finished to return a result.

Response example

{
  pipelineid: '6ecd8c99-4036-403d-bf84-cf8400f67836',
  duration: 823,
  files: [
    {
      name: 'compress_1',
      id: '40e6215d-b5c6-4896-987c-f30f3678f608',
      link: 'https://api.visualpdf.com/v1/download/40e6215d-b5c6-4896-987c-f30f3678f608',
    },
  ],
  status: 'succeeded',
  started: '2024-05-29T16:08:43.511Z',
}

async: the request will return a result as soon as the pipeline has started. webhook-url will be called when the pipeline is completed, with a body in the format of a wait mode response.
Response example
```
{
  pipelineid: '6ecd8c99-4036-403d-bf84-cf8400f67836',
  'webhook-url': 'https://your-domain.com/visual-pdf-webhook',
  status: 'running',
  started: '2024-05-29T16:08:43.511Z',
}
```

Errors

HTTP code	Description
400 - Bad Request	The request was unacceptable, often due to missing or incompatible parameters or tasks.
401 - Unauthorized	No valid API key provided.
403 - Forbidden	The API key doesn't have permissions to perform the request, often due to insufficient number of credits.
429 - Too Many Requests	Too many requests hit the API too quickly.
5xx - Server Errors	Something went wrong on our end.

Process

Parameters

Example

Request (NodeJS)

Response

Task object

Available tools

Task options

Add PDF password

Compress PDF

Crop pages

Delete pages

Duplicate pages

Excel to PDF

Images to PDF

Merge PDFs

Order pages

PDF to images

PowerPoint to PDF

Remove PDF password

Rotate pages

Sign PDF

Split/extract PDF pages

Add watermark

Word to PDF

Pipeline options

Errors

Request workflow

Download