Topics
Core API
Forestry API
Paper API
Object Reference
Appendix

PrintReleaf API v1.4.0

Introduction

The PrintReleaf API is organized around REST to have predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors.

It uses built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned in all responses from the API, including errors, and is expected as the body for all requests.

Conventions

  • All data is sent and received as JSON
  • All resource IDs are UUID strings
  • Blank fields are included as null instead of being omitted
  • All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
  • All units are metric: m for units of length; m2 for area; g for mass; g/m2 for density

Access Patterns

Accounts in PrintReleaf are hierarchical, meaning every account can have one parent account and an arbitrary number of child accounts. Each account has a role that determines its abilities.

By default, all resources of the Core API are scoped to your account. The same resources can be accessed for any of your child accounts:

Default Scope: /certificates
/certificates/:id
Account Scope: /accounts/:account_id/certificates
/accounts/:account_id/certificates/:id

API Endpoint

https://api.printreleaf.com/v1/

Authentication

You authenticate to the PrintReleaf API by including your API keys in the request. You can manage your API keys from your PrintReleaf Dashboard.

Authentication to the PrintReleaf API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

# Example Request
$ curl https://api.printreleaf.com/v1/ -u c7686125c49022c9fd3f9662bd2a8:
# curl uses the -u flag to pass basic auth credentials (adding a colon after your API key prevents cURL from asking for a password).

Errors

The PrintReleaf API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with PrintReleaf's servers.

HTTP Status Code Summary

  • 200 OK - Everything worked as expected.
  • 400 Bad Request - Invalid or missing request parameters.
  • 401 Unauthorized - Invalid API key.
  • 403 Forbidden - API keys were provided but the requested action is not authorized.
  • 404 Not Found - The requested resource doesn't exist.
  • 429 Too Many Requests - Rate limit exceeded.
  • 5xx Server errors - Something went wrong on our end.

The Error Object

code:
integer Indicates the type of error.
error:
string A human-readable message giving more details about the error. 
// Example Error Object
{
  "code": 404,
  "error": "Object not found"
}

Getting Started

The PrintReleaf API employs two usage models that can be used independently or in combination:

Transactions

Transactions are realtime exchanges of paper consumption for reforested trees.

When creating a transaction, you have the option to:

  1. Provide the total number of pages to be reforested; or
  2. Provide the total number of trees to be reforested; or
  3. Provide a quote_id to convert a quote to a transaction

In return, when the transaction is created, you will immediately receive a certificate of reforestation as a receipt of the transaction.

This model is ideal for transactional applications; for example, a point-of-sale integration for print jobs.

Using Transactions ›

Deposits

Deposits are periodic additions of paper consumption data to an account.

Over the course of a month, you periodically add deposits to an account; for example, daily meter reads from a device, fleet, or entire business. At the end of the month, the deposits are batched and summed to determine the account's total consumption during that month. A transaction is then automatically executed for the total consumption and the account receives a certificate of reforestation as a receipt of the transaction.

This model is ideal for subscription applications where an account accrues paper consumption over time to be executed as a single big transaction rather than many small transactions.

Our integrations with third-party print monitoring software (FMAudit, PrintFleet, etc.) are powered by this deposits model. Every day our data collectors gather paper consumption data from the print monitoring software and create a deposit for the day's consumption.

Using Deposits ›

Core API

My Account

Retrieves the details of your account.

GET /account

Returns

Returns an expanded account object.

// Example Response
{
  "id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "name": "Channel 123",
  "display_name": "Channel 123",
  "role": "channel",
  "created_at": "2016-12-08T04:00:31Z",
  "parent_id": null,
  "external_id": null,
  "status": "active",
  "activated_at": "2016-12-08T04:00:31Z",
  "deactivated_at": null,
  "accounts_count": 2,
  "users_count": 2,
  "mtd_pages": 1234,
  "qtd_pages": 12345,
  "ytd_pages": 123456,
  "ltd_pages": 1234567,
  "mtd_trees": 0.15,
  "qtd_trees": 1.48,
  "ytd_trees": 14.82,
  "ltd_trees": 148.0
}

Accounts

Listing all accounts

Lists all accounts.

GET /accounts

Returns

Returns an array of account objects, sorted alphabetically.

// Example Response
[
  {
    "id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "name": "Customer ABC",
    "display_name": "Customer ABC",
    "role": "customer",
    "created_at": "2017-12-08T04:00:31Z",
    "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
    "external_id": null,
    "status": "active",
    "activated_at": "2017-12-08T04:00:31Z",
    "deactivated_at": null
  },
  {
    "id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
    "name": "Customer DEF",
    "display_name": "Customer DEF",
    "role": "customer",
    "created_at": "2018-12-08T04:00:31Z",
    "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
    "external_id": null,
    "status": "inactive",
    "activated_at": "2018-12-08T04:00:31Z",
    "deactivated_at": "2019-06-08T04:00:31Z"
  }
]

Retrieving an account

Retrieves the details of an account.

GET /accounts/:id

Arguments

id:
account identifier required

Returns

Returns an expanded account object if a valid identifier was provided, and returns an error otherwise.

// Example Response
{
  "id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "name": "Customer ABC",
  "display_name": "Customer ABC",
  "role": "customer",
  "created_at": "2017-12-08T04:00:31Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2017-12-08T04:00:31Z",
  "deactivated_at": null,
  "accounts_count": 0,
  "users_count": 3,
  "mtd_pages": 1234,
  "qtd_pages": 12345,
  "ytd_pages": 123456,
  "ltd_pages": 1234567,
  "mtd_trees": 0.15,
  "qtd_trees": 1.48,
  "ytd_trees": 14.82,
  "ltd_trees": 148.0
}

Creating an account

To create a new account, supply a name for the account.

POST /accounts

Arguments

name:
string required Name of the account.
Must be unique to the parent account.
display_name:
string optional Name displayed on the account's dashboard, communications, and collateral.
external_id:
string optional Custom external identifier for the account.
Must be unique to the parent account.

Returns

Returns the new expanded account object if valid information was provided, and returns an error otherwise.

// Example Request
{
  "name": "Customer GHI"
}
// Example Response
{
  "id": "6dd962a0-a515-4a83-980e-d3bd7cbb243a",
  "name": "Customer GHI",
  "display_name": "Customer GHI",
  "role": "customer",
  "created_at": "2019-12-08T04:00:31Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2019-12-08T04:00:31Z",
  "deactivated_at": null,
  "accounts_count": 0,
  "users_count": 0,
  "mtd_pages": 0,
  "qtd_pages": 0,
  "ytd_pages": 0,
  "ltd_pages": 0,
  "mtd_trees": 0.0,
  "qtd_trees": 0.0,
  "ytd_trees": 0.0,
  "ltd_trees": 0.0
}

Updating an account

Updates the specified account by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

PATCH /accounts/:id

Arguments

name:
string optional Name of the account.
Must be unique to the parent account.
display_name:
string optional Name displayed on the account's dashboard, communications, and collateral.
external_id:
string optional Custom external identifier for the account.
Must be unique to the parent account.

Returns

Returns the updated expanded account object if valid information was provided, and returns an error otherwise.

// Example Request
{
  "name": "Customer JKL"
}
// Example Response
{
  "id": "6dd962a0-a515-4a83-980e-d3bd7cbb243a",
  "name": "Customer JKL",
  "display_name": "Customer GHI",
  "role": "customer",
  "created_at": "2019-12-08T04:00:31Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2019-12-08T04:00:31Z",
  "deactivated_at": null,
  "accounts_count": 0,
  "users_count": 0,
  "mtd_pages": 0,
  "qtd_pages": 0,
  "ytd_pages": 0,
  "ltd_pages": 0,
  "mtd_trees": 0.0,
  "qtd_trees": 0.0,
  "ytd_trees": 0.0,
  "ltd_trees": 0.0
}

Activating an account

Activates the specified account.

POST /accounts/:id/activate

Arguments

id:
account identifier required

Returns

Returns the updated expanded account object if valid information was provided, and returns an error otherwise.

// Example Response
{
  "id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
  "name": "Customer DEF",
  "display_name": "Customer DEF",
  "role": "customer",
  "created_at": "2018-12-08T04:00:31Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2019-12-08T04:00:31Z",
  "deactivated_at": "2019-06-08T04:00:31Z",
  "accounts_count": 0,
  "users_count": 1,
  "mtd_pages": 2468,
  "qtd_pages": 24690,
  "ytd_pages": 246912,
  "ltd_pages": 2469134,
  "mtd_trees": 0.3,
  "qtd_trees": 2.96,
  "ytd_trees": 29.63,
  "ltd_trees": 296.0
}

Deactivating an account

Dectivates the specified account. Deactivating an account stops data collection, effectively pausing reforestation service.

Once deactivated, users of the account will still be able to sign into their PrintReleaf account to monitor the forests they've already planted, but their account will no longer accrue reforestated pages.

If you need to permanently delete an account, please contact support.

POST /accounts/:id/deactivate

Arguments

id:
account identifier required

Returns

Returns the updated expanded account object if valid information was provided, and returns an error otherwise.

// Example Response
{
  "id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
  "name": "Customer DEF",
  "display_name": "Customer DEF",
  "role": "customer",
  "created_at": "2018-12-08T04:00:31Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "inactive",
  "activated_at": "2018-12-08T04:00:31Z",
  "deactivated_at": "2019-12-08T04:00:31Z",
  "accounts_count": 0,
  "users_count": 1,
  "mtd_pages": 2468,
  "qtd_pages": 24690,
  "ytd_pages": 246912,
  "ltd_pages": 2469134,
  "mtd_trees": 0.3,
  "qtd_trees": 2.96,
  "ytd_trees": 29.63,
  "ltd_trees": 296.0
}

Certificates

Listing certificates

Lists all certificates.

GET /certificates

Arguments

Returns

Returns an array of certificate objects, sorted reverse-chronologically.

// Example Response
[
  {
    "id": "ae630937-e15b-4da5-98de-bb68eefe2a12",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "date": "2019-11-30T23:59:59Z",
    "pages": 2469134,
    "trees": 296.0,
    "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
    "project": {
      "id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
      "name": "Madagascar",
      "status": "active",
      "forest_latitude": -15.735844444444444,
      "forest_longitude": 46.35879166666667,
      "content_logo": "http://s3.amazonaws.com/projects/madagascar/logo.jpg",
      "content_masthead": "http://s3.amazonaws.com/projects/madagascar/masthead.jpg",
      "content_introduction": "Madagascar, due to its isolation...",
      "content_body_html": "<h1>Madagascar is one of the most...",
      "content_images": [
        "http://s3.amazonaws.com/projects/madagascar/1.jpg",
        "http://s3.amazonaws.com/projects/madagascar/2.jpg",
        "http://s3.amazonaws.com/projects/madagascar/3.jpg"
      ]
    },
    "url": "https://printreleaf.com/certificates/ae630937-e15b-4da5-98de-bb68eefe2a12",
    "pdf_url": "https://printreleaf.com/certificates/ae630937-e15b-4da5-98de-bb68eefe2a12.pdf"
  },
  {
    "id": "dfd1cdfc-8535-43d8-8987-9817580ebd2e",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "date": "2019-10-31T23:59:59Z",
    "pages": 469134,
    "trees": 56.3,
    "project_id": "692bb68d-64aa-4a79-8a08-d373fb0d8752",
    "project": {
      "id": "692bb68d-64aa-4a79-8a08-d373fb0d8752",
      "name": "Ethiopia",
      "status": "inactive",
      "forest_latitude": 6.7029261,
      "forest_longitude": 38.7062503,
      "content_logo": "http://s3.amazonaws.com/projects/ethiopia/logo.jpg",
      "content_masthead": "http://s3.amazonaws.com/projects/ethiopia/masthead.jpg",
      "content_introduction": "In Ethiopia deforestation...",
      "content_body_html": "<h1>Due to the absence of...",
      "content_images": [
        "http://s3.amazonaws.com/projects/ethiopia/1.jpg",
        "http://s3.amazonaws.com/projects/ethiopia/2.jpg",
        "http://s3.amazonaws.com/projects/ethiopia/3.jpg"
      ]
    },
    "url": "https://printreleaf.com/certificates/dfd1cdfc-8535-43d8-8987-9817580ebd2e",
    "pdf_url": "https://printreleaf.com/certificates/dfd1cdfc-8535-43d8-8987-9817580ebd2e.pdf"
  }
]

Retrieving a certificate

Retrieves the details of a certificate. Supply a certificate identifier.

GET /certificates/:id

Arguments

id:
certificate identifier required

Returns

Returns a certificate object if a valid identifier was provided, and returns an error otherwise.

// Example Response
{
  "id": "ae630937-e15b-4da5-98de-bb68eefe2a12",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "date": "2019-11-30T23:59:59Z",
  "pages": 2469134,
  "trees": 296.0,
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "project": {
    "id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
    "name": "Madagascar",
    "status": "active",
    "forest_latitude": -15.735844444444444,
    "forest_longitude": 46.35879166666667,
    "content_logo": "http://s3.amazonaws.com/projects/madagascar/logo.jpg",
    "content_masthead": "http://s3.amazonaws.com/projects/madagascar/masthead.jpg",
    "content_introduction": "Madagascar, due to its isolation...",
    "content_body_html": "<h1>Madagascar is one of the most...",
    "content_images": [
      "http://s3.amazonaws.com/projects/madagascar/1.jpg",
      "http://s3.amazonaws.com/projects/madagascar/2.jpg",
      "http://s3.amazonaws.com/projects/madagascar/3.jpg"
    ]
  },
  "url": "https://printreleaf.com/certificates/ae630937-e15b-4da5-98de-bb68eefe2a12",
  "pdf_url": "https://printreleaf.com/certificates/ae630937-e15b-4da5-98de-bb68eefe2a12.pdf"
}

Deposits

Deposits are periodic additions of paper consumption data to an account.

Over the course of a month, you periodically add deposits to an account; for example, daily meter reads from a device, fleet, or entire business. At the end of the month, the deposits are batched and summed to determine the account's total consumption during that month. A transaction is then automatically executed for the total consumption and the account receives a certificate of reforestation as a receipt of the transaction.

Learn more about Deposits ›



Listing deposits

Lists all deposits.

GET /deposits
GET /deposits?start_date=2019-11-08

Arguments

start_date:
date optional Filter start date in YYYY-MM-DD format.
end_date:
date optional Filter end date in YYYY-MM-DD format.

Returns

Returns an array of deposit objects, sorted reverse-chronologically by date.

// Example Response
[
  {
    "id": "a86d591c-3c29-4bef-82c3-7a007fb6b19c",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "feed_id": "44e182ed-cd50-4fa1-af90-e77dd6d6a78c",
    "date": "2016-07-05T12:29:12Z",
    "pages": 20000,
    "width": 0.2127,
    "length": 0.2762,
    "density": 216
  },
  {
    "id": "85034431-db14-47c1-a965-632e8471e573",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "feed_id": null,
    "date": "2016-07-04T09:45:25Z",
    "pages": 16666,
    "width": 0.2159,
    "length": 0.2794,
    "density": 75
  }
]

Retrieving a deposit

Retrieves the details of a deposit. Supply a deposit identifier.

GET /deposits/:id

Arguments

id:
deposit identifier required

Returns

Returns an deposit object if a valid identifier was provided, and returns an error otherwise.

// Example Response
{
  "id": "a86d591c-3c29-4bef-82c3-7a007fb6b19c",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "feed_id": "44e182ed-cd50-4fa1-af90-e77dd6d6a78c",
  "date": "2016-07-05T12:29:12Z",
  "pages": 20000,
  "width": 0.2127,
  "length": 0.2762,
  "density": 216
}

Creating a deposit

Creates a new deposit.

POST /deposits

Arguments

pages:
integer required Number of pages in this deposit.
May be negative (ex. an adjustment)
width:
float optional Width (m) of this deposit's paper size.
Defaults to 0.2159 m (8.5 inches).
length:
float optional Length (m) of this deposit's paper size.
Defaults to 0.2794 m (11 inches).
density:
integer optional Density (g/m2) of this deposit's paper.
Defaults to 75 (standard 20# Bond/Writing/Ledger).
date:
timestamp optional Date of the deposit.

Returns

Returns the new deposit object if valid information was provided, and returns an error otherwise.

// Example Request
{
  "pages": 16666
}
// Example Response
{
  "id": "85034431-db14-47c1-a965-632e8471e573",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "feed_id": null,
  "date": "2016-07-04T09:45:25Z",
  "pages": 16666,
  "width": 0.2159,
  "length": 0.2794,
  "density": 75
}

Deleting a deposit

To delete a deposit, supply the deposit identifier.

Deleting a deposit is permitted until the deposit has been converted to a transaction at the end of the period, at which point it becomes locked.

DELETE /deposits/:id

Arguments

id:
deposit identifier required

Returns

Returns an object with a deleted parameter on success. If the deposit does not exist or deleting this deposit is not permitted, this call returns an an error. 

// Example Response
{
  "id": "a86d591c-3c29-4bef-82c3-7a007fb6b19c",
  "deleted": true
}

Favorite Projects

Listing favorite projects

Lists the account's selected reforestation projects.

GET /projects

Returns

Returns an array of project objects.

// Example Response
[
  {
    "id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
    "name": "Madagascar",
    "status": "active",
    "forest_latitude": -15.735844444444444,
    "forest_longitude": 46.35879166666667,
    "content_logo": "http://s3.amazonaws.com/projects/madagascar/logo.jpg",
    "content_masthead": "http://s3.amazonaws.com/projects/madagascar/masthead.jpg",
    "content_introduction": "Madagascar, due to its isolation...",
    "content_body_html": "<h1>Madagascar is one of the most...",
    "content_images": [
      "http://s3.amazonaws.com/projects/madagascar/1.jpg",
      "http://s3.amazonaws.com/projects/madagascar/2.jpg",
      "http://s3.amazonaws.com/projects/madagascar/3.jpg"
    ]
  }
]

Adding a favorite reforestation project

To add a reforestation project to favorites, supply the project identifier.

POST /projects/:id

Arguments

id:
project identifier required

Returns

Returns the updated array of project objects.

POST /projects/692bb68d-64aa-4a79-8a08-d373fb0d8752
// Example Response
[
  {
    "id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
    "name": "Madagascar",
    "status": "active",
    "forest_latitude": -15.735844444444444,
    "forest_longitude": 46.35879166666667,
    "content_logo": "http://s3.amazonaws.com/projects/madagascar/logo.jpg",
    "content_masthead": "http://s3.amazonaws.com/projects/madagascar/masthead.jpg",
    "content_introduction": "Madagascar, due to its isolation...",
    "content_body_html": "<h1>Madagascar is one of the most...",
    "content_images": [
      "http://s3.amazonaws.com/projects/madagascar/1.jpg",
      "http://s3.amazonaws.com/projects/madagascar/2.jpg",
      "http://s3.amazonaws.com/projects/madagascar/3.jpg"
    ]
  },
  {
    "id": "692bb68d-64aa-4a79-8a08-d373fb0d8752",
    "name": "Ethiopia",
    "status": "inactive",
    "forest_latitude": 6.7029261,
    "forest_longitude": 38.7062503,
    "content_logo": "http://s3.amazonaws.com/projects/ethiopia/logo.jpg",
    "content_masthead": "http://s3.amazonaws.com/projects/ethiopia/masthead.jpg",
    "content_introduction": "In Ethiopia deforestation...",
    "content_body_html": "<h1>Due to the absence of...",
    "content_images": [
      "http://s3.amazonaws.com/projects/ethiopia/1.jpg",
      "http://s3.amazonaws.com/projects/ethiopia/2.jpg",
      "http://s3.amazonaws.com/projects/ethiopia/3.jpg"
    ]
  }
]

Dropping a favorite reforestation project

To remove a reforestation project from favorites, supply the project identifier.

DELETE /projects/:id

Arguments

id:
project identifier required

Returns

Returns the updated array of project objects.

DELETE /projects/692bb68d-64aa-4a79-8a08-d373fb0d8752
// Example Response
[
  {
    "id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
    "name": "Madagascar",
    "status": "active",
    "forest_latitude": -15.735844444444444,
    "forest_longitude": 46.35879166666667,
    "content_logo": "http://s3.amazonaws.com/projects/madagascar/logo.jpg",
    "content_masthead": "http://s3.amazonaws.com/projects/madagascar/masthead.jpg",
    "content_introduction": "Madagascar, due to its isolation...",
    "content_body_html": "<h1>Madagascar is one of the most...",
    "content_images": [
      "http://s3.amazonaws.com/projects/madagascar/1.jpg",
      "http://s3.amazonaws.com/projects/madagascar/2.jpg",
      "http://s3.amazonaws.com/projects/madagascar/3.jpg"
    ]
  }
]

Feeds

A feed configures an account for automatic collection of page count data from a third-party integration. Feeds create deposits for accounts. An account can have any number of feeds.



Listing feeds

Lists all feeds.

GET /feeds

Arguments

Returns

Returns an array of feed objects, sorted reverse-chronologically by activated_at.

// Example Response
[
  {
    "id": "06d88c48-c8c3-4b11-a267-18f5b4e8dacc",
    "account_id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
    "type": "printfleet",
    "server_id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
    "external_id": "732ec0d3-20e3-439e-94e6-e64b40eb533a",
    "collection_scope": "all",
    "created_at": "2017-12-08T04:00:31Z",
    "status": "inactive",
    "activated_at": "2017-12-08T04:00:31Z",
    "deactivated_at": "2018-12-08T04:00:31Z",
    "health_check": "unhealthy",
    "health_check_checked_at": "2019-12-08T04:00:31Z",
    "health_check_changed_at": "2019-12-08T04:00:31Z"
  },
  {
    "id": "44e182ed-cd50-4fa1-af90-e77dd6d6a78c",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "type": "fmaudit",
    "server_id": "eadabb78-b199-43cb-adbd-ab36ce5c5a10",
    "external_id": "456",
    "collection_scope": "managed_only",
    "created_at": "2018-12-08T04:00:31Z",
    "status": "active",
    "activated_at": "2018-12-08T04:00:31Z",
    "deactivated_at": null,
    "health_check": "healthy",
    "health_check_checked_at": "2019-12-08T04:00:31Z",
    "health_check_changed_at": "2019-12-08T04:00:31Z"
  }
]

Retrieving a feed

Retrieves the details of a feed. Supply a feed identifier.

GET /feeds/:id

Arguments

id:
feed identifier required

Returns

Returns a feed object if a valid identifier was provided, and returns an error otherwise.

// Example Response
{
  "id": "44e182ed-cd50-4fa1-af90-e77dd6d6a78c",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "type": "fmaudit",
  "server_id": "eadabb78-b199-43cb-adbd-ab36ce5c5a10",
  "external_id": "456",
  "collection_scope": "managed_only",
  "created_at": "2018-12-08T04:00:31Z",
  "status": "active",
  "activated_at": "2018-12-08T04:00:31Z",
  "deactivated_at": null,
  "health_check": "healthy",
  "health_check_checked_at": "2019-12-08T04:00:31Z",
  "health_check_changed_at": "2019-12-08T04:00:31Z"
}

Creating a feed

To create a new feed, supply the type, server identifier, and external id for the feed.

POST /feeds

Arguments

type:
string required The type of the feed to create.
server_id:
uuid optional Server identifier for this feed.
Some feed types do not require a server_id parameter.
external_id:
string optional External ID credential for this feed.
Some feed types do not require an external_id parameter.
collection_scope:
string optional Collection scope setting of the feed.
Only applies to feed types for print monitoring software that have a notion of 'managed' vs. 'unmanaged'.
Can be 'all' or 'managed_only'. Defaults to 'all'.
{all, managed_only}
activated_at:
timestamp optional Date the feed was activated.
Defaults to the first day of the current month.

Returns

Returns the new feed object if valid information was provided, and returns an error otherwise.

// Example Request
{
  "type": "printfleet",
  "server_id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
  "external_id": "732ec0d3-20e3-439e-94e6-e64b40eb533a"
}
// Example Response
{
  "id": "06d88c48-c8c3-4b11-a267-18f5b4e8dacc",
  "account_id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
  "type": "printfleet",
  "server_id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
  "external_id": "732ec0d3-20e3-439e-94e6-e64b40eb533a",
  "collection_scope": "all",
  "created_at": "2017-12-08T04:00:31Z",
  "status": "active",
  "activated_at": "2019-12-08 04:00:31 +0000",
  "deactivated_at": null,
  "health_check": "unhealthy",
  "health_check_checked_at": "2019-12-08T04:00:31Z",
  "health_check_changed_at": "2019-12-08T04:00:31Z"
}

Updating a feed

Updates the feed by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

PATCH /feeds/:id

Arguments

id:
feed identifier required
server_id:
uuid optional Server identifier for this feed.
Some feed types do not require a server_id parameter.
external_id:
string optional External ID credential for this feed.
Some feed types do not require an external_id parameter.

Returns

Returns the updated feed object if valid information was provided, and returns an error otherwise.

// Example Request
{
  "external_id": "732ec0d3-20e3-439e-94e6-e64b40eb533a"
}
// Example Response
{
  "id": "06d88c48-c8c3-4b11-a267-18f5b4e8dacc",
  "account_id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
  "type": "printfleet",
  "server_id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
  "external_id": "732ec0d3-20e3-439e-94e6-e64b40eb533a",
  "collection_scope": "all",
  "created_at": "2017-12-08T04:00:31Z",
  "status": "inactive",
  "activated_at": "2017-12-08T04:00:31Z",
  "deactivated_at": "2018-12-08T04:00:31Z",
  "health_check": "unhealthy",
  "health_check_checked_at": "2019-12-08T04:00:31Z",
  "health_check_changed_at": "2019-12-08T04:00:31Z"
}

Deleting a feed

To delete a feed, supply the feed identifier.

DELETE /feeds/:id

Arguments

id:
feed identifier required

Returns

Returns an object with a deleted parameter on success. If the feed does not exist, this call returns an an error. 

// Example Response
{
  "id": "06d88c48-c8c3-4b11-a267-18f5b4e8dacc",
  "deleted": true
}

Activating a feed

Activates the specified feed.

POST /feeds/:id/activate

Arguments

id:
feed identifier required

Returns

Returns the updated feed object if valid information was provided, and returns an error otherwise.

// Example Response
{
  "id": "06d88c48-c8c3-4b11-a267-18f5b4e8dacc",
  "account_id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
  "type": "printfleet",
  "server_id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
  "external_id": "732ec0d3-20e3-439e-94e6-e64b40eb533a",
  "collection_scope": "all",
  "created_at": "2017-12-08T04:00:31Z",
  "status": "active",
  "activated_at": "2019-12-08T04:00:31Z",
  "deactivated_at": "2018-12-08T04:00:31Z",
  "health_check": "unhealthy",
  "health_check_checked_at": "2019-12-08T04:00:31Z",
  "health_check_changed_at": "2019-12-08T04:00:31Z"
}

Deactivating a feed

Dectivates the specified feed. Deactivating a feed stops automatic data collection from that integration.

POST /feeds/:id/deactivate

Arguments

id:
feed identifier required

Returns

Returns the updated feed object if valid information was provided, and returns an error otherwise.

// Example Response
{
  "id": "06d88c48-c8c3-4b11-a267-18f5b4e8dacc",
  "account_id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
  "type": "printfleet",
  "server_id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
  "external_id": "732ec0d3-20e3-439e-94e6-e64b40eb533a",
  "collection_scope": "all",
  "created_at": "2017-12-08T04:00:31Z",
  "status": "inactive",
  "activated_at": "2017-12-08T04:00:31Z",
  "deactivated_at": "2019-12-08T04:00:31Z",
  "health_check": "unhealthy",
  "health_check_checked_at": "2019-12-08T04:00:31Z",
  "health_check_changed_at": "2019-12-08T04:00:31Z"
}

Quotes

Listing quotes

Lists all quotes.

GET /quotes

Returns

Returns an array of quote objects, sorted reverse-chronologically by created_at.

// Example Response
[
  {
    "id": "83d12ee9-a187-489d-a93f-3096238f1f86",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
    "created_at": "2015-10-22T00:37:11Z",
    "trees": 63.047762,
    "standard_pages": 518373,
    "mass": 2345215.091819,
    "price": 157.61,
    "transaction_id": null
  },
  {
    "id": "e9ad2b00-409a-49a5-a05c-93f63329d3af",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
    "created_at": "2015-10-22T00:37:11Z",
    "trees": 2.0,
    "standard_pages": 16666,
    "mass": 75400.058877,
    "price": 6.66,
    "transaction_id": null
  }
]

Retrieving a quote

Retrieves the details of a quote. Supply a quote identifier.

GET /quotes/:id

Arguments

id:
quote identifier required

Returns

Returns an expanded quote object if a valid identifier was provided, and returns an error otherwise.

// Example Response
{
  "id": "83d12ee9-a187-489d-a93f-3096238f1f86",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "created_at": "2015-10-22T00:37:11Z",
  "trees": 63.047762,
  "standard_pages": 518373,
  "mass": 2345215.091819,
  "price": 157.61,
  "transaction_id": null,
  "items": [
    {
      "quantity": 20000,
      "width": 0.2127,
      "length": 0.2762,
      "density": 216,
      "paper_type_id": "a11c7abc-011e-462f-babb-3c6375fa6473",
      "mass": 253793.177897
    },
    {
      "quantity": 400000,
      "width": 0.2127,
      "length": 0.2762,
      "density": 89,
      "paper_type_id": "bbd0f271-2f9e-494c-b2af-7f9354b310ad",
      "mass": 2091421.913922
    }
  ]
}

Creating a quote

To create a new quote, supply the raw paper consumption data and PrintReleaf will equate it to the number of trees deforested to produce that paper.

POST /quotes

Quote Arguments

project_id:
uuid required Project identifier.

Quote Items Arguments

quantity:
integer required Paper quantity for this item (sheets/pages/etc.)
width:
float required Width (m) of the item's paper size.
Defaults to 0.2159 m (8.5 inches).
length:
float required Length (m) of the item's paper size.
Defaults to 0.2794 m (11 inches).
density:
integer required Density (g/m2) of this item's paper.
Defaults to 75 (standard 20# Bond/Writing/Ledger).
Conflicts with paper_type_id.
paper_type_id:
uuid optional Paper type identifier.
Is null when the item does not have a paper type.
Conflicts with density.
mass:
float optional Mass (g) of this item's paper.
Optionally supply the mass of the item in lieu of specs.
Conflicts with quantity, width, length, density, and paper_type_id.

Returns

Returns the new expanded quote object if valid information was provided, and returns an error otherwise.

// Example Request (providing paper specs)
{
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "items": [
    {
      "quantity": 16666,
      "width": 0.2159,
      "length": 0.2794,
      "density": 75
    }
  ]
}
// Example Request (providing `mass`)
{
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "items": [
    {
      "mass": 75400.058877
    }
  ]
}
// Example Response
{
  "id": "e9ad2b00-409a-49a5-a05c-93f63329d3af",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "created_at": "2015-10-22T00:37:11Z",
  "trees": 2.0,
  "standard_pages": 16666,
  "mass": 75400.058877,
  "price": 6.66,
  "transaction_id": null,
  "items": [
    {
      "quantity": 16666,
      "width": 0.2159,
      "length": 0.2794,
      "density": 75,
      "paper_type_id": null,
      "mass": 75400.058877
    }
  ]
}

Deleting a quote

To delete a quote, supply the quote identifier.

Deleting a quote is permitted unless the quote has been transacted upon.

DELETE /quotes/:id

Arguments

id:
quote identifier required

Returns

Returns an object with a deleted parameter on success. If the quote does not exist or deleting this quote is not permitted, this call returns an an error. 

// Example Response
{
  "id": "83d12ee9-a187-489d-a93f-3096238f1f86",
  "deleted": true
}

Servers

Listing servers

Lists all servers.

GET /servers

Arguments

Returns

Returns an array of server objects, sorted reverse-chronologically.

// Example Response
[
  {
    "id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
    "account_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
    "type": "printfleet",
    "url": "https://myprintfleetserver.com",
    "username": "MyPrintFleetUsername",
    "contact": "sally@example.com",
    "created_at": "2017-12-08T04:00:31Z"
  },
  {
    "id": "eadabb78-b199-43cb-adbd-ab36ce5c5a10",
    "account_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
    "type": "fmaudit",
    "url": "https://myfmauditserver.com",
    "username": "MyFMAuditUsername",
    "contact": "bob@example.com",
    "created_at": "2017-12-08T04:00:31Z"
  }
]

Retrieving a server

Retrieves the details of a server. Supply a server identifier.

GET /servers/:id

Arguments

id:
server identifier required

Returns

Returns a server object if a valid identifier was provided, and returns an error otherwise.

// Example Response
{
  "id": "eadabb78-b199-43cb-adbd-ab36ce5c5a10",
  "account_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "type": "fmaudit",
  "url": "https://myfmauditserver.com",
  "username": "MyFMAuditUsername",
  "contact": "bob@example.com",
  "created_at": "2017-12-08T04:00:31Z"
}

Creating a server

To create a new server, supply the type, url, username, password, and contact for the server.

POST /servers

Arguments

type:
string required The type of the server to create.
url:
string required URL of the server.
username:
string required Username credential of the server.
password:
string optional Password credential of the server.
Some server types do not require a password parameter.
contact:
string required Email PrintReleaf can contact for support with the server.

Returns

Returns the new server object if valid information was provided, and returns an error otherwise.

// Example Request
{
  "type": "printfleet",
  "url": "https://myprintfleetserver.com",
  "username": "MyPrintFleetUsername",
  "contact": "sally@example.com",
  "password": "MyPrintFleetPassword"
}
// Example Response
{
  "id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
  "account_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "type": "printfleet",
  "url": "https://myprintfleetserver.com",
  "username": "MyPrintFleetUsername",
  "contact": "sally@example.com",
  "created_at": "2017-12-08T04:00:31Z"
}

Updating a server

Updates the server by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

PATCH /servers/:id

Arguments

id:
server identifier required
url:
string required URL of the server.
username:
string required Username credential of the server.
password:
string optional Password credential of the server.
Some server types do not require a password parameter.
contact:
string required Email PrintReleaf can contact for support with the server.

Returns

Returns the updated server object if valid information was provided, and returns an error otherwise.

// Example Request
{
  "username": "MyUpdatedPrintFleetPassword"
}
// Example Response
{
  "id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
  "account_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "type": "printfleet",
  "url": "https://myprintfleetserver.com",
  "username": "MyUpdatedPrintFleetPassword",
  "contact": "sally@example.com",
  "created_at": "2017-12-08T04:00:31Z"
}

Deleting a server

To delete a server, supply the server identifier.

DELETE /servers/:id

Arguments

id:
server identifier required

Returns

Returns an object with a deleted parameter on success. If the server does not exist, this call returns an an error. 

// Example Response
{
  "id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
  "deleted": true
}

Transactions

Transactions are realtime exchanges of paper consumption for reforested trees.

Learn more about Transactions ›



Listing transactions

Lists all transactions.

GET /transactions
GET /transactions?start_date=2019-11-08

Arguments

start_date:
date optional Filter start date in YYYY-MM-DD format.
end_date:
date optional Filter end date in YYYY-MM-DD format.

Returns

Returns an array of transaction objects, sorted reverse-chronologically by date.

// Example Response
[
  {
    "id": "70af5540-e3ec-4db7-bc45-4fb65b74368b",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "quote_id": "83d12ee9-a187-489d-a93f-3096238f1f86",
    "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
    "certificate_id": "70af5540-e3ec-4db7-bc45-4fb65b74368b",
    "date": "2015-10-22T01:52:12Z",
    "pages": 525379,
    "trees": 63.048
  },
  {
    "id": "def0f271-2f9e-494c-b2af-7f9354b310ad",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "quote_id": null,
    "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
    "certificate_id": "def0f271-2f9e-494c-b2af-7f9354b310ad",
    "date": "2015-10-21T19:45:25Z",
    "pages": 16666,
    "trees": 2.0
  }
]

Retrieving a transaction

Retrieves the details of a transaction. Supply a transaction identifier.

GET /transactions/:id

Arguments

id:
transaction identifier required

Returns

Returns a transaction object if a valid identifier was provided, and returns an error otherwise.

// Example Response
{
  "id": "def0f271-2f9e-494c-b2af-7f9354b310ad",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "quote_id": null,
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "certificate_id": "def0f271-2f9e-494c-b2af-7f9354b310ad",
  "date": "2015-10-21T19:45:25Z",
  "pages": 16666,
  "trees": 2.0
}

Creating a transaction

When creating a transaction, you have the option to:

  1. Provide the total number of pages to be reforested; or
  2. Provide the total number of trees to be reforested; or
  3. Provide a quote_id to convert a quote to a transaction

Optionally provide a project_id to identify at which forestry project you would like the trees to be planted.

After the transaction is received, you will immediately receive a certificate of reforestation as a receipt of the transaction.

POST /transactions

Arguments

pages:
integer required Number of pages to be reforested.
trees:
float optional Number of trees to be reforested.
Conflicts with pages.
project_id:
uuid optional The project where this transaction's trees should be planted. If missing or null, PrintReleaf will choose a project at random.
date:
timestamp optional Date of the transaction.
quote_id:
uuid optional Quote identifier.
Conflicts with pages, trees, and project_id.

Returns

Returns the new transaction object if valid information was provided, and returns an error otherwise.

// Example Request (providing `pages`)
{
  "pages": 16666
}
// Example Response
{
  "id": "def0f271-2f9e-494c-b2af-7f9354b310ad",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "quote_id": null,
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "certificate_id": "def0f271-2f9e-494c-b2af-7f9354b310ad",
  "date": "2015-10-21T19:45:25Z",
  "pages": 16666,
  "trees": 2.0
}
// Example Request (providing `trees`)
{
  "trees": 2.0
}
// Example Response
{
  "id": "def0f271-2f9e-494c-b2af-7f9354b310ad",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "quote_id": null,
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "certificate_id": "def0f271-2f9e-494c-b2af-7f9354b310ad",
  "date": "2015-10-21T19:45:25Z",
  "pages": 16666,
  "trees": 2.0
}
// Example Request (providing `quote_id`)
{
  "quote_id": "83d12ee9-a187-489d-a93f-3096238f1f86"
}
// Example Response
{
  "id": "70af5540-e3ec-4db7-bc45-4fb65b74368b",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "quote_id": "83d12ee9-a187-489d-a93f-3096238f1f86",
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "certificate_id": "70af5540-e3ec-4db7-bc45-4fb65b74368b",
  "date": "2015-10-22T01:52:12Z",
  "pages": 525379,
  "trees": 63.048
}

Deleting a transaction

To delete a transaction, supply the transaction identifier.

Deleting a transaction is permitted until the transaction has been billed to your account, at which point it becomes locked.

DELETE /transactions/:id

Arguments

id:
transaction identifier required

Returns

Returns an object with a deleted parameter on success. If the transaction does not exist or deleting this transaction is not permitted, this call returns an an error. 

// Example Response
{
  "id": "70af5540-e3ec-4db7-bc45-4fb65b74368b",
  "deleted": true
}

Users

Listing users

Lists all users.

GET /users

Arguments

Returns

Returns an array of user objects, sorted by name.

// Example Response
[
  {
    "id": "5f25569f-ec0d-4ff3-a6ce-0456ac79b84d",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "name": "David Example",
    "email": "david@example.com",
    "locale": "en",
    "created_at": "2018-12-08T04:00:31Z"
  },
  {
    "id": "5f25569f-ec0d-4ff3-a6ce-0456ac79b84d",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "name": "Sally Example",
    "email": "sally@example.com",
    "locale": "en",
    "created_at": "2017-12-08T04:00:31Z"
  }
]

Retrieving a user

Retrieves the details of a user. Supply a user identifier.

GET /users/:id

Arguments

id:
user identifier required

Returns

Returns a user object if a valid identifier was provided, and returns an error otherwise.

// Example Response
{
  "id": "5f25569f-ec0d-4ff3-a6ce-0456ac79b84d",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "name": "Sally Example",
  "email": "sally@example.com",
  "locale": "en",
  "created_at": "2017-12-08T04:00:31Z"
}

Creating a user

To create a new user, supply an email address for the user. Optionally provide a locale for the user. All user interfaces and communications will be displayed in the user's locale.

POST /users

Arguments

email:
string required Email address of the user.
Must be unique to the account.
locale:
string optional Locale setting of the user.
{en, de, es, fr, it, pt}
Defaults to 'en'.

Returns

Returns the new user object if valid information was provided, and returns an error otherwise.

// Example Request
{
  "email": "sally@example.com",
  "locale": "pt"
}
// Example Response
{
  "id": "5f25569f-ec0d-4ff3-a6ce-0456ac79b84d",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "name": "Sally Example",
  "email": "sally@example.com",
  "locale": "pt",
  "created_at": "2017-12-08T04:00:31Z"
}

Deleting a user

To delete a user, supply the user identifier.

DELETE /users/:id

Arguments

id:
user identifier required

Returns

Returns an object with a deleted parameter on success. If the user does not exist, this call returns an an error. 

// Example Response
{
  "id": "5f25569f-ec0d-4ff3-a6ce-0456ac79b84d",
  "deleted": true
}

Volume

Listing volume summary history

Lists entire volume history summarized by period.

GET /volume
GET /volume?period=monthly

Arguments

period:
string optional Period to group the volume history.
{daily, monthly, yearly}
Defaults to 'monthly'.
start_date:
date optional Filter start date in YYYY-MM-DD format.
Defaults to the last day of the current month.
end_date:
date optional Filter end date in YYYY-MM-DD format.
Defaults to the first day of the current month in the previous year.

Returns

Returns an array of volume period objects, sorted chronologically.

// Example Response
[
  {
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "date": "2019-10-01T00:00:00Z",
    "pages": 234567,
    "trees": 56.3
  },
  {
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "date": "2019-11-01T00:00:00Z",
    "pages": 2469134,
    "trees": 296.0
  }
]

Forestry API

Reforestation Projects

Listing all projects

Lists all projects.

GET /forestry/projects

Returns

Returns an array of project objects, sorted by the date they were created.

// Example Response
[
  {
    "id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
    "name": "Madagascar",
    "status": "active",
    "forest_latitude": -15.735844444444444,
    "forest_longitude": 46.35879166666667,
    "content_logo": "http://s3.amazonaws.com/projects/madagascar/logo.jpg",
    "content_masthead": "http://s3.amazonaws.com/projects/madagascar/masthead.jpg",
    "content_introduction": "Madagascar, due to its isolation...",
    "content_body_html": "<h1>Madagascar is one of the most...",
    "content_images": [
      "http://s3.amazonaws.com/projects/madagascar/1.jpg",
      "http://s3.amazonaws.com/projects/madagascar/2.jpg",
      "http://s3.amazonaws.com/projects/madagascar/3.jpg"
    ]
  },
  {
    "id": "692bb68d-64aa-4a79-8a08-d373fb0d8752",
    "name": "Ethiopia",
    "status": "inactive",
    "forest_latitude": 6.7029261,
    "forest_longitude": 38.7062503,
    "content_logo": "http://s3.amazonaws.com/projects/ethiopia/logo.jpg",
    "content_masthead": "http://s3.amazonaws.com/projects/ethiopia/masthead.jpg",
    "content_introduction": "In Ethiopia deforestation...",
    "content_body_html": "<h1>Due to the absence of...",
    "content_images": [
      "http://s3.amazonaws.com/projects/ethiopia/1.jpg",
      "http://s3.amazonaws.com/projects/ethiopia/2.jpg",
      "http://s3.amazonaws.com/projects/ethiopia/3.jpg"
    ]
  }
]

Retrieving a project

Retrieves the details of a project. Supply a project identifier.

GET /forestry/projects/:id

Arguments

id:
project identifier required

Returns

Returns a project object if a valid identifier was provided, and returns an error otherwise.

// Example Response
{
  "id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "name": "Madagascar",
  "status": "active",
  "forest_latitude": -15.735844444444444,
  "forest_longitude": 46.35879166666667,
  "content_logo": "http://s3.amazonaws.com/projects/madagascar/logo.jpg",
  "content_masthead": "http://s3.amazonaws.com/projects/madagascar/masthead.jpg",
  "content_introduction": "Madagascar, due to its isolation...",
  "content_body_html": "<h1>Madagascar is one of the most...",
  "content_images": [
    "http://s3.amazonaws.com/projects/madagascar/1.jpg",
    "http://s3.amazonaws.com/projects/madagascar/2.jpg",
    "http://s3.amazonaws.com/projects/madagascar/3.jpg"
  ]
}

Paper API

Paper Types

Listing all paper types

Lists all available paper types, including the full set of PrintReleaf default paper types and any custom paper types you have created.

GET /paper/types

Returns

Returns an array of paper type objects.

// Example Response
[
  {
    "id": "a11c7abc-011e-462f-babb-3c6375fa6473",
    "account_id": null,
    "name": "80# #2 Gloss Cover",
    "density": 216
  },
  {
    "id": "bbd0f271-2f9e-494c-b2af-7f9354b310ad",
    "account_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
    "name": "60# #3 Gloss Text",
    "density": 89
  }
]

Retrieving a paper type

Retrieves the details of a paper type. Supply a paper type identifier.

GET /paper/types/:id

Arguments

id:
paper type identifier required

Returns

Returns a paper type object if a valid identifier was provided, and returns an error otherwise.

// Example Response
{
  "id": "d3c3e1df-5e55-4587-9d81-91ac87927424",
  "account_id": null,
  "name": "20# Bond/Writing/Ledger",
  "density": 75
}

Creating a custom paper type

In addition to the list of PrintReleaf default paper types, you may build a portfolio of your own paper types that are only visible to your account.

Creates a new custom paper type, only visible to your account.

POST /paper/types

Arguments

name:
string required Name of the paper type.
density:
integer required GSM density of the paper type.
Must be greater than 0.

Returns

Returns the new paper type object if valid information was provided, and returns an error otherwise.

// Example Request
{
  "name": "20# Bond/Writing/Ledger",
  "density": 75
}
// Example Response
{
  "id": "d3c3e1df-5e55-4587-9d81-91ac87927424",
  "account_id": null,
  "name": "20# Bond/Writing/Ledger",
  "density": 75
}

Deleting a paper type

To delete a paper type, supply the paper type identifier. You may only delete paper types that you have created.

DELETE /paper/types/:id

Arguments

id:
paper type identifier required

Returns

Returns an object with a deleted parameter on success. If the paper type does not exist or deleting this paper type is not permitted, this call returns an an error. 

// Example Response
{
  "id": "a11c7abc-011e-462f-babb-3c6375fa6473",
  "deleted": true
}

Object Reference

The Account Object

Account Object Properties

id:
uuid
name:
string Name of the account.
display_name:
string Name displayed on the account's dashboard, communications, and collateral.
external_id:
string Custom external identifier for the account.
role:
string Role of the account.
{distributor, channel, customer}
created_at:
timestamp Date the account was created.
parent_id:
uuid Account ID of the account's parent account.
Is null when the account does not have a parent account.
status:
string Status of the account.
{active, inactive}
activated_at:
timestamp Date the account was activated.
Is null when the account has never been activated.
deactivated_at:
timestamp Date the account was deactivated.
Is null when the account has never been deactivated.

Expanded Properties

accounts_count:
integer Number of child accounts of which the account is the direct parent.
users_count:
integer Number of users belonging to the account.
mtd_pages:
integer Month-to-date pages reforested.
qtd_pages:
integer Quarter-to-date pages reforested.
ytd_pages:
integer Year-to-date pages reforested.
ltd_pages:
integer Lifetime pages reforested.
mtd_trees:
float Month-to-date trees reforested.
qtd_trees:
float Quarter-to-date trees reforested.
ytd_trees:
float Year-to-date trees reforested.
ltd_trees:
float Lifetime trees reforested. 
// Example Account Object
{
  "id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "name": "Customer ABC",
  "display_name": "Customer ABC",
  "role": "customer",
  "created_at": "2017-12-08T04:00:31Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2017-12-08T04:00:31Z",
  "deactivated_at": null
}
// Example Expanded Account Object
{
  "id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "name": "Customer ABC",
  "display_name": "Customer ABC",
  "role": "customer",
  "created_at": "2017-12-08T04:00:31Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2017-12-08T04:00:31Z",
  "deactivated_at": null,
  "accounts_count": 0,
  "users_count": 3,
  "mtd_pages": 1234,
  "qtd_pages": 12345,
  "ytd_pages": 123456,
  "ltd_pages": 1234567,
  "mtd_trees": 0.15,
  "qtd_trees": 1.48,
  "ytd_trees": 14.82,
  "ltd_trees": 148.0
}

The Certificate Object

Certificate Object Properties

id:
uuid
account_id:
uuid
date:
timestamp Date this certificate was issued.
pages:
integer Number of standard pages reforested on this certificate.
trees:
float Number of trees reforested on this certificate.
project_id:
uuid
project:
project object The project where this certificate's trees will be planted.
url:
string Permalink for this certificate.
pdf_url:
string PDF permalink for this certificate. 
// Example Certificate Object
{
  "id": "ae630937-e15b-4da5-98de-bb68eefe2a12",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "date": "2019-11-30T23:59:59Z",
  "pages": 2469134,
  "trees": 296.0,
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "project": {
    "id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
    "name": "Madagascar",
    "status": "active",
    "forest_latitude": -15.735844444444444,
    "forest_longitude": 46.35879166666667,
    "content_logo": "http://s3.amazonaws.com/projects/madagascar/logo.jpg",
    "content_masthead": "http://s3.amazonaws.com/projects/madagascar/masthead.jpg",
    "content_introduction": "Madagascar, due to its isolation...",
    "content_body_html": "<h1>Madagascar is one of the most...",
    "content_images": [
      "http://s3.amazonaws.com/projects/madagascar/1.jpg",
      "http://s3.amazonaws.com/projects/madagascar/2.jpg",
      "http://s3.amazonaws.com/projects/madagascar/3.jpg"
    ]
  },
  "url": "https://printreleaf.com/certificates/ae630937-e15b-4da5-98de-bb68eefe2a12",
  "pdf_url": "https://printreleaf.com/certificates/ae630937-e15b-4da5-98de-bb68eefe2a12.pdf"
}

The Deposit Object

Deposit Object Properties

id:
uuid
account_id:
uuid
feed_id:
uuid Feed identifier.
Is null when the deposit does not have a feed.
date:
timestamp Date of the deposit.
pages:
integer Number of pages in this deposit.
width:
float Width (m) of this deposit's paper size.
length:
float Length (m) of this deposit's paper size.
height:
float Alias for length. Can be used interchangeably.
density:
integer Density (g/m2) of this deposit's paper. 
// Example Deposit Object
{
  "id": "a86d591c-3c29-4bef-82c3-7a007fb6b19c",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "feed_id": "44e182ed-cd50-4fa1-af90-e77dd6d6a78c",
  "date": "2016-07-05T12:29:12Z",
  "pages": 20000,
  "width": 0.2127,
  "length": 0.2762,
  "density": 216
}

The Paper Type Object

Paper Type Object Properties

id:
uuid
account_id:
uuid Is null if it is a PrintReleaf default paper type.
name:
string Name of the paper type.
density:
integer Density (g/m2) of this paper type. 
// Example Paper Type Object
{
  "id": "d3c3e1df-5e55-4587-9d81-91ac87927424",
  "account_id": null,
  "name": "20# Bond/Writing/Ledger",
  "density": 75
}

The Project Object

Project Object Properties

id:
uuid
name:
string Name of the project.
status:
string Status of the project.
{active, inactive}
forest_latitude:
float Latitude of the project's forest.
forest_longitude:
float Longitude of the project's forest.
content_logo:
string URL for the project's logo image.
content_masthead:
string URL for the project's masthead image.
content_introduction:
string Introduction content for the project.
content_body_html:
string HTML body content for the project.
content_images:
array Array of URLs for images for the project. 
// Example Project Object
{
  "id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "name": "Madagascar",
  "status": "active",
  "forest_latitude": -15.735844444444444,
  "forest_longitude": 46.35879166666667,
  "content_logo": "http://s3.amazonaws.com/projects/madagascar/logo.jpg",
  "content_masthead": "http://s3.amazonaws.com/projects/madagascar/masthead.jpg",
  "content_introduction": "Madagascar, due to its isolation...",
  "content_body_html": "<h1>Madagascar is one of the most...",
  "content_images": [
    "http://s3.amazonaws.com/projects/madagascar/1.jpg",
    "http://s3.amazonaws.com/projects/madagascar/2.jpg",
    "http://s3.amazonaws.com/projects/madagascar/3.jpg"
  ]
}

The Quote Object

Quote Object Properties

id:
uuid
account_id:
uuid
project_id:
uuid
created_at:
timestamp Date the quote was created.
trees:
float Total equivalent trees for this quote.
standard_pages:
integer Total equivalent normalized standard pages for this quote.
mass:
float Total mass (g) of this quote's paper.
price:
float Total price for this quote.
transaction_id:
uuid Is null when this quote has not yet been transacted.

Expanded Properties

items:
array of quote item objects List of items constituting this quote. 
// Example Quote Object
{
  "id": "e9ad2b00-409a-49a5-a05c-93f63329d3af",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "created_at": "2015-10-22T00:37:11Z",
  "trees": 2.0,
  "standard_pages": 16666,
  "mass": 75400.058877,
  "price": 6.66,
  "transaction_id": null,
  "items": [
    {
      "quantity": 16666,
      "width": 0.2159,
      "length": 0.2794,
      "density": 75,
      "paper_type_id": null,
      "mass": 75400.058877
    }
  ]
}

The Quote Item Object

Quote Item Object Properties

quantity:
integer Paper quantity for this item (sheets/pages/etc.)
width:
float Width (m) of this item's paper size.
length:
float Length (m) of this item's paper size.
density:
integer Density (g/m2) of this item's paper.
paper_type_id:
uuid Paper type identifier.
Is null when the item does not have a paper type.
mass:
float Mass (g) of this item's paper. 
// Example Quote Item Object
{
  "quantity": 20000,
  "width": 0.2127,
  "length": 0.2762,
  "density": 216,
  "paper_type_id": "a11c7abc-011e-462f-babb-3c6375fa6473",
  "mass": 253793.177897
}

The Server Object

Server Object Properties

id:
uuid
account_id:
uuid
type:
string type of the server.
url:
string URL of the server.
username:
string Username credential of the server.
contact:
string Email PrintReleaf can contact for support with the server.
created_at:
timestamp Date the server was created. 
// Example Server Object
{
  "id": "eadabb78-b199-43cb-adbd-ab36ce5c5a10",
  "account_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "type": "fmaudit",
  "url": "https://myfmauditserver.com",
  "username": "MyFMAuditUsername",
  "contact": "bob@example.com",
  "created_at": "2017-12-08T04:00:31Z"
}

The Feed Object

Feed Object Properties

id:
uuid
account_id:
uuid
type:
string type of the feed.
server_id:
uuid Server identifier of the feed's server.
Is null when the feed does not have a server.
external_id:
string External ID credential of the feed.
collection_scope:
string Collection scope setting of the feed.
Only applies to feed types for print monitoring software that have a notion of 'managed' vs. 'unmanaged'.
Can be 'all' or 'managed_only'. Defaults to 'all'.
{all, managed_only}
created_at:
timestamp Date the feed was created.
status:
string Status of the feed.
{active, inactive}
activated_at:
timestamp Date the feed was activated.
Is null when the feed has never been activated.
deactivated_at:
timestamp Date the feed was deactivated.
Is null when the feed has never been deactivated.
health_check:
string Health check status for this feed.
{healthy, unhealthy, pending, offline}
health_check_checked_at:
timestamp Date the health check status was last checked.
Is null when the feed has never been health checked.
health_check_changed_at:
timestamp Date the health check status was last changed.
Is null when the feed has never been health checked. 
// Example Feed Object
{
  "id": "44e182ed-cd50-4fa1-af90-e77dd6d6a78c",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "type": "fmaudit",
  "server_id": "eadabb78-b199-43cb-adbd-ab36ce5c5a10",
  "external_id": "456",
  "collection_scope": "managed_only",
  "created_at": "2018-12-08T04:00:31Z",
  "status": "active",
  "activated_at": "2018-12-08T04:00:31Z",
  "deactivated_at": null,
  "health_check": "healthy",
  "health_check_checked_at": "2019-12-08T04:00:31Z",
  "health_check_changed_at": "2019-12-08T04:00:31Z"
}

The Transaction Object

Transaction Object Properties

id:
uuid
account_id:
uuid
quote_id:
uuid The quote that was used to create this transaction.
project_id:
uuid The project where this transaction's trees will be planted.
certificate_id:
uuid The certificate issued for this transaction.
date:
timestamp Date of the transaction.
pages:
integer Total number of pages reforested on this transaction.
trees:
float Total number of trees reforested on this transaction. 
// Example Transaction Object
{
  "id": "def0f271-2f9e-494c-b2af-7f9354b310ad",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "quote_id": null,
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "certificate_id": "def0f271-2f9e-494c-b2af-7f9354b310ad",
  "date": "2015-10-21T19:45:25Z",
  "pages": 16666,
  "trees": 2.0
}

The User Object

User Object Properties

id:
uuid
account_id:
uuid
name:
string Full name of the user.
email:
string Email address of the user.
locale:
string Locale setting of the user.
{en, de, es, fr, it, pt}
Defaults to 'en'.
created_at:
timestamp Date the user was created. 
// Example User Object
{
  "id": "5f25569f-ec0d-4ff3-a6ce-0456ac79b84d",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "name": "Sally Example",
  "email": "sally@example.com",
  "locale": "en",
  "created_at": "2017-12-08T04:00:31Z"
}

The Volume Period Object

Volume Period Object Properties

account_id:
uuid
date:
timestamp Date of the volume period.
pages:
integer Number of pages reforested during this period.
trees:
float Number of trees reforested during this period. 
// Example Volume Period Object
{
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "date": "2019-10-01T00:00:00Z",
  "pages": 234567,
  "trees": 56.3
}

Appendix

Changelog

2019-10-22 v1.5.1

  • project_id is now a required parameter when creating a quote.
  • Add mass property to Quotes and Quote Items.

2019-09-10 v1.5.0

  • rate and price properties have been added to Quotes.
  • msrp_rate and msrp_price properties have been removed from Quotes.

2018-09-14 v1.4.2

  • Add ability to manage an account's favorite projects

2018-09-06 v1.4.1

  • Negative deposits are now permitted

2018-06-12 v1.4.0

  • Invitations have been removed
  • The new POST /users endpoint has been added for creating users directly.

2018-05-14 v1.3.4

  • Allow activated_at property to be supplied when creating a Feed. Defaults to the first day of the current month.

2018-04-04 v1.3.3

  • Add pending and offline health checks to the Feed object; remove unknown

2018-02-26 v1.3.2

  • Add external_id property to the Account object

2018-02-21 v1.3.1

  • Add display_name property to the Account object

2017-11-30 v1.3.0   backward compatible change

  • Sources are now known as Feeds
  • All old /sources actions remain available as an alias to the new /feeds actions.
  • Likewise, the old source_id property of the Deposit object remains available as an alias to the new feed_id property.

2017-11-07 v1.2.3

  • Add ability to create a Transaction by providing only a raw pages value

2017-10-23 v1.2.2

  • Add Quotes

2017-08-10 v1.2.1

  • Add contact property to the Server object

2017-05-24 v1.2.0

  • Add start_date and end_date query paramters to Deposits and Transactions