API 2.0

CloudPDF API Reference

CloudPDF is a cloud-based PDF management service. It enables users to upload, store, secure, track and deliver PDFs for your website.

In this API reference we will explain how to interact with our Server API. You will need this API if you want to upload or change, for example, documents on CloudPDF through your application.

If you are looking for information on implementing the client side viewer please follow the viewer SDK documentation.

Don't hesitate to contact us through the chat in the right bottom corner if you have questions.

Client Libraries
Node
PHP
Ruby
$ npm install @cloudpdf/api
NODE

Base URL

All API requests should be done to our base URL

Base URL
https://api.cloudpdf.io

Authentication

CloudPDF uses API keys to allow access to the API. You can find the API key in your Dashboard → Settings → API Keys.

CloudPDF expects the API key to be included in all API requests to the server in a header that looks like the following:

X-Authorization: API_KEY

To verify if your authentication and request is valid you can use this endpoint. If the authorization is successful it will respond with the message "Authorized"

There are two methods of authentication for the API. They are simple authentication and signed authentication.

Name: APIV2GetAuth
Endpoint
GET
/v2/auth
Sample Response
{
    "message": "Authorized",
    "organizationName": "ACME Company LTD"
}

Simple authentication

You can find the simple authentication API key in your Dashboard → Settings → API Keys.

Copy the API key with the name Simple API Key

You can use this API key directly in the X-Authorization header. Please be aware that the API is exposed on every API request - make sure you don't use Simple authentication on the client side.

If you don't want the API key to be exposed on every API request we suggest you to use Signed authentication.

Signed authentication

You can find the signed authentication API keys in your Dashboard → Settings → API Keys.

Copy the API keys with the name Secret Signing Key and Cloud Name.

We use JWT (JSON Web Tokens) to generate a signed token. You can learn on how to generate a JWT in your coding language here: https://jwt.io/.

Make sure to include the Cloud Name as kid in the JWT header.

You should sign the JWT header and payload with the Secret Signing Key and include the full JWT token in the X-Authorization header.

Sample JWT Header
{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "pXBZfeF1I" // add your cloud name here
}
Sample JWT Body
{
  "function": "APIV2GetAuth", // add the function name here
  "params": {}, // include all the parameters of the request here
  "iat": 1652954293,
  "exp": 1662997493
}

Account

To check your account status at any time you can use this endpoint. It will respond with your quota levels and current usage levels. Usage resets every 30 days.

Name: APIV2GetAccount
Endpoint
GET
/v2/account
Sample Response
{
    "organizationName": "ACME Company LTD",
    "plan": "Professional",
    "allowedMonthlyUploads": 100,
    "usedMonthlyUploads": 36,
    "allowedMonthlyViews": 1999,
    "usedMonthlyViews": 130,
    "allowedStorage": 1073741824,
    "usedStorage": 95751557
}

Errors

The CloudPDF API uses the following status / error codes.

200OK
202Accepted -- Your request is has been accepted for processing
400Bad Request -- Your request is invalid
401Unauthorized -- Your API key is wrong
402Payment Required -- Your have run out of your plans quota.
403Forbidden -- Unauthorized request.
404Not Found -- The specified resource can not be found

The document object

These are the attributes of the document object

Attributes

idstring

The identifier of the document

namestring

The name of the document

descriptionstring

Description of the document

fileobject

The PDF file

File
idstring

The identifier of the file

statusstring

The current status of the file; WaitingUpload, Processing, Failed, Completed

uploadUrlstring

A pre-signed URL where you can upload your PDF to. This field will only be populated on creation of the document.

defaultPermissionsobject

These are the default document permissions

defaultPermissions
downloadstring

Options are: "NotAllowed", "Allowed", "EmailRequired"

searchboolean

Is search allowed in the document

selectionboolean

Is selection allowed in the document

infoarray

Require info to open a document. Set as an array with possible options: "email", "name", "organization", "phone"

publicboolean

If true, the document is publicly accessible. If false the document is not publicly accessible.

Example Object
{
    "id": "5e6665b0-c276-494f-abfc-01e7b1151461",
    "name": "test.pdf",
    "description": "test document",
    "file": {
        "id": "804ac929-7c46-404f-a166-72c6b3cea049",
        "status": "WaitingUpload",
        "uploadUrl": "https://cloudpdf-document-dev.s3.amazonaws.com/804ac929-7c46-404f-a166-72c6b3cea049.pdf?Content-Type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJVXNAZ5KS7UKHXEA%2F20220516%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220516T214206Z&X-Amz-Expires=900&X-Amz-Signature=0fe718742a0bab2cff698f1c16c47d1c27fed63afbf5249b89d736e2d12dd4d6&X-Amz-SignedHeaders=host",
        "thumbnail": null,
        "size": null
    },
    "defaultPermissions": {
        "download": "Allowed",
        "search": true,
        "selection": true,
        "info": null,
        "public": true
    }
}

Create a document

Before you can upload a PDF to CloudPDF you must create a new document.

The server will return a pre-signed upload URL where you can upload your PDF file.

After uploading the file you must notify our server that the upload is finished and we will process the PDF by our PDF engine.

Parameters

namestringRequired

The name of the PDF you want to upload.

descriptionstring

Description of the PDF you want to upload.

parentIdstring

The ID of the folder you want to create the document in.

tagsarray

Set tags on the document to easily filter and search documents later

defaultPermissionsobject

Set the default permissions for this document. If none are given we use the default permissions of the organization. You can change the default permissions of the organization in the Dashboard → Settings → Upload Settings.

defaultPermissions
downloadstring

Options are: "NotAllowed", "Allowed", "EmailRequired"

searchboolean

Is search allowed in the document

selectionboolean

Is selection allowed in the document

infoarray

Require info to open a document. Set as an array with possible options: "email", "name", "organization", "phone"

publicboolean

If true, the document is publicly accessible. If false the document is not publicly accessible.

Name: APIV2CreateDocument
Endpoint
POST
/v2/documents
Sample Request
var data = {
  "name" : "sales_document.pdf",
  "parentId" : "ac3429c6-07c1-4123-89e2-0acb558b74b7",
  "tags": ["sales"],
  "defaultPermissions": {
    "search": false,
    "selection": false,
    "public": true,
    "download": "NotAllowed"
    "info": ["email"]
  }
}
fetch('https://api.cloudpdf.io/v2/documents', {
  method: 'POST',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'X-Authorization' : API_KEY
  }
})

Retrieve a document

Parameters

idstringRequiredURL Parameter

The identifier of the document

Name: APIV2GetDocument
Endpoint
GET
/v2/documents/:id
Sample request
fetch(`https://api.cloudpdf.io/v2/documents/${ID}`, {
  method: 'GET',
  headers: {
    'X-Authorization' : API_KEY
  }
})

Update a document

Parameters

idstringRequiredURL Parameter

The identifier of the document you want to update

descriptionstring

A description of the document

parentIdstring

The ID of the folder you want to move the document to

tagsarray

Tags to easily find this document later

defaultPermissionsobject

The default permissions for this document. If none are given we use the default permissions of the organization. You can change the default permissions of the organization in the Dashboard → Settings → Upload Settings.

defaultPermissions
downloadstring

Options are: "NotAllowed", "Allowed", "EmailRequired"

searchboolean

Is search allowed in the document

selectionboolean

Is selection allowed in the document

infoarray

Require info to open a document. Set as an array with possible options: "email", "name", "organization", "phone"

publicboolean

If true, the document is publicly accessible. If false the document is not publicly accessible.

Name: APIV2UpdateDocument
Endpoint
PUT
/v2/documents/:id
Sample Request
var data = {
    "name": "test.pdf",
    "description": "test document",
    "tags": ["test", "test1"],
    "defaultPermissions": {
        "info": ["email"],
        "download": "NotAllowed",
        "public": true,
        "selection": false,
        "search": true
    }
}
fetch(`https://api.cloudpdf.io/v2/documents/${ID}`, {
  method: 'PUT',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'X-Authorization' : API_KEY
  }
})

Delete a document

Parameters

idstringRequired

The identifier of the document

Name: APIV2DeleteDocument
Endpoint
DELETE
/v2/documents/:id
Sample Request
fetch(`https://api.cloudpdf.io/v2/documents/${ID}`, {
  method: 'DELETE',
  headers: {
    'X-Authorization' : API_KEY
  }
})

Create new file version

When you have a new version of your PDF. You can upload it to an already existing document without having to create a new one.

Parameters

idstringRequiredURL Parameter

The document identifier.

namestringRequired

The name of the PDF you want to upload.

Name: APIV2CreateDocumentFile
Endpoint
POST
/v2/documents/:id/files
Sample request
var data = {
  "name" : "sales_document.pdf"
}
fetch(`https://api.cloudpdf.io/v2/documents/${ID}/files`, {
  method: 'POST',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'X-Authorization' : API_KEY
  }
})

Upload file

After you create a document you will receive an Amazon signed URL where you can upload your PDF file. We suggest to upload the file directly from the clients browser to spare your server load. You can look at the example using Axios in TypeScript.

When the file upload is finished you must notify our server.

Sample request
import axios from 'axios';
axios.put(signedUploadURL, file, {
  headers: {
    "Content-Type": "application/pdf"
  },
  onUploadProgress: (e) => {
    //  Show progress
    const percentComplete = Math.round((e.loaded * 100) / e.total);
    console.log(percentComplete);
  },
});

Upload file completed

After uploading your file to Amazon S3 you must notify our server on this endpoint that the upload is complete. On a successful request the status of the document will change from "WaitingUpload" to "Processing".

You can poll the GET endpoint for status updates or use a webhook to find out if your document has completed processing by our PDF engine.

Parameters

idstringRequiredURL Parameter

The identifier of the document

fileIdstringRequiredURL Parameter

The identifier of the file

uploadCompletedboolean

Notify the server that you uploaded the PDF file to the Amazon S3 bucket

Name: APIV2PatchDocumentFile
Endpoint
PATCH
/v2/documents/:id/files/:fileId
Sample request
var data = {
  "uploadCompleted" : true
}
fetch(`https://api.cloudpdf.io/v2/documents/${ID}/files/${FILEID}`, {
  method: 'PATCH',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'X-Authorization' : API_KEY
  }
})

Retrieve a file

Parameters

idstringRequiredURL Parameter

The identifier of the document

fileIdstringRequiredURL Parameter

The identifier of the file

Name: APIV2GetDocumentFile
Endpoint
GET
/v2/documents/:id/files/:fileId
Sample Request
fetch(`https://api.cloudpdf.io/v2/documents/${ID}/files/${FILEID}`, {
  method: 'GET',
  headers: {
    'X-Authorization' : API_KEY
  }
})

Viewer document

This is the endpoint the CloudPDF viewer calls to render the document. In general we do not recommend using this endpoint. We put it in the API reference to give you clarity on how to generate the signed JWT token.

You can only call this endpoint with a signed token or without token for public documents.

This endpoint will not allow simple token authentication.

Parameters

idstringRequiredURL Parameter

The identifier of the document

downloadstring

Options are: "NotAllowed", "Allowed", "EmailRequired". This parameter only has effect in combination with a signed JWT token. If no JWT token is included in the request, the default permissions will be returned.

searchboolean

Is search allowed in the document. This parameter only has effect in combination with a signed JWT token. If no JWT token is included in the request, the default permissions will be returned.

selectionboolean

Is selection allowed in the document. This parameter only has effect in combination with a signed JWT token. If no JWT token is included in the request, the default permissions will be returned.

infoarray

Require info to open document. Should be send in an array. Possible options are: email, phone, organization, name. This parameter only has effect in combination with a signed JWT token. If no JWT token is included in the request, the default permissions will be returned.

Name: APIGetDocument
Endpoint
GET
/v2/viewer/documents/:id
Sample Request
var data = {
    "search": false,
    "selection": true,
    "download": "NotAllowed",
    "info": ["email"]
}
fetch(`https://api.cloudpdf.io/v2/viewer/documents/${ID}`, {
  method: 'GET',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'X-Authorization' : SIGNED_JWT_TOKEN
  }
})

Generate viewer token

You can find the signed authentication API keys in the Dashboard → Settings → API Keys.

Copy the API keys with the name Secret Signing Key and Cloud Name.

We use JWT (JSON Web Tokens) to generate a signed token. You can learn how to generate a JWT in your coding language here: https://jwt.io/.

Make sure to include the Cloud Name as kid in the JWT header.

You should sign the JWT header and payload with the Secret Signing Key and include the full JWT token in the X-Authorization header.

Example JWT Header
{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "pXBZfeF1I" // add your cloud name here
}
Example JWT Body
{
  "function": "APIGetDocument",
  "params": {
    "id": "cff8e851-69f9-4e77-ae91-749ef48a889f",
    "download": "NotAllowed",
    "selection": true,
    "search": false
  },
  "iat": 1652954293,
  "exp": 1662997493
}

Webhooks

Webhooks are used to notify your system of specific CloudPDF events.

Endpoints
POST/v2/webhooks
GET/v2/webhooks/:id
PUT/v2/webhooks/:id
DELETE/v2/webhooks/:id
GET/v2/webhooks

The webhook object

Attributes

idstring

The identifier of the webhook

namestring

The name of the webhook

secretstring

This is the secret that will be sent with the request as a query string. You can use it to protect your webhook endpoint.

enabledboolean

If false the webhook is disabled, if true the webhook is active.

urlstring

The URL that the webhook will request when an event is triggered

headersobject

The headers that will be sent with the webhook request

eventsarray

The events that will trigger the webhook URL

Events
namestring

The name of the event

slugstring

The slug of the event

Sample object
{
    "id": "1",
    "name": "Test",
    "secret": "",
    "enabled": true,
    "url": "https://yourendpoint.com/webhook-event",
    "headers": {},
    "events": [
        {
            "name": "A document is updated",
            "slug": "document.updated"
        }
    ]
}

Create a webhook

Parameters

namestringRequired

The name of your webhook for your own reference

urlstringRequired

The URL that the webhook should trigger on a event

secretstring

Optional secret that you can use to secure the webhook endpoint

eventsarray

An array of events. Possible values are: document.created, document.updated, collection.created, collection.updated, tracker.new, lead.new, file.processed

headersobject

Object of header keys and values that will be sent as request header on the webhook request

Name: APIV2CreateWebhook
Endpoint
POST
/v2/webhooks
Sample Request
var data = {
    "name": "Test webhook 2",
    "url": "https://yourdomain.com/webhook-endpoint",
    "secret": "a secret password",
    "events": ["document.created", "document.updated", "collection.created"]
}
fetch('https://api.cloudpdf.io/v2/webhooks', {
  method: 'POST',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'X-Authorization' : API_KEY
  }
})

Retrieve a webhook

Parameters

idintegerRequiredURL Parameter

The identifier of the webhook

Name: APIV2GetWebhook
Endpoint
GET
/v2/webhooks/:id
Sample Request
fetch(`https://api.cloudpdf.io/v2/webhooks/${ID}`, {
  method: 'GET',
  headers: {
    'X-Authorization' : API_KEY
  }
})

Update a webhook

Parameters

idintegerRequiredURL Parameter

The identifier of the webhook you want to update

namestringRequired

The name of the webhook for your own reference

urlstringRequired

The URL that the webhook should trigger on a event

secretstring

Optional secret that you can use to secure the webhook endpoint

eventsarray

An array of events on which the webhook will be triggered. Possible values are: document.created, document.updated, collection.created, collection.updated, tracker.new, lead.new

headersobject

Object of header keys and values that will be sent as request header on the webhook request

Name: APIV2UpdateWebhook
Endpoint
PUT
/v2/webhooks/:id
Sample request
var data = {
    "name": "Test webhook 2",
    "url": "https://yourdomain.com/webhook-endpoint",
    "secret": "a secret password",
    "events": ["document.created", "document.updated", "collection.created"]
}
fetch(`https://api.cloudpdf.io/v2/webhooks/${ID}`, {
  method: 'PUT',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'X-Authorization' : API_KEY
  }
})

Delete a webhook

Parameters

idintegerRequiredURL Parameter

The identifier of the webhook you want to delete

Name: APIV2DeleteWebhook
Endpoint
DELETE
/v2/webhooks/:id
Sample request
fetch(`https://api.cloudpdf.io/v2/webhooks/${ID}`, {
  method: 'DELETE',
  headers: {
    'X-Authorization' : API_KEY
  }
})

List all webhooks

Name: APIV2GetWebhooks
Endpoint
GET
/v2/webhooks
Sample request
fetch(`https://api.cloudpdf.io/v2/webhooks`, {
  method: 'GET',
  headers: {
    'X-Authorization' : API_KEY
  }
})