Skip to content
Intelliprint

Getting Started

Core Concepts

Resources

Introduction

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 information about ourAPI pricing plansand volume discounts, visit our pricing page.

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. As a UK-based service, we integrate directly withRoyal Mail delivery servicesfor optimal reliability.

Base URL

base-url.txt
https://api.rnbdata.uk/v1

SDKs

Browser JavaScript
Node.js
PHP

Authentication

For authentication, we use API keys provided in the Authorization header using HTTP Bearer authentication. Learn more about ourenterprise-grade security practicesfor keeping your API communications secure.

You can generate an API key on our platform. 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.

API Key Authentication

auth-header.txt
Authorization: Bearer YOUR_API_KEY

Security Notice

Keep your API keys secure and never expose them in client-side code. If you believe your API key has been compromised, you can generate a new one from your dashboard.

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.

Demo Files

Here are some demo files you can use for creating a Print Job:

Single Letter

A single demo letter.

Download Demo Letter

Multiple Letters

Use split_by_content and set the splitting word to "Dear". This file with these splitting options should result in 100 separate letters.

Download Multiple 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.

Example Response

rate-limit-error.json
{
  "error": {
    "message": "You're making too many requests, please wait a few seconds then try again",
    "type": "rate_limited",
    "code": "rate_limited"
  }
}

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.

Error Object Breakdown

FieldDescription
messageThis is a human readable message describing the error.
typeThe type of error. One of invalid_request_error, authentication_error, rate_limited or internal_error.
codeThe 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.
paramNot always present. The parameter that caused the error.

Example Error Response

error-response.json
{
  "error": {
    "message": "Missing required param: file",
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "param": "file"
  }
}

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

PropertyDescription
idThe ID of this Background object.
objectThe type of object. This is always background.
nameThe user-provided name of this Background.
filenameThe name of the uploaded file.
teamThe Team object this Background belongs to.
previewThe URL for a PNG preview image of this Background.
createdThe UNIX timestamp of when this Background was created.

Retrieve a Background

Retrieve an existing Background.

GET/v1/backgrounds/{background_id}

Example Request

retrieve-background.sh
curl https://api.rnbdata.uk/v1/backgrounds/bg_ID \
-u key_EXAMPLE:

Example Response

retrieve-background-response.json
{
  "id": "bg_ID",
  "object": "background",
  "name": "background.pdf",
  "filename": "background.pdf",
  "team": null,
  "preview": "https://api.rnbdata.uk/v1/files/pics/bg_ID.png",
  "created": 1629361000
}

Update a Background

Update an existing Background.

PATCH/v1/backgrounds/{background_id}

Request Body Parameters

ParameterDescription
nameThe user-provided name of this Background.
teamThe Team ID to assign this Background to.

Example Request

update-background.sh
curl https://api.rnbdata.uk/v1/backgrounds/bg_ID \
-u key_EXAMPLE: \
-d name="My Background"

Example Response

update-background-response.json
{
  "id": "bg_ID",
  "object": "background",
  "name": "My Background",
  "filename": "background.pdf",
  "team": null,
  "preview": "https://api.rnbdata.uk/v1/files/pics/bg_ID.png",
  "created": 1629361000
}

Delete a Background

Delete a Background.

DELETE/v1/backgrounds/{background_id}

Example Request

delete-background.sh
curl https://api.rnbdata.uk/v1/backgrounds/bg_ID \
-u key_EXAMPLE: \
-X DELETE

Example Response

delete-background-response.json
{
  "id": "bg_ID",
  "object": "background",
  "deleted": true
}

List Backgrounds

List all available Backgrounds.

GET/v1/backgrounds

Request Query Parameters

ParameterDescription
teamThe Team ID for which Backgrounds to return.
limitThe number of Backgrounds to return. Must be between 1 and 1,000. By default, 10 Backgrounds are returned.
skipThe number of results to skip over before returning. Useful for pagination.

Example Request

list-backgrounds.sh
curl https://api.rnbdata.uk/v1/backgrounds \
-u key_EXAMPLE: \
-d limit=1 \
-G

Example Response

list-backgrounds-response.json
{
  "object": "list",
  "data": [
    {
      "id": "bg_ID",
      "object": "background",
      "name": "My Background",
      "filename": "background.pdf",
      "team": null,
      "preview": "https://api.rnbdata.uk/v1/files/pics/bg_ID.png",
      "created": 1629361000
    }
  ],
  "total_available": 1001,
  "has_more": true
}

Tools

Modify your files with Tools.

The Merge Tool Object

PropertyDescription
idThe ID of this Merge object.
objectThe type of object. This is always merge.
download_linkThe download link for the resulting file.

Merge Files

Merge multiple files together.

POST/v1/tools/merge

Request Body Parameters

ParameterDescription
files
REQUIRED
An array of multipart/form-data encoded files to merge together.

Example Request

merge-files.sh
curl https://api.rnbdata.uk/v1/tools/merge \
-u key_EXAMPLE: \
-F files[]=@1.pdf \
-F files[]=@2.pdf

Example Response

merge-files-response.json
{
  "id": "merge_ID",
  "object": "merge",
  "download_link": "https://api.rnbdata.uk/v1/tools/merge/merge_ID/download"
}

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.

Error Object Breakdown

FieldDescription
messageThis is a human readable message describing the error.
typeThe type of error. One of invalid_request_error, authentication_error, rate_limited or internal_error.
codeThe 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.
paramNot always present. The parameter that caused the error.

Example Error Response

error-response.json
{
  "error": {
    "message": "Missing required param: file",
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "param": "file"
  }
}

Register for API Access

To get started with our API, you'll need to create an account and request API credentials. This process ensures that only authorized developers have access to our services.

1. Create an account on our dashboard.

2. Navigate to the "Developers" section of your account.

3. Request API access by clicking the "Enable API Access" button.

Authentication Guide

Once you have API access, you'll need to generate and use your API keys for secure authentication.

1. Generate your API key in the "API Keys" section of the developer dashboard.

2. Securely store your API key - it will only be shown once.

3. Include your API key in the Authorization header of all API requests.

auth-header.txt
Authorization: Bearer YOUR_API_KEY

Sandbox Testing Environment

Before going live, use our sandbox environment to test your integration without sending real mail.

To use the sandbox, simply set testmode to true in your API requests.

Test mode operations have no cost and don't result in real mail being sent.

The sandbox environment functions exactly like production, allowing you to test all API features.

sandbox-example.js
// Example sandbox test request
const response = await axios.post('https://api.rnbdata.uk/v1/prints', {
  // Request parameters
  testmode: true // Enable sandbox mode
}, {
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

Going Live: Production Guide

Once you've thoroughly tested your integration in the sandbox, you're ready to switch to production mode.

1. Ensure you've completed comprehensive testing in the sandbox environment.

2. Set testmode to false or omit it completely in your API requests.

3. Monitor your first few production requests to ensure everything works as expected.

4. Set up webhooks to receive real-time status updates for your mail.

Production Checklist

  • Implement proper error handling
  • Set up retry mechanisms with exponential backoff
  • Secure API key storage
  • Implement address validation
  • Set up proper logging and monitoring

Ready to Integrate?

Get your API key and start sending mail programmatically in minutes.

Get API KeyAPI Reference