Pagination API (1.2 - 2024/09/24)

Download OpenAPI specification:Download

Introduction

The Pagination API is an easy way to create a document.
From a structured data file and a specific layout, the API returns a link to download the document (PDF and InDesign format).
The process is asynchronous.

Base URL

The base URL for all endpoints is: https://api.pagination.com/vpc

Usage quick guide

Create a new project by selecting a layout (project_class).
Launch the pagination prcess by attaching a data file to the request; you can personalize the Pagination.
Upon completion the user will receive a notification (e.g. email, webhook) with the link to the output zip package.

Get started & main documentation

If you'd like to get started now, try out our demo project introduction!
That is a nice place also if you'd like to look deeper into the process workflow and the process requisites (e.g. datafile structure).

Authentication

api-key

Security Scheme Type	API Key
Header parameter name:	x-api-key

Projects endpoints

Create Project

The method creates a new project from a chosen project_class template and returns the unique project_id that is needed to launch the pagination process.

Authorizations:

api-key

Request Body schema: application/x-www-form-urlencoded

project_class required	string The layout name for the document. Check out the full documentations to discover our layout classes.
project_name required	string The name of the project document. It is used to generate a unique id for your project in our database. The name can be "price list", "catalog", "brochure", etc.
email required	string The email of the project's owner. This email uniquely identify the user. It define the "user_id" (in response). All subsequent api calls should have this parameter as a header parameter. This address is also used to receive standard email notifications.
customer	string Just a label for the customer; it groups users together (e.g. "Company XYZ"). Defaults to the user_id.
webhook	string Push notifications are sent to this URL (POST messages).

Responses

200

put/projects

https://api.pagination.com/vpc/projects

Request samples

Payload

Content type

application/x-www-form-urlencoded

Copy

email=email%40gmail.com&project_class=demo&project_name=netsuite-demo&customer=Company%20XYZ

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"status": "creation complete",
"project_id": "netuiste-demo-23",
"user_id": "[email protected]",
"project_class": "demo",
"project_name": "netsuite-demo",
"customer": "Company XYZ"
}

Launch Project

This method launches a pagination process to create a new document.

Authorizations:

api-key

header Parameters

user_id

required

string

The "user_id" parameter returned in response of the "createProject" endpoint.

Request Body schema: multipart/form-data

The body is a multipart/form-data request type. The datafile is the binary file.

project_id required	string The id of the project that is returned in the response of the Create project method.
datafile required	string <binary> The API supports the data file in CSV or XLSX format. See the Data File section to read how to create a new one or download a sample.
coverTitle	string The title printed on the cover page of the document.
coverSubtitle	string The subtitle printed on the cover page of the document, underneath the title.
tocTitle	string The title printed on the Table of contents page.
companyLogo	string The URL of the company logo to add to the document. The URL must be public.
coverColor	string The principal color of the document. The process can accept only a hexadecimal color code.
doOnlyValidation	boolean If `true` the method runs only the checks of the data file. The default value is `false`.

Responses

200

OK - requst accepted

post/projects

https://api.pagination.com/vpc/projects

Request samples

Payload

Content type

multipart/form-data

Copy

[
  {
    "companyLogo": "https://hotpink.s3-eu-west-1.amazonaws.com/pro3Images/Pagination.png"
  },
  {
    "coverColor": "#0067B9"
  },
  {
    "tocTitle": "Table of contents"
  },
  {
    "datafile": "<file goes here>",
    "format": "binary"
  },
  {
    "coverSubtitle": "Subtitle1"
  },
  {
    "project_id": "projectName_pro3Test_pro3_id-1"
  },
  {
    "coverTitle": "Title1"
  },
  {
    "doOnlyValidation": false
  }
]

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"fileName": "mainDataFile_test.csv",
"message": "Pagination started!",
"reqId": "07215d06-11ed-4cb4-b992-5b5ccac6bfe4"
}

Delete Project

Delete a project based on project id. Also, update user information contextually.

Authorizations:

api-key

header Parameters

project_id required	string The id of the project that is returned from the response of the Create project method.
user_id required	string

Request Body schema: application/json

webhook

string

The URL to receive the notifications.

Responses

200

delete/projects

https://api.pagination.com/vpc/projects

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"webhook": "string"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"message": "Deletion complete."
}

Modify Project

Modify the editable properties of a project.

header Parameters

project_id

required

string

The id of the project that is returned from the response of the Create project method.

Request Body schema: application/x-www-form-urlencoded

webhook

string

The URL to receive the notifications.

Responses

200

patch/projects

https://api.pagination.com/vpc/projects

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"message": "Update complete for project_id myCompany_myProject_demo_id-1."
}

Operations endpoints

Get Process Status

Retrieve the status of a process given its request id (reqId)
Retrieve the full history by project_id
Retrieve the full user's request history if no reqId nor project_id is provided
Each item's signedUrl link expires after 7 days.
If you'd like to refresh a specific link, please call this endpoint by specifying the reqId.

Authorizations:

api-key

header Parameters

project_id	any the id of the project you'd like to get the status of.
reqId	string The id of the request that is returned by the Launch pagination api. The download link (signedUrl) is refreshed if its validity has expired (1 week). If you don't specifiy this, the api returns the full list of previous requests. ATTENTION: the download links are not automatically refreshed.
user_id required	string the user_id of the user attached to the project (e.g. the owner).

Responses

200

get/operations

https://api.pagination.com/vpc/operations

Response samples

Content type

application/json

Copy

Expand all Collapse all


[
{"status": "string",
"origin": "string",
"reqId": "string",
"paginationDate": "string",
"signedUrl": "string",
"expireDate": "string",
"project_id": "string",
"remainingEstimated": 100000.555,
"progress": 100
}
]

Delete Process

Stop an ongoing process by its request Id (reqId).

header Parameters

reqId required	string The reqId is returned from the response of the Launch project method.
project_id required	string The id of the project that is returned from the response of the Create project method.

Responses

200

delete/operations

https://api.pagination.com/vpc/operations

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"message": "Process stopped."
}

User endpoints

Get User Info

Retrieve user info from our database.
Check current subscription, attached projects and default user email.

header Parameters

user_id required	string the user_id of the user attached to the project (e.g. the owner).
userinfo_id required	string The user_id of the user to retrieve the information.

Responses

200

get/users

https://api.pagination.com/vpc/users

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"user_id": "pagination-pagination-default",
"subscription_id": "BASIC",
"email": "[email protected]",
"attached_projects": 
[
{"project_class": "demo",
"project_id": "MyCompany_MyProject_demo_id-1"
}
]
}

Modify User

Modify editable user information.

header Parameters

user_id

required

string

the user_id of the user attached to the project (e.g. the owner).

Request Body schema: application/x-www-form-urlencoded

userinfo_id required	string The user_id of the user to retrieve the information.
project_ids	array The list of project_ids to attach to a user.

Responses

200

patch/users

https://api.pagination.com/vpc/users

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"message": "Update complete for user myCompany_myProject_demo_id-1."
}