Pagination API

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

Endpoints specifications are documented using the OpenApi 3.0 format.

Table of contents

• Getting started
• Workflow
  ⋅  step 0 – credentials
  ⋅  step 1 – create project
  ⋅  step 2 – launch process
  ⋅  step 3 – retrieve request status
• Layout VS Datafile
  ⋅  project_class and layout
  ⋅  Datafile
  ⋅  Images

---

Getting started

Pagination APIs lets the user create, customize and control the Pagination Service, autonomously.

The core of the Pagination Service consists of:

• project
  The container of all the customer choices in terms of
  ⋅   base layout (chosen from our templates library or custom-made by us)
  ⋅   personalization (all features added on top of the base layout)
  ⋅   settings (e.g. notification settings)
  The project is identified by a unique project_id.
  The base layout is identified by a unique project_class.
• user
  The owner of the project authorized to perform API calls.
  It is identified by a unique user_id.
• the pagination process
  Requests are identified by a unique reqId. When calling the endpoint, you must provide, as input
  ⋅   a well structured datafile
  ⋅   request-specific settings (e.g. colors, type of exports, notifications)
  Pagination Service processes requests asinchronously, using the rules and settings stored in the project.
  As a result, the process exports a single .zip file containing the output files in the desired formats.
  Along the process, the status of each request is stored in the project’s history, that is always accessible by the user.
  After completion, users are notified (e.g email, webhook) and they are given the link to download the exported documents.

Pagination APIs provide different endpoints in order to control all the components of the Pagination Service.

---

Workflow

In order to better understand the workflow of the Pagination Service and how to control it using the APIs, lets dive into a quick tutorial using our template demo!

Step 0 – credentials

Each API call must be authenticated.
Usually each endpoint requires an api-key and a user_id as header params.
Please refer to the specs for authentication details.

Ask us for some free demo credentials already set up for launching a project, or download directly an api-key in order to setup a new demo project from scratch.

Step 1 – create a project

Before paginating anything, you must create a new project, by making a call to the create project endpoint.
Upon creation of your first project, a new user will be added to our database.
The endpoint requires you to provide:

• project_class
  The class is the document layout unique id and and can choose the layout you prefer from our Library.
  For this demo, you can pick up the class named demo.
  You can better understand how the document layout is organized on the page by having a look into the Layout section.
• email
  Your actual email address, i.e. the project’s owner email.
  This email is used upon creation to register a new user into our database.
  All new projects created using the same email will be attached to the same user.
• webhook settings (optional)
  If you prefer to receive also POST message to your custom URL, with notifications on the process status, just fill up this field.
• optional settings
  Each class has its own custom global settings, that you can set upon project creation.
  The demo template doesn’t require any other setting.
  Adding many new project classes is on our roadmap!

The endpoint returns some key property used to authorize and call every other endpoint:

• project_id
  The unique id of the newly created project.
• user_id
  The unique id of the project’s owner. It is the provided email. Use this as a required header parameter in subseguent api calls.

Step 2 – launch the process

After creating the project, you can launch it using the launch process endpoint.

The endpoint requires you to provide:

• project_id (returned by the create project endpoint)
• user_id (returned by the create project endpoint)
• datafile
• optional settings, specific for the current pagination process request (e.g. the colors of the labels, the titles) and depending on the project class.
  The demo class doesn’t require to specify any optional setting.

In order to launch a pagination process you have to build a suitable datafile (.csv, .xlsx format), that must be structured as the selected project_class requires.
You can have a better understanding on how to structure a datafile for the demo class in the Datafile section.

The file is uploaded as a part of the request’s body. Please pay attention that body type is multipart/form-data.

A note on the multipart/form-data

Depending on the framework you are using to make the API call (e.g. nodeJs, postman), you have to adopt a specific syntax in order to specify that one of the body’s field refers to a file to be uploaded. Using curl, for example:

curl -X POST -F fieldNameHere=@myfile.html http://myapi.com/

The endpoint returns the unique request id of the process (reqId), that allows you to retrieve the process status and results.

Notifications

Upon launch, the owner receives at the provided address an email (and a message to the webhook URL, if provided during project creation), informing him of the correct start of the pagination process.
Since the process is asynchronous, you will receive a notification (email and webhook if provided) once the process is complete.
In the “pagination-complete” notification, a public URL to the exported document is provided. Please remember that the link expires after 7 day (renewal is possible through the get Status endpoint).

Step 3 – retrieve request status

After launching a project, the job is pretty much done and you have just to wait for the notification of process complete.
You can retrieve the request status by calling the get Process Status endpoint. In particular, it is possible to get either the full history or the specific request status, by providing its reqId.
In the response you’ll find the download link: please remember that it expires after 7 days (it automatically get renewed after calling the get Process Status endpoint with its reqId).

---

Layout vs Datafile

Layout

Each project_class comes with its own layout and its own settings.
The datafile structure reflects the layout structure, e.g. if the layout includes tables with 2 images for each product, you’ll need to fill 2 extra fields in the datafile.

The demo template consists of two main parts:

• the table of contents page that summarize the products in the document
• the body of the document with the products organized in tables

See a sample PDF document here.
Paid plans can benefit from more templates or submit their own custom layouts.
For more information please contact us.

---

Data File

Format of the data .csv or .xlsx
Download data file example here.
Hierarchy fields and Descriptive Fields are mandatory, Attribute fields are optional.
Cells can be left empty, what is mandatory is the column header.

Hierarchy fields

Products are grouped using these fields: products that share the same categories will be grouped together.
The content of these fields will be printed in the table of contents.

Category1

Main category that classifies the products.
Placement: Page sides

Category2

The second level of classification of the products, subcategory.
Placement: Page sides

Descriptive fields

These fields refer to the products.

ProductName

Product title.
This field is used to group together variants or various product codes.
Placement: Top of the layout

Description

Product description.
Basic HTML coding can be used to personalize the text.
Permitted tags:
<b>bold</b>
<ul> <li> bullet list </li> </ul>
<i>italic</i>
sup for superscript
sub for subscript
Placement: Underneath ProductName

Image1

Public URL of the main product image.
The image refers to the Product name, not the product code. If every Item/Sku has a different image, the first of the group (ProductName) will be printed
Must include the extension. e.g. “pagination.jpg”
Accepted format: .jpg .eps .pdf .png .tiff .ai .psd
Placement: Right side of the layout

Image2

Public URL of product images could be technical drawing, detail, different pov.
The image refers to the Product name, not the product code. If every Item/Sku has a different image, the first of the group (ProductName) will be printed
Must include the extension. e.g. “pagination.jpg”
Accepted format: .jpg .eps .pdf .png .tiff .ai .psd
Placement: Underneath description

Image3

Public URL of product image could be technical drawing, detail, different pov.
The image refers to the Product name, not the product code. If every Item/Sku has a different image, the first of the group (ProductName) will be printed
Must include the extension. e.g. “pagination.jpg”
Accepted format: .jpg .eps .pdf .png .tiff .ai .psd
Placement: Underneath description

BrandLogo

Public URL of the manufacturer/brand logo of the product.
Must include the extension. e.g. “pagination.jpg”
Accepted format: .jpg .eps .pdf .png .tiff .ai .psd
Placement: Above Image1

Attributes

These fields can be specific to the products and variants.
There can be as many columns as needed in the data file.
The demo layout fits max 11 attribute columns filled per ProductName.
The order in which the columns appear in the data file (left to right) is the order used in the layout.
Headers do not have mandatory names.

Product Code/SKU is to be considered as an attribute.
Other examples of attributes can be: dimensions, colors, short description, prices/currencies.
Make sure that the cells are formatted as text and the content is what to expect
to see in the layout. Especially in price columns make sure that: prefix for currencies, number of decimal
digits, thousands separator, decimal separator are correctly typed in.
Placement: Table

---

Images

All images will be automatically loaded from the public URL included in the data file.