Topics
Core API
Forestry API
Object Reference
Appendix

PrintReleaf API v1.6.4

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
  • A period refers to all days within a single month

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: /biomass/offsets
/biomass/offsets/:id
Account Scope: /accounts/:account_id/biomass/offsets
/accounts/:account_id/biomass/offsets/: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:

Biomass Offsets

Biomass Offsets are realtime exchanges of paper consumption for reforested trees.

When creating a biomass offset, you have the option to:

  1. Provide the number of sheets of paper consumed; or
  2. Provide the number of trees to be reforested; or
  3. Provide a quote_id to execute a quote to create a biomass offset

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

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

Using Biomass Offsets ›

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 biomass offset is then automatically created for the total consumption and the account receives a certificate of reforestation as a receipt of the biomass offset.

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

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": "2021-10-22T09:13:15Z",
  "parent_id": null,
  "external_id": null,
  "status": "active",
  "activated_at": "2021-10-22T09:13:15Z",
  "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
}

Biomass Certificates

Listing biomass certificates

Lists all biomass certificates.

GET /biomass/certificates

Returns

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

// Example Response
[
  {
    "id": "ae630937-e15b-4da5-98de-bb68eefe2a12",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "date": "2024-09-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/biomass/offset/ae630937-e15b-4da5-98de-bb68eefe2a12",
    "pdf_url": "https://printreleaf.com/certificates/biomass/offset/ae630937-e15b-4da5-98de-bb68eefe2a12"
  },
  {
    "id": "dfd1cdfc-8535-43d8-8987-9817580ebd2e",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "date": "2024-08-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": "complete",
      "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/biomass/offset/dfd1cdfc-8535-43d8-8987-9817580ebd2e",
    "pdf_url": "https://printreleaf.com/certificates/biomass/offset/dfd1cdfc-8535-43d8-8987-9817580ebd2e"
  }
]

Retrieving a biomass certificate

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

GET /biomass/certificates/:id

Arguments

id:
biomass certificate identifier required

Returns

Returns a biomass 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": "2024-09-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/biomass/offset/ae630937-e15b-4da5-98de-bb68eefe2a12",
  "pdf_url": "https://printreleaf.com/certificates/biomass/offset/ae630937-e15b-4da5-98de-bb68eefe2a12"
}

Biomass Offsets

Biomass offsets are realtime exchanges of paper consumption for reforested trees.

Learn more about Biomass Offsets ›



Listing biomass offsets

Lists all biomass offsets.

GET /biomass/offsets
GET /biomass/offsets?start_date=2024-09-22

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 biomass offset 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 biomass offset

Retrieves the details of a biomass offset. Supply a biomass offset identifier.

GET /biomass/offsets/:id

Arguments

id:
biomass offset identifier required

Returns

Returns a biomass offset 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 biomass offset

When creating a biomass offset, 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 biomass offset

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

After the biomass offset is created, you will immediately receive a biomass certificate as a receipt of the biomass offset.

POST /biomass/offsets

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 biomass offset's trees should be planted. If missing or null, PrintReleaf will choose a project at random.
date:
timestamp optional Date of the biomass offset.
quote_id:
uuid optional Quote identifier.
Conflicts with pages, trees, and project_id.

Returns

Returns the new biomass offset 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 biomass offset

To delete a biomass offset, supply the biomass offset identifier.

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

DELETE /biomass/offsets/:id

Arguments

id:
biomass offset identifier required

Returns

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

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

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": "2022-10-22T09:13:15Z",
    "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
    "external_id": null,
    "status": "active",
    "activated_at": "2022-10-22T09:13:15Z",
    "deactivated_at": null
  },
  {
    "id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
    "name": "Customer DEF",
    "display_name": "Customer DEF",
    "role": "customer",
    "created_at": "2023-10-22T09:13:15Z",
    "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
    "external_id": null,
    "status": "inactive",
    "activated_at": "2023-10-22T09:13:15Z",
    "deactivated_at": "2024-04-22T09:13:15Z"
  }
]

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": "2022-10-22T09:13:15Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2022-10-22T09:13:15Z",
  "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.
Defaults to name.
external_id:
string optional Custom unique 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": "2024-10-22T09:13:15Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2024-10-22T09:13:15Z",
  "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

id:
account identifier required
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 unique 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": "2024-10-22T09:13:15Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2024-10-22T09:13:15Z",
  "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": "2023-10-22T09:13:15Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2024-10-22T09:13:15Z",
  "deactivated_at": "2024-04-22T09:13:15Z",
  "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.

No new deposits can be made to a deactivated account, all outstanding deposits made prior to deactivating the account will be processed at the end of the period as usual.

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": "2023-10-22T09:13:15Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "inactive",
  "activated_at": "2023-10-22T09:13:15Z",
  "deactivated_at": "2024-10-22T09:13:15Z",
  "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
}

Carbon Offsets

Listing carbon offsets

Lists all carbon offsets.

GET /carbon/offsets

Returns

Returns an array of carbon offset objects, sorted reverse-chronologically.

// Example Response
[
  {
    "id": "0f66ae84-ad28-4e17-b447-9f521d73b557",
    "account_id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
    "project_id": "075f2aab-718b-4d06-8fca-9a51b14af88e",
    "project_name": "Brazil - Forestry REDD+ Project",
    "project_type": "Agriculture Forestry and Other Land Use",
    "registry_name": "VERRA",
    "date": "2024-09-30T23:59:59Z",
    "mtco2e": 106.123,
    "status": "fulfilled",
    "vintage_start_date": "2021-10-22T09:13:15Z",
    "vintage_end_date": "2023-10-22T09:13:15Z",
    "serial_numbers": [
      "65831-336365509-389564721-VPL-HTP-223-VER-NL-3-378-01032016-16112017-2",
      "17890-344360449-347318621-VCS-VCU-896-OKR-RE-1-335-01052004-31122006-6"
    ]
  },
  {
    "id": "c18b52dd-718b-44a4-8483-4c57c7d7182d",
    "account_id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
    "project_id": "a810ccde-88fe-4088-b32d-bdf00b1dc2cb",
    "project_name": "China - Wind Farm Project",
    "project_type": "Energy industries (renewable/non-renewable sources)",
    "registry_name": "VERRA",
    "date": "2024-08-31T23:59:59Z",
    "mtco2e": 190.453,
    "status": "processing",
    "vintage_start_date": null,
    "vintage_end_date": null,
    "serial_numbers": [

    ]
  }
]

Retrieving a carbon offset

Retrieves the details of a carbon offset. Supply a carbon offset identifier.

GET /carbon/offsets/:id

Arguments

id:
carbon offset identifier required

Returns

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

// Example Response
{
  "id": "0f66ae84-ad28-4e17-b447-9f521d73b557",
  "account_id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
  "project_id": "075f2aab-718b-4d06-8fca-9a51b14af88e",
  "project_name": "Brazil - Forestry REDD+ Project",
  "project_type": "Agriculture Forestry and Other Land Use",
  "registry_name": "VERRA",
  "date": "2024-09-30T23:59:59Z",
  "mtco2e": 106.123,
  "status": "fulfilled",
  "vintage_start_date": "2021-10-22T09:13:15Z",
  "vintage_end_date": "2023-10-22T09:13:15Z",
  "serial_numbers": [
    "65831-336365509-389564721-VPL-HTP-223-VER-NL-3-378-01032016-16112017-2",
    "17890-344360449-347318621-VCS-VCU-896-OKR-RE-1-335-01052004-31122006-6"
  ]
}

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 biomass offset is then automatically created for the total consumption and the account receives a set of certificates as a receipt of the biomass offset.

Learn more about Deposits ›



Listing deposits

Lists all deposits.

GET /deposits
GET /deposits?start_date=2024-09-22

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 processed and certified 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 Forestry Projects

Listing favorite projects

Lists the account's selected forestry projects.

GET /projects

Returns

Returns an array of forestry 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 project

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

POST /projects/:id

Arguments

id:
project identifier required

Returns

Returns the updated array of forestry 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": "complete",
    "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 project

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

DELETE /projects/:id

Arguments

id:
project identifier required

Returns

Returns the updated array of forestry 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

Returns

Returns an array of feed objects.

// 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": "2022-10-22T09:13:15Z",
    "status": "inactive",
    "activated_at": "2022-10-22T09:13:15Z",
    "deactivated_at": "2023-10-22T09:13:15Z",
    "health_check": "unhealthy",
    "health_check_checked_at": "2024-10-22T09:13:15Z",
    "health_check_changed_at": "2024-10-22T09:13:15Z"
  },
  {
    "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": "2023-10-22T09:13:15Z",
    "status": "active",
    "activated_at": "2023-10-22T09:13:15Z",
    "deactivated_at": null,
    "health_check": "healthy",
    "health_check_checked_at": "2024-10-22T09:13:15Z",
    "health_check_changed_at": "2024-10-22T09:13:15Z"
  }
]

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": "2023-10-22T09:13:15Z",
  "status": "active",
  "activated_at": "2023-10-22T09:13:15Z",
  "deactivated_at": null,
  "health_check": "healthy",
  "health_check_checked_at": "2024-10-22T09:13:15Z",
  "health_check_changed_at": "2024-10-22T09:13:15Z"
}

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 require a server_id parameter.
external_id:
string optional External ID credential for this feed.
Some feed types 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' devices.
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": "2022-10-22T09:13:15Z",
  "status": "active",
  "activated_at": "2024-10-22 09:13:15 +0000",
  "deactivated_at": null,
  "health_check": "unhealthy",
  "health_check_checked_at": "2024-10-22T09:13:15Z",
  "health_check_changed_at": "2024-10-22T09:13:15Z"
}

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 require a server_id parameter.
external_id:
string optional External ID credential for this feed.
Some feed types 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": "2022-10-22T09:13:15Z",
  "status": "inactive",
  "activated_at": "2022-10-22T09:13:15Z",
  "deactivated_at": "2023-10-22T09:13:15Z",
  "health_check": "unhealthy",
  "health_check_checked_at": "2024-10-22T09:13:15Z",
  "health_check_changed_at": "2024-10-22T09:13:15Z"
}

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": "2022-10-22T09:13:15Z",
  "status": "active",
  "activated_at": "2024-10-22T09:13:15Z",
  "deactivated_at": "2023-10-22T09:13:15Z",
  "health_check": "unhealthy",
  "health_check_checked_at": "2024-10-22T09:13:15Z",
  "health_check_changed_at": "2024-10-22T09:13:15Z"
}

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": "2022-10-22T09:13:15Z",
  "status": "inactive",
  "activated_at": "2022-10-22T09:13:15Z",
  "deactivated_at": "2024-10-22T09:13:15Z",
  "health_check": "unhealthy",
  "health_check_checked_at": "2024-10-22T09:13:15Z",
  "health_check_changed_at": "2024-10-22T09:13:15Z"
}

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,
    "external_id": null,
    "biomass_offset_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,
    "external_id": null,
    "biomass_offset_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,
  "external_id": null,
  "biomass_offset_id": null,
  "items": [
    {
      "quantity": 20000,
      "width": 0.2127,
      "length": 0.2762,
      "density": 216,
      "mass": 253793.177897
    },
    {
      "quantity": 400000,
      "width": 0.2127,
      "length": 0.2762,
      "density": 89,
      "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.
external_id:
string optional Optional custom identifier for this quote.
Must be unique.

Quote Items Arguments

Raw paper consumption data can be reported using one of two methods:

  • quantity, width, length, and density
  • mass
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).
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, and density.

Returns

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

// Example Request (providing paper specs or mass)
{
  "project_id": "5d3b468f-c0a3-4e7c-bed4-2dcce9d3f0f9",
  "items": [
    {
      "quantity": 16666,
      "width": 0.2159,
      "length": 0.2794,
      "density": 75
    },
    {
      "mass": 253793.177897
    }
  ]
}
// 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,
  "external_id": null,
  "biomass_offset_id": null,
  "items": [
    {
      "quantity": 16666,
      "width": 0.2159,
      "length": 0.2794,
      "density": 75,
      "mass": 75400.058877
    },
    {
      "quantity": 20000,
      "width": 0.2127,
      "length": 0.2762,
      "density": 216,
      "mass": 253793.177897
    }
  ]
}

Deleting a quote

To delete a quote, supply the quote identifier.

Deleting a quote is permitted unless the quote has been executed to create a biomass offset.

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

Returns

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

// Example Response
[
  {
    "id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
    "account_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
    "type": "printfleet",
    "url": "https://myprintfleetserver.com",
    "username": "MyPrintFleetUsername",
    "created_at": "2022-10-22T09:13:15Z"
  },
  {
    "id": "eadabb78-b199-43cb-adbd-ab36ce5c5a10",
    "account_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
    "type": "fmaudit",
    "url": "https://myfmauditserver.com",
    "username": "MyFMAuditUsername",
    "created_at": "2022-10-22T09:13:15Z"
  }
]

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",
  "created_at": "2022-10-22T09:13:15Z"
}

Creating a server

To create a new server, supply the type, url, username, and password 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.

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",
  "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",
  "created_at": "2022-10-22T09:13:15Z"
}

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 optional URL of the server.
username:
string optional Username credential of the server.
password:
string optional Password credential of the server.
Some server types do not require a password parameter.

Returns

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

// Example Request
{
  "username": "MyUpdatedPrintFleetUsername"
}
// Example Response
{
  "id": "9a6a1ced-4e71-4919-9d6d-25075834c404",
  "account_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "type": "printfleet",
  "url": "https://myprintfleetserver.com",
  "username": "MyUpdatedPrintFleetUsername",
  "created_at": "2022-10-22T09:13:15Z"
}

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
}

Users

Listing users

Lists all users.

GET /users

Returns

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

// Example Response
[
  {
    "id": "5f25569f-ec0d-4ff3-a6ce-0456ac79b84d",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "full_name": "Sally Example",
    "email": "sally@example.com",
    "locale": "en",
    "created_at": "2024-10-12T09:13:15Z"
  },
  {
    "id": "5f25569f-ec0d-4ff3-a6ce-0456ac79b84d",
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "full_name": "David Example",
    "email": "david@example.com",
    "locale": "en",
    "created_at": "2024-10-17T09:13:15Z"
  }
]

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",
  "full_name": "Sally Example",
  "email": "sally@example.com",
  "locale": "en",
  "created_at": "2024-10-12T09:13:15Z"
}

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.
full_name:
string optional Full Name of the user.
locale:
string optional Locale setting of the user.
{en, de, es, fr, id, it, ja, ko, ms, pt, th, zh-CN, zh-TW}
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",
  "full_name": "Sally Example",
  "locale": "pt"
}
// Example Response
{
  "id": "5f25569f-ec0d-4ff3-a6ce-0456ac79b84d",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "full_name": "Sally Example",
  "email": "sally@example.com",
  "locale": "pt",
  "created_at": "2024-10-12T09:13:15Z"
}

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 volume history summarized by month.

GET /volume

Arguments

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": "2024-08-01T00:00:00Z",
    "pages": 234567,
    "trees": 56.3
  },
  {
    "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
    "date": "2024-09-01T00:00:00Z",
    "pages": 2469134,
    "trees": 296.0
  }
]

Forestry API

Forestry Projects

Listing all forestry projects

Lists all forestry projects.

GET /forestry/projects

Returns

Returns an array of forestry 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": "complete",
    "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 forestry project

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

GET /forestry/projects/:id

Arguments

id:
project identifier required

Returns

Returns a forestry 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"
  ]
}

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 | null Custom unique identifier for this account.
role:
string Role of the account.
{distributor, channel, customer}
created_at:
timestamp Date the account was created.
parent_id:
uuid | null 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 | null Date the account was activated.
Is null when the account has never been activated.
deactivated_at:
timestamp | null 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": "2022-10-22T09:13:15Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2022-10-22T09:13:15Z",
  "deactivated_at": null
}
// Example Expanded Account Object
{
  "id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "name": "Customer ABC",
  "display_name": "Customer ABC",
  "role": "customer",
  "created_at": "2022-10-22T09:13:15Z",
  "parent_id": "a2c031fa-6599-4939-8bc6-8128881953c4",
  "external_id": null,
  "status": "active",
  "activated_at": "2022-10-22T09:13:15Z",
  "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 Biomass Certificate Object

Biomass 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:
forestry 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 Biomass Certificate Object
{
  "id": "ae630937-e15b-4da5-98de-bb68eefe2a12",
  "account_id": "971d10ac-a912-42c0-aa41-f55adc7b6755",
  "date": "2024-09-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/biomass/offset/ae630937-e15b-4da5-98de-bb68eefe2a12",
  "pdf_url": "https://printreleaf.com/certificates/biomass/offset/ae630937-e15b-4da5-98de-bb68eefe2a12"
}

The Biomass Offset Object

Biomass Offset Object Properties

id:
uuid
account_id:
uuid
quote_id:
uuid | null The quote that was used to create this biomass offset.
project_id:
uuid The project where this biomass offset's trees will be planted.
certificate_id:
uuid The certificate issued for this biomass offset.
date:
timestamp Date of the biomass offset.
pages:
integer Total number of pages reforested on this biomass offset.
trees:
float Total number of trees reforested on this biomass offset. 
// Example Biomass Offset 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 Carbon Offset Object

Carbon Offset Object Properties

id:
uuid
account_id:
uuid
project_id:
uuid
project_name:
string Name of the carbon project.
project_type:
string Carbon offset project type.
registry_name:
string Carbon registry name.
date:
timestamp Date of the carbon offset.
mtco2e:
float Quantity of MTCO2e offset.
status:
string Status of the offset.
{processing, fulfilled}
vintage_start_date:
timestamp | null The earliest vintage start date for carbon credits used in the offset.
Is null when the carbon offset is not yet fulfilled.
vintage_end_date:
timestamp | null The latest vintage end date for carbon credits used in the offset.
Is null when the carbon offset is not yet fulfilled.
serial_numbers:
array Registry serial numbers for the carbon credit lots used for the offset.
Returns an empty array when the carbon offset is not yet fulfilled. 
// Example Carbon Offset Object
{
  "id": "0f66ae84-ad28-4e17-b447-9f521d73b557",
  "account_id": "415a588e-c6f6-46a8-a04f-96423f7e518d",
  "project_id": "075f2aab-718b-4d06-8fca-9a51b14af88e",
  "project_name": "Brazil - Forestry REDD+ Project",
  "project_type": "Agriculture Forestry and Other Land Use",
  "registry_name": "VERRA",
  "date": "2024-09-30T23:59:59Z",
  "mtco2e": 106.123,
  "status": "fulfilled",
  "vintage_start_date": "2021-10-22T09:13:15Z",
  "vintage_end_date": "2023-10-22T09:13:15Z",
  "serial_numbers": [
    "65831-336365509-389564721-VPL-HTP-223-VER-NL-3-378-01032016-16112017-2",
    "17890-344360449-347318621-VCS-VCU-896-OKR-RE-1-335-01052004-31122006-6"
  ]
}

The Deposit Object

Deposit Object Properties

id:
uuid
account_id:
uuid
feed_id:
uuid | null 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 Forestry Project Object

Forestry Project Object Properties

id:
uuid
name:
string Name of the project.
status:
string Status of the project.
{active, complete}
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 Forestry 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.
external_id:
string | null Custom unique identifier for this quote.
biomass_offset_id:
uuid | null Is null when this quote has not yet been executed.

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,
  "external_id": null,
  "biomass_offset_id": null,
  "items": [
    {
      "quantity": 16666,
      "width": 0.2159,
      "length": 0.2794,
      "density": 75,
      "mass": 75400.058877
    },
    {
      "quantity": 20000,
      "width": 0.2127,
      "length": 0.2762,
      "density": 216,
      "mass": 253793.177897
    }
  ]
}

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.
mass:
float Mass (g) of this item's paper. 
// Example Quote Item Object
{
  "quantity": 20000,
  "width": 0.2127,
  "length": 0.2762,
  "density": 216,
  "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.
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",
  "created_at": "2022-10-22T09:13:15Z"
}

The Feed Object

Feed Object Properties

id:
uuid
account_id:
uuid
type:
string type of the feed.
server_id:
uuid | null Server identifier of the feed's server.
Is null when the feed does not have a server.
external_id:
string | null 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' devices.
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 | null Date the feed was activated.
Is null when the feed has never been activated.
deactivated_at:
timestamp | null 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 | null Date the health check status was last checked.
Is null when the feed has never been health checked.
health_check_changed_at:
timestamp | null 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": "2023-10-22T09:13:15Z",
  "status": "active",
  "activated_at": "2023-10-22T09:13:15Z",
  "deactivated_at": null,
  "health_check": "healthy",
  "health_check_checked_at": "2024-10-22T09:13:15Z",
  "health_check_changed_at": "2024-10-22T09:13:15Z"
}

The User Object

User Object Properties

id:
uuid
account_id:
uuid
full_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, id, it, ja, ko, ms, pt, th, zh-CN, zh-TW}
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",
  "full_name": "Sally Example",
  "email": "sally@example.com",
  "locale": "en",
  "created_at": "2024-10-12T09:13:15Z"
}

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": "2024-08-01T00:00:00Z",
  "pages": 234567,
  "trees": 56.3
}

Appendix

Changelog

2024-10-10 v1.6.4

  • Remove contact property from the Server object.

2023-09-01 v1.6.3

backward compatible change

  • Allow optional full_name property to be supplied when creating a User.

2022-10-12 v1.6.2

backward compatible change

  • The name property of the User object has been renamed to full_name.
  • The old name property of the User object remains available as an alias to the new full_name property.

2022-09-08 v1.6.1

breaking change

  • Old /paper/types endpoints have been deprecated.
  • Likewise, the old paper_type_id property of the Quote Item object has been deprecated.

2022-08-30 v1.6.0

backward compatible change

  • Transactions are now known as Biomass Offsets
  • All old /transactions endpoints remain available as an alias to the new /biomass/offsets endpoints.
  • Likewise, the old transaction_id property of the Quote object remains available as an alias to the new biomass_offset_id property.

backward compatible change

  • Certificates are now known as Biomass Certificates
  • All old /certificates endpoints remain available as an alias to the new /biomass/certificates endpoints.

breaking change

  • Old /sources endpoints have been deprecated.

2022-04-01 v1.5.4

  • The new GET /carbon/offsets endpoint has been added for listing carbon offsets.
  • The new GET /carbon/offsets/:id endpoint has been added for retrieving a carbon offsets.

2020-10-02 v1.5.3

  • Volume period parameter has been removed. Now it is always summarized by month.

2020-07-08 v1.5.2

  • Add external_id property to the Paper Type object

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