The REST API from Keyline | Keyline Knowledge Base

You can find the official documentation of our two APIs here.

The Inbox API is suitable for creating an order in Keyline from a system such as a Web2Print shop, using predefined product templates.

Here, a virtual shopping cart is filled, and with a checkout, Keyline directly creates an order for you based on your defined data and products.

With the Advanced API, you can make additional configurations.

In the Admin area under Accounts/API Permissions, you can create and manage new API keys.

These keys are required to integrate third-party applications such as Pipedrive, make.com, CRM systems, etc.

Once you’ve created a new API key via the “Create API access permission” button, you can share it with the service provider and deactivate it at any time.

Caution: API keys created in this way have access to all resources of your Keyline account.

You can therefore also restrict API keys to specific organizations, which will then only operate under that organization’s name.

To do this, please create the API key directly within the organization (Sales > Organization).

API keys that are no longer needed should be deactivated immediately.

Each API key also counts towards the total number of users.

Please note that a deactivated API key cannot be reactivated.

🔎 Usage Tip:

Use your browser’s search function (Ctrl+F / Cmd+F) to jump directly to relevant keywords or endpoints.

📦 Circulations – Define Print Runs per Variant

This API section allows you to define actual circulations (print runs) per product variant, similar to the feature available in the UI.

Method	Endpoint	Description
GET	/production/products/:product_id/circulations	List all circulations for a product
GET	/production/products/:product_id/circulations/:id	Retrieve a single circulation
PATCH	/production/products/:product_id/circulations/:id	Update the actual_amount of a circulation

📤 Example Payload:

{
  "circulation": {
    "actual_amount": 32
  }
}

📄 Job Bags, Delivery Notes & Labels

You can generate various production and logistics documents via the API. Depending on the requested content type, the API returns either JSON metadata or the PDF file directly.

Method	Endpoint	Description
GET	/production/products/:product_id/job_bag.pdf	Job bag (PDF as JSON link)
GET	/logistics/shipments/:shipment_id/delivery_note.pdf	Delivery note (PDF as JSON)
GET	/logistics/shipments/:shipment_id/proforma_invoice.pdf	Pro forma invoice
GET	/logistics/parcels/:parcel_id/label.pdf	Parcel label (PDF link)

Direct PDF file (binary response)

Use the same endpoints with header:

Accept: application/pdf

Method	Endpoint	Description
GET	/production/products/:product_id/job_bag	Direct job bag PDF
GET	/logistics/shipments/:shipment_id/delivery_note	Direct delivery note PDF
GET	/logistics/shipments/:shipment_id/proforma_invoice	Pro forma invoice PDF
GET	/logistics/parcels/:parcel_id/label	Parcel label PDF
GET	/logistics/outsourcings/:outsourcing_id	Outsourcing Slip PDF

🧾 Material Presets & Packaging

Use these endpoints to predefine materials for product components, finishings, and packaging steps. This allows for automation and standardization of material selection in the conception phase.

You can assign material presets at different levels:

Method	Endpoint	Description
GET/POST	/conception/products/:product_id/components/:component_id/material_presets	Material presets for a specific component
GET/POST	/conception/products/:product_id/components/:component_id/finishings/:finishing_id/material_presets	Material presets for a finishing within a component
GET/POST	/conception/products/:product_id/material_presets	Material presets at product level
GET/POST	/conception/products/:product_id/finishings/:finishing_id/material_presets	Material presets at product → finishing level
GET/POST	/conception/products/:product_id/packagings/:packaging_id/material_presets	Material preset for packaging

📤 Example Payload:

{
  "material_preset": {
    "material_id": 1
  }
}

📦 Packaging Workflow (Step-by-Step)

To automate packaging setup, follow this flow:

Create packaging entry
POST /conception/products/{product_id}/packagings
Define packaging details (label type, deposition, etc.)
PATCH /conception/products/{product_id}/packagings/{packaging_id}
Create pick instructions (which items go into this packaging)
POST /conception/products/{product_id}/packagings/{packaging_id}/picks

👉 If multiple sorts or packagings exist, all definitions must be combined in the same JSON payload.

🚚 Shipping Note:

If an item is to be shipped directly, include the property:

"deposition": "shipment"

This skips the picking step and directly creates a packaging for shipping.

📦 Retrieve Packagings During Production

If you want to view the packaging units of a product during production, the following endpoints are available:

GET /production/products/:id/packagings/
GET /production/products/:id/packagings/:id

🛠️ Change Production Means & Recalculate Concept

These endpoints allow you to override default production resources and trigger a new conceptualization (recalculation of the production path).

🔧 Change Production Resource (e.g. machine)

To change a production resource for a specific component:

POST /conception/products/{product_id}/production_paths/{production_path_id}/production_flow_modifications

📤 Example Payload:

{
  "production_flow_modification": {
    "modification": "preset",
    "workable_type": "component",
    "workable_id": 1361413,
    "stock_task_id": 6579,
    "means_of_production_id": 10319
  }
}

workable_id: corresponds to the component ID
means_of_production_id: new machine/resource
stock_task_id: the specific task ID within the flow

♻️ Recalculate Production Path (Conceptualization)

After making changes, you can trigger a new calculation:

POST /conception/products/{product_id}/production_paths/{production_path_id}/conceptualize

This is not mandatory, but recommended to update timings and costs.

✂️ Cutting (Enable Cutting Step)

To activate cutting on a specific imposing:

PATCH /conception/products/{product_id}/components/{component_id}/imposings/{imposing_id}

📤 Example Payload:

{
  "imposing": {
    "cutting": true
  }
}

📐 Adjust Folding Schema

To change the folding pattern of an imposing:

PATCH /conception/products/{product_id}/components/{component_id}/imposings/{imposing_id}

📤 Example Payload:

{
  "imposing": {
    "default_stock_folding_pattern_id": 983
  }
}

You can retrieve available folding patterns here:

GET /configuration/stock_folding_patterns

🔄 Page Arrangement Options:

Value	Description
standalone	Single page layout
crossover	Connected page layout
parallel	Parallel folding (e.g. z-fold)

🔍 Filtering & Search Queries

Many endpoints support powerful filtering and search capabilities using query parameters.

These allow you to retrieve specific subsets of data based on date ranges, status, or keywords.

GET /accounting/invoices?billed_from=2024-08-28&billed_to=2025-08-22

billed_from, billed_to – filter by invoice date
created_from, created_to – filter by creation date

📦 Orders

GET /sales/orders?state=draft

GET /sales/orders?created_from=2024-08-12&created_to=2024-09-12

GET /sales/orders?updated_from=2024-08-12&updated_to=2024-09-12

state – e.g. draft, confirmed, cancelled
created_from, updated_from – filter by date range

⚙️ Production Tasks

GET /production/tasks?search_term=offset

GET /production/tasks?state=running

GET /production/tasks?created_from=2020-06-27&created_to=2020-06-27

GET /production/tasks?updated_from=2020-11-13&updated_to=2020-11-13

GET /production/tasks?search_term=offsetdruck&state=ready

search_term – keyword-based search (e.g. machine, process, product)
state – running, ready, completed
created_from, updated_from – filter by task life cycle

✉️ Product Messages & Internal Notes

You can attach messages to products to document internal notes or instructions.

GET /production/products/{product_id}/messages

POST /production/products/{product_id}/messages

PATCH /production/products/{product_id}/messages/{message_id}

DELETE /production/products/{product_id}/messages/{message_id}

📤 Example Payload:

{
  "text": "This is an my message via the API."
}

📧 Send Custom Offer Email Text

You can modify the subject and content of the offer email via API – as long as the order is still in draft status.

POST /sales/orders/{order_id}/offer_mail_messages

📤 Example Payload:

{
  "mail_message": {
    "subject": "Custom Email Subject via API",
    "content": "Custom email body content created via API."
  }
}

⚠️ The offer will be sent immediately with the modified email text.

The order must still be in draft state.

👥 Assign a Consultant or Team Member to an Order

You can assign a user to an order and define their role (e.g. customer consultant, media designer, production employee, etc.).

POST /sales/orders/{order_id}/assignments

📤 Example Payload:

{
  "assignment": {
    "user_id": 4033,
    "role": "customer_consultant"
  }
}

🎭 Available Roles:

customer_consultant
sales_representative
media_designer
prepress_employee
production_employee
accounting_employee

You can retrieve the user_id from the admin user management section.

📎 Document Callbacks (Custom Job Bag, etc.)

With document callbacks, you can override default Keyline documents (e.g. Job Bag) by linking to your own document URL.

POST /conception/products/{product_id}/document_callbacks

📤 Example Payload:

{
  "document_callback": {
    "kind": "job_bag",
    "url": "http://your_custom_document_url"
  }
}

🔄 Modify or Remove Callback

You can also manage callbacks during the production phase:

PATCH /production/products/:id/document_callbacks

DELETE /production/products/:id/document_callbacks/:callback_id

Or during conception:

PATCH /conception/products/:id/document_callbacks

DELETE /conception/products/:id/document_callbacks/:callback_id

✅ Confirm Draft Order (Send to Production)

Use the following endpoint to confirm and release an order:

POST /sales/orders/{order_id}/confirm

This changes the order from draft to active and triggers production.

📄 Download Order Confirmation PDF

Once confirmed, the confirmation PDF can be retrieved via:

GET /sales/orders/{order_id}/confirmation.pdf

📝 Edit Product Description

To manually update the product description:

PATCH /conception/products/{product_id}

📤 Example Payload:

{
  "custom_description": "Updated product description via API."
}

⚖️ Set Custom Product Weight

You can manually override the system-calculated product weight using this endpoint:

PATCH /conception/products/{product_id}/production_paths/{production_path_id}

📤 Example Payload:

{
  "weight_calculation_mode": "manual",
  "product_weight": 123456
}

Weight must be provided in milligrams per unit (e.g. 123456 = 123.456 g)

✅ Complete a Product

To mark a product as fully produced (completed):

PATCH /production/products/{product_id}/complete

This finalizes the product and updates its status accordingly.

📦 Retrieve Outsourcing (Fremdbeschaffung) Info

List all outsourcing entries:

GET /logistics/outsourcings

This includes all external production steps managed through logistics.

📫 Announce Customer Addresses

To pre-announce customer addresses (so they can be found via search even before use):

POST /customer_relations/organizations/{organization_id}/address_announcements

After being announced, the address is searchable and visible under the associated organization once used.

🗂️ Retrieve Actual Circulations (from Archive)

To get the actual produced circulation amount of a product from the archive:

GET /archive/products/{product_id}/circulations

GET /archive/products/{product_id}/circulations/{circulation_id}

This is helpful for reviewing actual print quantities post-production.

📦 Packaging Flow via API

To automate the full packaging process via API, follow this flow:

1. Create a Packaging Unit

POST /conception/products/{product_id}/packagings

2. Define Packaging Details

PATCH /conception/products/{product_id}/packagings/{packaging_id}

Include settings like deposition, labeling, etc.

3. Create Pick Instructions

POST /conception/products/{product_id}/packagings/{packaging_id}/picks

This defines what is packed into each unit.

If you have multiple types/sorts, combine them into a single JSON.

👉 Note: If the product is shipped directly, the packaging must include:

"deposition": "shipment"

No pick is required in this case.

💸 Post-Calculation via API

To trigger a product post-calculation:

PATCH /billing/products/{product_id}

🧾 Create Invoice from Finalized Order

Once an order is finalized and post-calculated, create an invoice:

POST /accounting/customer_invoices/create_from_order?order_id={id}

🙅‍♂️ Remove Contact Person from Invoice or Credit Note

If the invoice or credit note should be issued only to the billing address, without a named contact:

DEL /accounting/customer_invoices/:id/contact
DEL /accounting/credit_notes/:id/contact