Pagination API (1.0 - 2021/02/09)

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

  1. Create a new project by selecting a layout (project_class).
  2. Launch the pagination prcess by attaching a data file to the request; you can personalize the Pagination.
  3. 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:
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

OK

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

Request samples

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:
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

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": "pinolino_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:
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

OK

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

Request samples

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

OK

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "message": "Update complete for user 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:
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

OK

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

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.

Responses

200

OK

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.

Responses

200

OK

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":
    [
    ]
}

Modify User

Modify editable user information.

Request Body schema: application/x-www-form-urlencoded
email
required
string

The new email address to update for the user.

Responses

200

OK

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."
}