Browse API reference

Update a print job

posthttps://api.intelliprint.net/v1/prints/{id}

Updates a print job.

Parameters

Path

idrequired

string

The ID of the print job to update.

Request body

multipart/form-data

testmode

boolean

Whether to run the print job in test mode. Test mode print jobs are not charged and are not sent.

Defaultfalse

Exampletrue

confirmed

boolean

Whether to confirm the print job. Once confirmed, the print job is submitted for printing and cannot be updated.

Defaultfalse

Exampletrue

reference

string

A user-friendly description for the print job. This value is displayed in the dashboard. You can use this value to search for this print job later.

Example"My first print job"

splitting

object

Splitting settings for the print job. Used when a single file contains multiple letters with pre-inserted addresses. Splitting is only available for letters.

methodstring

The method to use to split the print job into mailings.

Allowed valuesnonesplit_on_phrasesplit_on_pagesmailing_list

Default"none"

phrasestring

The phrase to search for on each page to split the print job into multiple letters. Only used when method is split_on_phrase. The phrase should appear once on the first page of each letter. Tip: Use white text to hide the phrase from recipients.

Example"Dear"

pagesinteger

The number of pages each letter in a split print job should have. Only used if method is split_on_pages.

Example1

printing

object

Printing settings for the print job, including quality, color, single or double-sided printing, and finishing options.

premium_qualityboolean

Whether this print job should be printed in premium quality. Premium quality is optional for letters, while postcards are always printed in premium quality due to their glossy finish.

Defaultfalse

Exampletrue

black_and_whiteboolean

Whether this print job should be printed in black and white instead of color. This is only available for letters.

Defaultfalse

Exampletrue

matt_finishboolean

Whether this print job should be printed with a matt finish. This is only available for postcards as letters are always printed on matt paper.

Defaultfalse

Exampletrue

postage

object

Postage settings for the print job, including the postage service, ideal envelope (or postcard size), and mailing date.

servicestring

The postage service to use for the print job. Postcards can currently only be sent with uk_second_class or uk_first_class services.

Allowed valuesuk_second_classuk_second_class_signed_foruk_first_classuk_first_class_signed_foruk_special_delivery_9amuk_special_deliveryinternationaltracked_24tracked_48

Default"uk_second_class"

ideal_envelopestring

The ideal envelope size for letters or postcard size for postcards.

Available values are c4, c5, c4_plus, a4_box for letters, and postcard_a6, postcard_a5 or postcard_a5_enveloped for postcards. Default is c5 for letters and postcard_a6 for postcards.

The API may upgrade a letter to a larger envelope if the content is too large for the chosen size.

Allowed valuesc4c5c4_plusa4_boxpostcard_a6postcard_a5postcard_a5_enveloped

Default"c5"

mail_dateinteger

The mailing date for the print job. This is when we will print and ship your mailing, not when it will arrive at the recipient's address. This is a UNIX timestamp (day-adjusted). Use this field to schedule mailings for a future date.

Example1761955200

background

object

Background settings for the print job. Specify which backgrounds to apply to different pages. This is only available for letters.

first_pagestring

The ID of the background to apply to the first page of the print job. Typically a letterhead or logo.

Example"bg_eg"

other_pagesstring

The ID of the background to apply to the other pages of the print job. Typically a continuation design or logo.

Example"bg_eg"

confidential

boolean

Whether this print job should be considered confidential. Confidential print jobs cannot be viewed by other users in the dashboard.

Defaultfalse

Exampletrue

extra_documents

array of object

Extra documents (or additional documents) can be sent alongside letters in the print job. These can include standard terms and conditions, brochures, forms, or other supplementary materials.

A copy of all extra documents is sent with each letter in the print job.

The order they appear in the array is the order they will follow during printing.

Acceptable formats are PDF, RTF, and Word documents.

Extra documents are only available for letters, as postcards have a fixed size.

Array of object.

documentone ofrequired

One of

Option 1Direct file upload

The extra document file to include in the print job.

You can either provide this file directly as a binary file or as a Base64 encoded data object. Please select an approach above.

The accepted file formats are PDF, RTF and Word documents.

The extra document file to include in the print job.

You can either provide this file directly as a binary file or as a Base64 encoded data object. Please select an approach above.

The accepted file formats are PDF, RTF and Word documents.

Option 2Base64 encoded file data

The base64 encoded extra document data to be included in the print job.

The accepted file formats are PDF, RTF and Word documents.

contentstringrequired

The Base64 encoded content of the extra document to include in the print job.

Example"BASE64_ENCODED_PDF"

namestringrequired

The name of the extra document to include in the print job.

Example"Filename.pdf"

apply_backgroundboolean

Whether to apply the background.other_pages to the extra document. Default is false.

Defaultfalse

Exampletrue

remove_letters

object

Used alongside the splitting settings to remove specific letters from the print job.

with_phrasestring

If this phrase is present in a letter, it will be removed from the print job. This is only available for letters.

Example"EMAIL ONLY"

nudge

object

For print jobs with pre-inserted addresses, nudging helps position the address within the envelope window. Nudging is only available for letters.

xnumber

The horizontal distance to nudge the address window to the right in millimeters.

Example2

ynumber

The vertical distance to nudge the address window down in millimeters.

Example-1

confirmation_email

boolean

Whether to send a confirmation email to the account owner once the print job is confirmed. By default, no confirmation email is sent.

Defaultfalse

Examplefalse

address_window

string

The position of the address window on the page. This is only available for letters.

Allowed valuesleftright

Default"left"

insert

string

The ID of an insert to use for the print job. Inserts are a value-added service - We can keep stock of and insert any pre-printed materials provided ahead of time into envelopes for you. Please contact us at hello@intelliprint.net to enable this service for your account.

Example"ins_eg"

metadata

object

This is an arbitrary object that can be used to store any additional data alongside your print job. This is not used by Intelliprint and is only for your own use.

Responses

Sample JSON for every response shape is in the right rail. Expand a row below to see every field this endpoint can return.

200Successful responseapplication/json

id

string

A globally unique identifier for the print job.

Example"print_eg"

object

string

The object type. Always print.

Allowed valuesprint

testmode

boolean

Whether the print job is in test mode. When enabled, your account is not charged and mail is not sent.

Defaultfalse

Exampletrue

account

string

The Intelliprint account ID that the print job belongs to.

Example"acc_eg"

user

object

The user who initiated the print job. This value is null for API-initiated print jobs.

team

object

The team associated with the print job. This value is null for API-initiated print jobs.

reference

string

A user-friendly description of this print job. This value is displayed in the dashboard for easier identification.

Example"Marketing pamphlet for J. Doe"

confirmed

boolean

Whether the print job has been confirmed. Once confirmed, the print job is submitted for printing and cannot be updated. You can confirm a print job in the dashboard or by setting the confirmed parameter via the API.

Defaultfalse

Exampletrue

type

string

The type of mailings present in the print job.

Allowed valuesletterpostcard

Default"letter"

pages

integer

The total number of pages across all mailings in the print job. This may be the same as or more than sheets if double-sided printing is used.

Example10

sheets

integer

The total number of physical sheets across all mailings in the print job. Sheets are the physical paper that pages are printed on.

Example5

file

object

Details about the file uploaded to create the print job.

namestring

The name of the file uploaded when creating the print job. This also serves as the default reference if one is not provided.

Example"eg_file.pdf"

pagesinteger

The number of pages in the uploaded file.

Example10

sizeinteger<int64>

The size of the file uploaded in bytes.

Example1024000

splitting

object

Splitting settings for the print job. Used when a single file contains multiple letters with pre-inserted addresses. Splitting is only available for letters.

methodstring

The method used to split the print job into mailings.

Allowed valuesnonesplit_on_phrasesplit_on_pagesmailing_list

Default"none"

phrasestring

Example"Dear"

pagesinteger

The number of pages each letter in a split print job should have. Only used if method is split_on_pages.

Example1

printing

object

Printing settings for the print job, including quality, color, single or double-sided printing, and finishing options. Single-sided printing is the default.

double_sidedstring

Whether this print job should be printed on both sides of the paper.

If you choose mixed, you need to specify the page indexes to print double sided in the double_sided_specific_pages property.

This is only available for letters.

Allowed valuesnoyesmixed

Default"no"

double_sided_specific_pagesarray of integer

The page indexes to print double-sided. Only used if double_sided is mixed. This is only available for letters. Page indexes are 0-indexed (first page is index 0).

Array of integer.

premium_qualityboolean

Whether this print job should be printed in premium quality. Premium quality is optional for letters, while postcards are always printed in premium quality due to their glossy finish.

Defaultfalse

Exampletrue

black_and_whiteboolean

Whether this print job should be printed in black and white instead of color. This is only available for letters.

Defaultfalse

Exampletrue

matt_finishboolean

Whether this print job should be printed with a matt finish. This is only available for postcards as letters are always printed on matt paper.

Defaultfalse

Exampletrue

postage

object

Postage settings for the print job, including the postage service, ideal envelope (or postcard size), and mailing date.

servicestring

The postage service to use for the print job. Postcards can currently only be sent with uk_second_class or uk_first_class services.

Allowed valuesuk_second_classuk_second_class_signed_foruk_first_classuk_first_class_signed_foruk_special_delivery_9amuk_special_deliveryinternationaltracked_24tracked_48

Default"uk_second_class"

ideal_envelopestring

The ideal envelope size for letters or postcard size for postcards.

The API may upgrade a letter to a larger envelope if the content is too large for the chosen envelope size.

Allowed valuesc4c5c4_plusa4_boxpostcard_a6postcard_a5postcard_a5_enveloped

Default"c5"

mail_dateinteger<int64>

Example1761955200

background

object

Background settings for the print job. Specify which backgrounds to apply to different pages. This is only available for letters.

first_pagestring

The ID of the background to apply to the first page of the print job. Typically a letterhead or logo.

Example"bg_eg"

other_pagesstring

The ID of the background to apply to the other pages of the print job. Typically a continuation design or logo.

Example"bg_eg"

confidential

boolean

Whether this print job should be considered confidential. Confidential print jobs cannot be viewed by other users in the dashboard.

Defaultfalse

Exampletrue

extra_documents

array of object

Extra documents (or additional documents) can be sent alongside letters in the print job. These can include standard terms and conditions, brochures, forms, or other supplementary materials.

A copy of all extra documents is sent with each letter in the print job.

Extra documents are only available for letters, as postcards have a fixed size.

Array of object.

idstring

A globally unique identifier for the extra document uploaded.

Example"extra_eg"

namestring

The filename of the uploaded document.

Example"eg_file.pdf"

apply_backgroundboolean

Whether to apply the background.other_pages to the extra document. Default is false.

Defaultfalse

Exampletrue

pagesinteger

The number of pages in the extra document.

Example10

sizeinteger<int64>

The size of the extra document in bytes.

Example1024000

remove_letters

object

Used alongside the splitting settings to remove specific letters from the print job.

with_phrasestring

If this phrase is present in a letter, it will be removed from the print job. This is only available for letters.

Example"EMAIL ONLY"

nudge

object

For print jobs with pre-inserted addresses, nudging helps position the address within the envelope window. Nudging is only available for letters.

xnumber

The horizontal distance to nudge the address window to the right in millimeters.

Example2

ynumber

The vertical distance to nudge the address window down in millimeters.

Example-1

letters

array of object

An array of letters or postcards present in the print job.

Array of object.

idstring

A globally unique identifier for this mail item.

Example"letter_eg"

objectstring

The object type. Always letter for both letters and postcards.

Allowed valuesletter

statusstring

The status of the mail item, representing its lifecycle from creation to dispatch.

Allowed valuesdraftwaiting_to_printprintingenclosingshippingsentcancelledreturnedfailed_wrong_address

Default"draft"

postage_servicestring

The postage service used to ship the mail item.

Allowed valuesuk_second_classuk_second_class_signed_foruk_first_classuk_first_class_signed_foruk_special_delivery_9amuk_special_deliveryinternationaltracked_24tracked_48

Default"uk_second_class"

tracking_numberstring

The Royal Mail tracking number of the mail item.

This is only available for tracked shipping services, uk_second_class_signed_for, uk_first_class_signed_for, uk_special_delivery_9am, uk_special_delivery, tracked_24 or tracked_48.

Example"1234567890"

shipped_dateinteger<int64>

The UNIX timestamp of when the mail item was shipped out. We use UNIX timestamps to mitigate any timezone-based issues.

Example1761955200

returnedobject

Details concerning why a mail item was returned.

This object is only present if the mail item has a status of returned.

acknowledgedboolean

Whether the mail item's return has been acknowledged on the dashboard.

Exampletrue

dateinteger<int64>

The UNIX timestamp of when the mail item was returned to us. We use UNIX timestamps to mitigate any timezone-based issues.

Example1761955200

reasonstring

A free-form reason why the mail item was returned.

Example"Not at this address"

pagesinteger

The number of pages in the mail item. Pages might be the same as, or more than sheets if double-sided printing is chosen.

Example10

sheetsinteger

The number of sheets in the mail item. Sheets are the physical paper sheets that pages are printed on.

Example5

envelopestring

The exact envelope a letter will be enclosed in or the postcard size.

Allowed valuesc4c5c4_plusa4_boxpostcard_a6postcard_a5postcard_a5_enveloped

Default"c5"

address_windowstring

The position of the address window on the envelope. This is only available for letters.

Allowed valuesleftright

Default"left"

add_address_sheetboolean

Whether the address is printed on a separate page followed by your letter (If true) or if the address is printed on the same page as your letter (If false).

Defaultfalse

Examplefalse

addressobject

The address the mail item is being sent to.

namestring

The name of the recipient.

Example"John Doe"

linestring

The address line.

Example"123 Main St, Anytown, Anyplace"

postcodestring

The postcode of the address.

Example"AB1 2CD"

countrystring

The country of the address.

Default"GB"

Example"GB"

costobject

The pricing details for the individual mail item.

amountinteger<int64>

This is the basic pre-tax cost of the individual mail item.

All costs amounts returned by the API need to be divided by 10^8 (100000000) to get the real GBP price. We factor in 8 decimal places for sub-penny precision of large bulk orders.

Example100000000

taxinteger<int64>

This is the tax amount applicable to the basic cost of the individual mail item.

We only charge VAT for our customers in the United Kingdom. Customers in other countries will see a tax amount of 0.

All costs amounts returned by the API need to be divided by 10^8 (100000000) to get the real GBP price. We factor in 8 decimal places for sub-penny precision of large bulk orders.

Example20000000

after_taxinteger<int64>

The total cost of the individual mail item after tax.

All costs amounts returned by the API need to be divided by 10^8 (100000000) to get the real GBP price. We factor in 8 decimal places for sub-penny precision of large bulk orders.

Example120000000

currencystring

This is the 3-letter currency code of the cost. This is an ISO 4217 currency code. Example: GBP. We currently only present costs in GBP.

Default"GBP"

Example"GBP"

weightnumber

The calculated weight of the mail item in grams.

Example28

print_streamstring

This is primarily an internal field which describes the printer tray the mail item will be sent to for printing and enclosing.

Example"uk_second_class-c5-standard"

pdf_statusstring

This field describes whether the underlying PDF for a mail item has been deleted or not.

Allowed valuesbuiltdeleted

Default"built"

pdfstring<uri>

A URL to a PDF preview of the mail item. This is a signed URL that will expire after 1 hour. This will be null if the pdf_status is deleted.

Example"https://cdn.storage.com/intelliprint/letters/letter_ID.pdf"

passthrough_exportedboolean

This is primarily an internal field. For certain shipping services, we register mail items with them and keep track of it in this field.

Defaultfalse

Exampletrue

cost

object

The pricing details for the entire print job.

amountinteger<int64>

This is the basic pre-tax cost of the print job.

All costs amounts returned by the API need to be divided by 10^8 (100000000) to get the real GBP price. We factor in 8 decimal places for sub-penny precision of large bulk orders.

Example100000000

taxinteger<int64>

This is the tax amount applicable to the basic cost of the print job.

We only charge VAT for our customers in the United Kingdom. Customers in other countries will see a tax amount of 0.

All costs amounts returned by the API need to be divided by 10^8 (100000000) to get the real GBP price. We factor in 8 decimal places for sub-penny precision of large bulk orders.

Example20000000

after_taxinteger<int64>

The total cost of the print job after tax. This is the amount charged to you for submitting this print job.

All costs amounts returned by the API need to be divided by 10^8 (100000000) to get the real GBP price. We factor in 8 decimal places for sub-penny precision of large bulk orders.

Example120000000

currencystring

This is the 3-letter currency code of the cost. This is an ISO 4217 currency code. Example: GBP. We currently only present costs in GBP.

Default"GBP"

Example"GBP"

confirmation_email

boolean

Whether a confirmation email should be sent to the account owner once the print job is confirmed.

Defaultfalse

Exampletrue

insert

string

This property is not present in the response if an insert ID is not provided while creating or updating a print job. Inserts are a value-added service - We can keep stock of and insert any pre-printed materials provided ahead of time into envelopes for you. Please contact us at hello@intelliprint.net to enable this service for your account.

Example"ins_eg"

template

string

The ID of the template used to create this print job.

Example"tmpl_eg"

mailing_list

string

The ID of the mailing list used to create this print job.

Example"mal_eg"

address_window

string

The position of the address window on the envelope. This is only available for letters.

Allowed valuesleftright

Default"left"

confirmed_at

integer<int64>

The UNIX timestamp of when the print job was confirmed. We use UNIX timestamps to mitigate any timezone-based issues.

Example1761955200

created

integer<int64>

The UNIX timestamp of when the print job was created. We use UNIX timestamps to mitigate any timezone-based issues.

Example1761955200

metadata

object

This is an arbitrary object that can be used to store any additional data alongside your print job. This is not used by Intelliprint and is only for your own use.

400Example error responseapplication/json

error

object

messagestring

A human-readable message describing the error. You can display this to your users to help them understand what went wrong.

Example"Received unknown parameter: testmood (Did you mean testmode?)"

typestring

The general category of the error.

Allowed valuesinvalid_request_errorauthentication_errorpayment_errorrate_limitedinternal_error

Example"invalid_request_error"

codestring

A unique code for the specific error that occurred.

Allowed valuesparameter_invalidparameter_missingparameter_unknownbody_too_largebody_incorrect_formatno_api_keyinvalid_api_keylogged_outforbiddenpayment_errornot_foundrate_limitedrefusedinternal_error

Example"parameter_unknown"

paramstring

The parameter that caused the error, if applicable.

Example"testmood"

Request example

cURL

curl -X POST https://api.intelliprint.net/v1/prints/print-job-id \ 
  -H 'Authorization: YOUR_API_KEY' \ 
  -d 'reference=My updated print job' \ 
  -d 'confirmed=true'

Node.js SDK

Node.js

import Intelliprint from 'intelliprint'
const ip = Intelliprint('your-api-key-here')

const print = await ip.prints.update('print-job-id', {
  reference: 'My updated print job',
  confirmed: true
})

Example response

200 · Successful response

JSON

{
  "id": "print_eg",
  "object": "print",
  "testmode": true,
  "account": "acc_eg",
  "user": null,
  "team": null,
  "reference": "Marketing pamphlet for J. Doe",
  "confirmed": true,
  "type": "letter",
  "pages": 10,
  "sheets": 5,
  "file": {
    "name": "eg_file.pdf",
    "pages": 10,
    "size": 1024000
  },
  "splitting": {
    "method": "none",
    "phrase": "Dear",
    "pages": 1
  },
  "printing": {
    "double_sided": "no",
    "double_sided_specific_pages": [
      0
    ],
    "premium_quality": true,
    "black_and_white": true,
    "matt_finish": true
  },
  "postage": {
    "service": "uk_second_class",
    "ideal_envelope": "c5",
    "mail_date": 1761955200
  },
  "background": {
    "first_page": "bg_eg",
    "other_pages": "bg_eg"
  },
  "confidential": true,
  "extra_documents": [
    {
      "id": "extra_eg",
      "name": "eg_file.pdf",
      "apply_background": true,
      "pages": 10,
      "size": 1024000
    }
  ],
  "remove_letters": {
    "with_phrase": "EMAIL ONLY"
  },
  "nudge": {
    "x": 2,
    "y": -1
  },
  "letters": [
    {
      "id": "letter_eg",
      "object": "letter",
      "status": "draft",
      "postage_service": "uk_second_class",
      "tracking_number": "1234567890",
      "shipped_date": 1761955200,
      "returned": {
        "acknowledged": true,
        "date": 1761955200,
        "reason": "Not at this address"
      },
      "pages": 10,
      "sheets": 5,
      "envelope": "c5",
      "address_window": "left",
      "add_address_sheet": false,
      "address": {
        "name": "John Doe",
        "line": "123 Main St, Anytown, Anyplace",
        "postcode": "AB1 2CD",
        "country": "GB"
      },
      "cost": {
        "amount": 100000000,
        "tax": 20000000,
        "after_tax": 120000000,
        "currency": "GBP"
      },
      "weight": 28,
      "print_stream": "uk_second_class-c5-standard",
      "pdf_status": "built",
      "pdf": "https://cdn.storage.com/intelliprint/letters/letter_ID.pdf",
      "passthrough_exported": true
    }
  ],
  "cost": {
    "amount": 100000000,
    "tax": 20000000,
    "after_tax": 120000000,
    "currency": "GBP"
  },
  "confirmation_email": true,
  "insert": "ins_eg",
  "template": "tmpl_eg",
  "mailing_list": "mal_eg",
  "address_window": "left",
  "confirmed_at": 1761955200,
  "created": 1761955200,
  "metadata": {
    "uploaded_by": "J. Doe",
    "internal_id": "123456"
  }
}

400 · Example error response

JSON

{
  "error": {
    "message": "Received unknown parameter: testmood (Did you mean testmode?)",
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "param": "testmood"
  }
}