Import API

Introduction

The PressMatrix Import API enables publishers to automate the transformation of print periodicals into digital editions for the PressMatrix Kiosk and branded apps. It supports multiple import modes—including simple PDF import, automatic widget extraction, and custom XML mapping—making it easy to deliver interactive magazines to mobile and tablet devices.

Download the OpenAPI Specification

Download OpenAPI YAML

You can view the spec with Swagger Editor.

Overview

The PressMatrix Import API (v2) exposes two main endpoints for importing or updating periodicals as PDFs:

POST /api/v2/importer/organizations/{organization_id}/publications/{publication_id}/emags (for new issues)
PUT /api/v2/importer/organizations/{organization_id}/publications/{publication_id}/emags/{emag_id} (for updating existing issues)

Both endpoints accept a JSON payload with all metadata, PDF location, and (optionally) XML configuration.
Only one of import_attributes or epub_import_attributes can be used per request.
All import modes (simple PDF, automatic widgets, custom XML, EPUB) are supported for both creating and updating issues.

Name
organization_id
Type
string
Description
The unique ID of your organization. This value is supplied by PressMatrix and is required for all requests.
Name
publication_id
Type
string
Description
The unique ID of the publication you wish to import or update. This value is supplied by PressMatrix and is required for all requests.
Name
emag_id
Type
integer
Description
The unique ID of the emag (periodical issue) to update. For PUT requests, this ID is returned in the id field of the POST response when a new emag is created (see the "Success Response" example in the POST documentation).

POST/api/v2/importer/organizations/{organisation_id}/publications/{publication_id}/emags

Import PDF/EPUB

The Import API allows you to import new periodicals and define how text and images are processed into widgets.
You control the import mode with either the import_attributes or the epub_import_attributes object in your payload.
Do not send both.

Pre-requisites

Organization and publication must be enabled by PressMatrix.
A token must be generated by PressMatrix and included in the request header as Authorization: Token {TOKEN_GENERATED_BY_PMX}.

There are several import modes supported by the API:

Simple PDF import - import_attributes.import_images = false (text widgets only)
PDF with image widgets - import_attributes.import_images = true (text and image widgets)
PDF with custom-defined XML widgets - import_attributes.xml_location set (custom mapping)
EPUB import - use epub_import_attributes instead (see below)
Planned PDF import - import_attributes.import_images = true (text and image widgets) + pe_id set (planned import)

Important: Only one of import_attributes or epub_import_attributes is allowed per request.

Name
name
Type
string
Description
(Required) Name of the issue. Must be unique within the publication. Displayed below the cover in the PressMatrix Kiosk.
Name
released_at
Type
string
Description
(Required) Date and time from which the issue becomes visible and available for purchase (format: YYYY-MM-DD HH:MM:SS).
To use the automated publishing feature, it must be activated by PressMatrix.
Name
pe_id
Type
string
Description
(Optional) Planned edition identifier. Provived by PressMatrix for planned imports.
Special property when using planned imports. IDs are provided by PressMatrix.
Name
preview
Type
string
Description
(Optional) Short description of the issue's contents. Visible in the PressMatrix Kiosk on the issue details screen. Recommended.
If this field is not provided, and the setting to use AI generated previews is enabled, an AI-generated preview will be created automatically.
Name
apple_product_identifier
Type
string
Description
(Required if cents > 0) Apple In-App Purchase product identifier. Must be unique within publication if price > 0. Must match Apple's format pattern.
Name
google_product_id
Type
string
Description
(Optional) Google In-App Billing product identifier. Must be unique within publication if present. Must match Google’s format pattern.
Name
external_id
Type
string
Description
(Optional) External identifiers (comma-separated). Only safe characters are allowed.
Name
hide_preview_widgets
Type
bool
Description
(Optional) If true, hides all widget types in the preview for this issue.
Name
single_purchase_required
Type
bool
Description
(Optional) If true, a single purchase is required to access this issue.
It's not possible to use this together with the for_subscribers_only flag.
Name
for_subscribers_only
Type
bool
Description
(Optional) If true, this issue is accessible only for subscribers.
It's not possible to use this together with the single_purchase_required flag.
Name
cents
Type
integer
Description
(Optional) Price of the issue in cents. Must be integer ≥ 0.
Name
currency
Type
string
Description
(Optional) Three-letter ISO currency code. Must be exactly 3 characters (e.g., "EUR").
Name
category_ids
Type
array
Description
(Optional) Array of category IDs the issue belongs to.
Category IDs must be valid and exist in the publication. If not provided, the issue will not be categorized.
Name
text_mode_enabled
Type
bool
Description
(Optional) Enables text mode for the issue. Controls if text widgets are available in the app. The text itself is always imported to our database.
Name
language
Type
string
Description
(Optional) Locale code for the issue (e.g., "de"). Must be exactly 2 characters and in the list of allowed languages. This is mainly relevant for the text to speech feature for the corresponding OS (e.g. iOS, Siri).
Name
import_attributes
Type
object
Description
(Required for PDF Import) PDF import configuration. Only one of import_attributes or epub_import_attributes can be provided per request.
- (Optional) import_images (bool): Extract and import images as widgets from the PDF (true) or import only text widgets (false).
- (Required) pdf_location (string): URL to the PDF file (HTTPS, valid certificate required).
- (Optional) xml_location (string): URL to the XML file for custom widget mapping (HTTPS, valid certificate required).
Name
epub_import_attributes
Type
object
Description
(Required for EPUB Import) EPUB import configuration. Only one of import_attributes or epub_import_attributes can be provided per request.
- (Optional) import_images (bool): Extract and import images as widgets from the EPUB (true) or import only text widgets (false).
- (Required) pdf_location (string): URL to the PDF file associated with the EPUB (HTTPS, valid certificate required).
- (Required) epub_location (string): URL to the EPUB file to import (HTTPS, valid certificate required).

PDF Import Example (POST)

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organisation_id}/publications/{publication_id}/emags' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "name": "name of the issue",
      "released_at": "2025-07-09 10:00:00",
      "preview": "Short description for kiosk details.",
      "apple_product_identifier": "com.example.kiosk.issue_2025_07",
      "google_product_id": "com.example.kiosk.issue_2025_07",
      "external_id": "ISSUE-2025-07",
      "hide_preview_widgets": false,
      "single_purchase_required": false,
      "for_subscribers_only": false,
      "cents": 199,
      "currency": "EUR",
      "category_ids": [
        508
      ],
      "text_mode_enabled": true,
      "language": "de",
      "import_attributes": {
        "import_images": true,
        "pdf_location": "https://www.mydomain.com/issue.pdf",
        "xml_location": "https://www.mydomain.com/issue.xml"
      }
    }
  }'

EPUB Import Example (POST)

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organisation_id}/publications/{publication_id}/emags' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "name": "EPUB Issue July 2025",
      "released_at": "2025-07-09 10:00:00",
      "preview": "Short description for kiosk details.",
      "apple_product_identifier": "com.example.kiosk.issue_2025_07_epub",
      "google_product_id": "com.example.kiosk.issue_2025_07_epub",
      "external_id": "ISSUE-2025-07-EPUB",
      "cents": 199,
      "currency": "EUR",
      "category_ids": [
        508,
        777
      ],
      "text_mode_enabled": true,
      "language": "de",
      "epub_import_attributes": {
        "import_articles": true,
        "import_images": true,
        "pdf_location": "https://cdn.example.com/issues/2025_07/issue.pdf",
        "epub_location": "https://cdn.example.com/issues/2025_07/issue.epub"
      }
    }
  }'

Planned Import Example (POST)

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organisation_id}/publications/{publication_id}/emags' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "name": "EPUB Issue July 2025",
      "released_at": "2025-07-09 10:00:00",
      "pe_id": "ABC_20260804",
      "preview": "Short description for kiosk details.",
      "apple_product_identifier": "com.example.kiosk.issue_2025_07_epub",
      "google_product_id": "com.example.kiosk.issue_2025_07_epub",
      "external_id": "ISSUE-2025-07-EPUB",
      "cents": 199,
      "currency": "EUR",
      "category_ids": [
        508,
        777
      ],
      "language": "de",
      "import_attributes": {
        "import_images": true,
        "pdf_location": "https://cdn.example.com/issues/2025_07/issue.pdf",
      }
    }
  }'

Success Response

{
  "id": 12345,
  "created_at": "2025-07-24T12:02:58.000Z"
}

Failure Response

{
  "field_name": [
    "error message"
  ]
}

PUT/api/v2/importer/organizations/{organisation_id}/publications/{publication_id}/emags/{emag_id}

Update PDF/EPUB

The Import API allows you to update any metadata or content of an existing periodical by sending a PUT request to the endpoint with the respective emag_id.

File Replacement:
Warning: If a new file is provided (e.g., pdf_location, xml_location, or epub_location), previous imports are deleted and a new import is started. If the file is broken or unreachable, the emag will be left empty and must be fixed via another update.
No Conversion Between PDF and EPUB:
You cannot switch from a PDF import (import_attributes) to an EPUB import (epub_import_attributes), or vice versa, via update. This will cause processing errors not caught by the API.
Uniqueness:
All uniqueness requirements for name, google_product_id, and apple_product_identifier still apply. If a conflict occurs, you will receive an error response indicating which field is not unique.

Name
emag_id
Type
integer
Description
(Required) The unique ID of the emag (issue) to update.
You receive this value in the id field of the POST response after creating a new emag.
Name
organization_id
Type
string
Description
(Required) The unique ID of your organization, supplied by PressMatrix.
Name
publication_id
Type
string
Description
(Required) The unique ID of the publication, supplied by PressMatrix.

Further fields and their descriptions are documented in the POST endpoint section.

Minimal Update Example (PUT)

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organisation_id}/publications/{publication_id}/emags/{emag_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "name": "Neuer Name der Ausgabe"
    }
  }'

Update PDF File (PUT)

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organisation_id}/publications/{publication_id}/emags/{emag_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "import_attributes": {
        "pdf_location": "https://www.mydomain.com/newfile.pdf"
      }
    }
  }'

Update EPUB File (PUT)

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organisation_id}/publications/{publication_id}/emags/{emag_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "epub_import_attributes": {
        "pdf_location": "https://www.mydomain.com/newfile.pdf",
        "epub_location": "https://www.mydomain.com/newfile.epub"
      }
    }
  }'

Update only meta fields

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organisation_id}/publications/{publication_id}/emags/{emag_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "name": "Updated Issue Title – July 2025",
      "released_at": "2025-07-10 12:00:00",
      "preview": "Updated short description for kiosk details.",
      "apple_product_identifier": "com.example.kiosk.issue_2025_07",
      "google_product_id": "com.example.kiosk.issue_2025_07",
      "external_id": "ISSUE-2025-07-REV-A",
      "hide_preview_widgets": true,
      "single_purchase_required": false,
      "for_subscribers_only": false,
      "cents": 299,
      "currency": "EUR",
      "category_ids": [
        508,
        777
      ],
      "text_mode_enabled": false,
      "language": "de"
    }
  }'

Reimport !! Triggers a NEW import !! This action cannot be undone.

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organisation_id}/publications/{publication_id}/emags/{emag_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "import_attributes": {
        "import_images": false,
        "pdf_location": "https://cdn.example.com/issues/2025_07/issue_v2.pdf",
        "xml_location": "https://cdn.example.com/issues/2025_07/issue_articles_v2.xml"
      }
    }
  }'

Success Response

{
  "id": 12345,
  "created_at": "2025-08-01T12:10:00.000Z"
}

Failure Response

{
  "field_name": [
    "error message"
  ]
}