Authorization header using HTTP Bearer authentication.All cost amounts must be converted to GBP by taking the amount and dividing it by 100000000 (10**8). We use integers while accounting for 8 decimal places to avoid floating point errors and still being able to provide accurate bulk usage discounts.Intelliprint API Reference
The Intelliprint API is organized around REST. Every resource has a predictable URL. Every endpoint accepts request bodies encoded as JSON, or with form encoding.Responses are JSON-encoded, with standard HTTP status codes.For authentication, we use API keys provided in the
Authentication
You can generate an API key here.Intelliprint API uses account-level API keys to authenticate you to your account. There are no separate API keys for test mode. Instead, when you want to create a test Print Job, just set the
testmode parameter to true.Provide your API key in the Authorization header as HTTP Bearer auth.Testing
To test a Print Job, set
testmode to true while uploading it.You do not pay for test Print Jobs, even if you confirm them. They are never sent out.Test Print Jobs don't show up in the regular list of Print Jobs, you have to set the testmode parameter to true when retrieving the list of Print Jobs to get back testmode Print Jobs.Print Job objects have a testmode boolean attribute which you can use to check if a particular Print Job is in testmode.Testmode Print Jobs are deleted from the system a week after they're confirmed.Here are some demo files you can use for creating a Print Job:A single demo letter.
Use
This file with these splitting options should result in 100 separate letters.
split_by_content and set the splitting word to Dear.This file with these splitting options should result in 100 separate letters.
Rate Limits
The Intelliprint API has a rate limit of 100 requests per 1 minute.If you surpass this limit, the API will reply with the
rate_limited error (HTTP status code 429).If you plan on making more frequent requests than that, you should implement methods that automatically retry a request that fails with the rate_limited error code after waiting for some time.Errors
On top of detailed JSON-encoded error messages, Intelliprint also gives back conventional HTTP status codes you can use to determine the result.
2.x.x status codes mean the request succeeded. 4.x.x status codes mean an error on your end (You can refer to the error.message to learn more). 5.x.x status codes mean an error on Intelliprint's end.Here is a breakdown of the error object:This is a human readable message describing the error.
The type of error. One of
invalid_request_error, authentication_error, rate_limited or internal_error.The error code. One of
body_too_large, body_incorrect_format, parameter_invalid, parameter_missing, parameter_unknown, no_api_key, invalid_api_key, forbidden, payment_error, not_found, rate_limited or internal_error.Not always present. The parameter that caused the error.
Print Jobs
Print Jobs are what you will be interacting with the most. They are the heart of Intelliprint.You can implement Print Jobs however you want. If your use case is entirely programmatic, you can send thousands of letters addressed to thousands of people with just one API call.Or if your use case is based around humans, you can make multiple calls, starting with a draft, previewing it, editing it, and then finally confirming it.
The Print Job Object
The ID of this Print Job object.
The type of object. This is always
print.The ID of the account this Print Job belongs to.
The user object who created this Print Job, can be
null as well.The ID of the team the user belongs to, can be
null as well.A user-provided reference for this Print Job.
Whether this Print Job is confirmed.
The total number of pages in this Print Job.
The total number of paper sheets to be used for this Print Job.
The name of the uploaded file.
The number of pages in the uploaded file.
The size of the uploaded file in bytes.
The splitting method to use for this file. One of
none, split_on_phrase or split_on_pages.The word or phrase to split letters using. Only used when splitting.method is set to
split_on_phrase.The number of pages each letter should be. Only used when splitting.method is set to
split_on_pages.Whether to print these letters double sided. One of
no, yes or mixed.The array of pages to print double sided. Only used when printing.double_sided is set to
mixed. Example: [[1, 3], [6, 7]]Whether to print these letters in premium quality.
The service to send this letter with. One of
uk_second_class, uk_first_class, uk_second_class_signed_for, uk_first_class_signed_for, uk_special_delivery or international.The ideal envelope size for these letters. One of
c4, c5, c4_plus or a4_box.The unix timestamp (Adjusted to day) to send this letter out on.
The ID of the Background to apply to the first page of these letters.
The ID of the Background to apply to all other pages of these letters.
Whether letters of this Print Job are confidential.
An array containing extra documents to be added to letters.
The Extra Document Object
The ID of this extra_document.
The name of this extra_document.
The order of this extra_document. One of
first, last, or custom.Only applicable for
custom ordering. Where in the letter to place this extra_document.Whether to apply the background to this extra_document as well.
The number of pages this extra_document has.
Remove letter objects that have this phrase in their content.
An array of letters' indexes that have been removed.
What amount in mm to move the first page of each letter horizontally. A positive number moves the page right, a negative number moves the page left.
What amount in mm to move the first page of each letter vertically. A positive number moves the page down, a negative number moves the page up.
The array of letters this Print Job will print.
The letter object
This letter's ID.
The type of object. This is always
letter.This letter's status. One of
draft, waiting_to_print, printing, enclosing, shipping, sent, cancelled, returned or failed_wrong_address.The number of pages in this letter.
The number of paper sheets to be used for this letter.
The postage service responsible for delivering this letter. One of
uk_second_class, uk_first_class, uk_second_class_signed_for, uk_first_class_signed_for, uk_special_delivery or international.The envelope used for this letter. One of
c4, c5, c4_plus or a4_box.The address this letter will be sent out to.
The person this letter is addressed to.
The address line for this address.
The postcode for this address.
The 2 character country code for this address.
The tracking number for this letter. Only available for signed for and special delivery postage services.
The print stream under which this letter will be printed.
The UNIX timestamp at which the letter was sent out.
The status of this letter's PDF print-out. Can be one of
built or deletedThe signed URL to view this letter's PDF preview. It is only present if the
pdf_status is built.The cost amount for this letter in integer form while accounting for 8 decimal places (Divide by 100000000 to get a currency unit based number).
The cost amount after tax for this letter in integer form while accounting for 8 decimal places (Divide by 100000000 to get a currency unit based number).
The 3 character currency code for this letter's cost.
The cost amount for this entire Print Job in integer form while accounting for 8 decimal places (Divide by 100000000 to get a currency unit based number).
The cost amount after tax for this entire Print Job in integer form while accounting for 8 decimal places (Divide by 100000000 to get a currency unit based number).
The 3 character currency code for this Print Job's cost.
Whether a confirmation email should be sent to the user or account's email address when this letter is confirmed.
Whether this Print Job is in testmode or not.
The UNIX timestamp of when this Print Job was created.
Boolean declaring whether this Print Job has been confirmed yet or not.
The UNIX timestamp of when this Print Job was confirmed.
A key-value object for storing any information you want to along with this Print Job.
Create a Print Job
Create a new Print Job.Set
confirmed to true once you're sure about the Print Job. You can do this when creating the Print Job itself, or by updating it. A confirmed Print Job cannot be updated anymore and will be sent for printing.REQUEST BODY PARAMETERS
The
multipart/form-data encoded file for this Print Job.An optional user-provided reference for this Print Job.
Whether to confirm this Print Job immediately, or to leave it as a draft.
Whether to mark this Print Job as a test.
The splitting method to use for this file. One of
none, split_on_phrase or split_on_pages.The word or phrase to split letters using. Only used when splitting.method is set to
split_on_phrase.The number of pages each letter should be. Only used when splitting.method is set to
split_on_pages.Whether to print these letters double sided. One of
no, yes or mixed.The array of pages to print double sided. Only used when printing.double_sided is set to
mixed. Example: [[1, 3], [6, 7]]Whether to print these letters in premium quality.
The service to send this letter with. One of
uk_second_class, uk_first_class, uk_second_class_signed_for, uk_first_class_signed_for, uk_special_delivery or international.The ideal envelope size for these letters. One of
c4, c5, c4_plus or a4_box.The unix timestamp (Adjusted to day) to send this letter out on.
The ID of the Background to apply to the first page of these letters.
The ID of the Background to apply to all other pages of these letters.
Whether to mark letters of this Print Job as confidential.
An array containing extra documents to be added to letters.
The Extra Document Object
The ID of an existing extra_document of this Print Job.
The
multipart/form-data encoded file for this extra_document.The order of this extra_document. One of
first, last, or custom.Only applicable for
custom ordering. Where in the letter to place this extra_document.Whether to apply the background to this extra_document as well.
Remove letter objects that have this phrase in their content.
What amount in mm to move the first page of each letter horizontally. A positive number moves the page right, a negative number moves the page left.
What amount in mm to move the first page of each letter vertically. A positive number moves the page down, a negative number moves the page up.
Whether a confirmation email should be sent to the user or account's email address when this letter is confirmed.
A key-value object for storing any information you want to along with this Print Job.
Retrieve a Print Job
Retrieve an existing Print Job.
Update a Print Job
Update an existing Print Job.Set
confirmed to true once you're sure about the Print Job. A confirmed Print Job cannot be updated anymore and will be sent for printing.REQUEST BODY PARAMETERS
An optional user-provided reference for this Print Job.
Whether to confirm this Print Job, or to leave it as a draft.
The splitting method to use for this file. One of
none, split_on_phrase or split_on_pages.The word or phrase to split letters using. Only used when splitting.method is set to
split_on_phrase.The number of pages each letter should be. Only used when splitting.method is set to
split_on_pages.Whether to print these letters double sided. One of
no, yes or mixed.The array of pages to print double sided. Only used when printing.double_sided is set to
mixed. Example: [[1, 3], [6, 7]]Whether to print these letters in premium quality.
The service to send this letter with. One of
uk_second_class, uk_first_class, uk_second_class_signed_for, uk_first_class_signed_for, uk_special_delivery or international.The ideal envelope size for these letters. One of
c4, c5, c4_plus or a4_box.The unix timestamp (Adjusted to day) to send this letter out on.
The ID of the Background to apply to the first page of these letters.
The ID of the Background to apply to all other pages of these letters.
Whether to mark letters of this Print Job as confidential.
An array containing extra documents to be added to letters.
The Extra Document Object
The ID of an existing extra_document of this Print Job.
The
multipart/form-data encoded file for this extra_document.The order of this extra_document. One of
first, last, or custom.Only applicable for
custom ordering. Where in the letter to place this extra_document.Whether to apply the background to this extra_document as well.
Remove letter objects that have this phrase in their content.
What amount in mm to move the first page of each letter horizontally. A positive number moves the page right, a negative number moves the page left.
What amount in mm to move the first page of each letter vertically. A positive number moves the page down, a negative number moves the page up.
Whether a confirmation email should be sent to the user or account's email address when this letter is confirmed.
A key-value object for storing any information you want to along with this Print Job.
Cancel or Delete a Print Job
Deletes an unconfirmed Print Job.If a Print Job is confirmed, all letters in the Print Job with the status
waiting_to_print will be cancelled instead and the amount charged will be refunded. The Print Job will not be deleted.List Print Jobs
By default, only live Print Jobs are returned.
Set the
Set the
testmode parameter to true and the API will return only testmode Print Jobs.Request Query Parameters
Whether to return live or only test mode Print Jobs. By default, only live Print Jobs are returned.
If set to false, only unconfirmed Print Jobs are returned. If set to true, only confirmed Print Jobs are returned.
The comma separated statuses to filter. Any Print Job that has any letter within it with a matching status is returned.
The number of Print Jobs to return. Must be between 1 and 1,000. By default, 10 Print Jobs are returned.
The number of results to skip over before returning. Useful for pagination.
Backgrounds
Use a Background object to add a background to a Print Job.You need to specify the Background's ID to a Print Job's
background.first_page and/or background.other_pages for it to be applied.The Background Object
The ID of this Background object.
The type of object. This is always
background.The user-provided name of this Background.
The name of the uploaded file.
The Team object this Background belongs to.
The URL for a PNG preview image of this Background.
The UNIX timestamp of when this Background was created.
Create a Background
Create a new Background.
REQUEST BODY PARAMETERS
The
multipart/form-data encoded file for this Background.The user-provided name of this Background.
The Team ID to assign this Background to.
Retrieve a Background
Retrieve an existing Background.
Update a Background
Update an existing Background.
REQUEST BODY PARAMETERS
The user-provided name of this Background.
The Team ID to assign this Background to.
Delete a Background
Delete a Background.
List Backgrounds
Request Query Parameters
The Team ID for which Backgrounds to return.
The number of Backgrounds to return. Must be between 1 and 1,000. By default, 10 Backgrounds are returned.
The number of results to skip over before returning. Useful for pagination.
Tools
Modify your files with Tools.
The Merge Tool Object
The ID of this Merge object.
The type of object. This is always
merge.The download link for the resulting file.
Merge Files
Merge multiple files together.
REQUEST BODY PARAMETERS
An array of
multipart/form-data encoded files to merge together.