RaaS logo

Introduction Edit

Welcome to the documentation for the DigitalHumani API! We refer to this service as RaaS, or “Reforestation as as Service”. It is a simple API for planting trees with trusted reforestation organizations.

This is a REST API. All requests should be made over SSL, and all response bodies, including errors, are encoded in JSON. We likewise recommend that all requests be JSON encoded and include the Content-Type: “application/json” request header.

This documentation will include some high-level information on topics such as authentication and billing followed by detailed information on available API routes.

Got any questions, or looking something that’s not specified in the docs? Feel free to shoot us a question at info@digitalhumani.com. We’re here to help!

Getting Started Edit

You can get started using the API by registering on the DigitalHumani dashboard at https://my.digitalhumani.com/register.

Once signed up, navigate to the Developer page to find your API key. You’ll need that key to authenticate with the API. From that page, you’ll also find your enterpriseId which will be useful in your API requests.

Continue reading for more info on how to access and authenticate with the API.

Accessing the API Edit

The API has two available endpoints:

Production
https://api.digitalhumani.com/

Sandbox
https://api.sandbox.digitalhumani.com/

Each endpoint offers access to different environments. More information on the Sandbox environment available below.

Authentication Edit

All requests to the API require proper authentication, and you’ll need an API key to authenticate. If you haven’t received your API key yet, review the Getting Started section for more information.

Once you’ve obtained your API key, you can authenticate your request by supplying the key in the X-Api-Key HTTP request header:

Key: X-Api-Key
Value: YOUR_API_KEY

Billing Edit

The RaaS solution is 100% free. You only pay for the trees at a cost of $1 per tree, and payment is made directly to the reforestation organization. By paying the reforestation organization directly, you can be sure that every cent is spent on planting trees.

Here’s what you can expect from the billing process:

  1. At the beginning of each month, we’ll check-in with you via a quick email to confirm the tree planting requests you’ve made in the last month.
  2. If all looks ok, we’ll then reach out to our partner reforestation organization where you requested to plant trees and have them initiate an invoice.
  3. You’ll receive an invoice from the reforestation organization and be able to remit payment directly to them.
  4. Once you pay the reforestation organization, they begin the process of planting these trees.

Note: Some reforestation organizations request a minimum number of tree planting requests before providing an invoice, normally around 20 trees. If you do not end up planting 20 trees within a month, we normally just extend the billing period until you do hit the minimum.

This is a flexible process, and we’re happy to help you through it - reach out to us with any questions you have.

Sandbox Environment Edit

After registration, you will have access to 2 separate environments: Sandbox and Production.

The Sandbox environment is used primarily for testing and getting familiar with the API. There are no costs associated with planting trees in Sandbox. Once you are ready to plant real trees, you should do so in the Production environment.

You can access the Sandbox dashboard by logging in at https://my.sandbox.digitalhumani.com. Initially, you will have the same login credentials for both Production and Sandbox.

Note that you will have a separate API key in the Sandbox and Production environments. To access your API key, navigate to the Developer page.

Choosing a Reforestation Project Edit

One of the most important first steps of planting trees is deciding where to plant them! We can help you with that process. DigitalHumani supports many great reforestation organizations around the world, so you can plant trees virtually anywhere.

A full list of projects you can support is available via the API - see the GET /project request below.

Not sure where to start? We have a few suggestions:

  • Shoot us an email. We’re happy to discuss your options in more detail.
  • We’ve created a special project that plants trees where they’re needed most. This will either defer the decision on where the trees are planted, or can be a temporary placeholder that can be updated to a different project later on. The ID for this project is 14442771.

SDKs & Integrations Edit

There are a number of integrations and SDKs available that you can use to easily integrate with the DigitalHumani API.

Integrations

Zapier | Digital Humani App (Invite-only)

Magento | Reforestation Integration

SDKs

PHP | rickkuilman/digital-humani-php-sdk

A PHP SDK and Composer package created and maintained by community member Rick Kuilman

Ruby | digitalhumani/ruby-sdk

A Ruby SDK and Gem maintained by the DH core team

Java | digitalhumani/java-sdk

A Java SDK maintained by the DH core team

Github Action | Continuous Reforestation

A Github Action for adding reforestation to your Github workflows. Created and maintained by the team at ProtonTypes, source available at protontypes/continuous-reforestation.

/enterprise/:id Edit

Get Enterprise by ID

The following method allows you to retrieve the details of your enterprise.

https://api.digitalhumani.com/enterprise/:id
Parameters
Type Params Data Type
URL_PARAM id string

id Id of the enterprise for which you want to get the details. Example of an id: 11111111 (Enterprise Ids are 8 digits long)

Status: 200

Response will be an object containing the details of an Enterprise, with the following attributes:

created Creation date of the enterprise in the RaaS database (ISO 8601 Date and Time format)
updated Date of the last modification of the enterprise information (ISO 8601 Date and Time format)
id Unique identifier of the enterprise (string)
name Name of the enterprise (string)
contact name Name of the contact in the enterprise (string)

https://api.digitalhumani.com/enterprise/11111111
{
  "created": "2018-12-12T09:07:00.725Z",
  "updated": "2019-03-30T15:03:42.095Z",
  "id": "11111111",
  "name": "Test - Cable Company ABC",
  "contact": {
    "name": "Jane Doe"
  }
}

/project Edit

Get list of all Projects

The following method retrieves all the reforestation projects available. The complete list of available projects is listed in the Appendix 1.

https://api.digitalhumani.com/project

Status: 200

Response will be an object, which is an array of all the projects. The projects have the following attributes:

created Creation date of the project in the RaaS database (ISO 8601 Date and Time format)
updated Date of the last modification of the project information (ISO 8601 Date and Time format)
id Unique identifier of the project (string)
name Short name of the project, in English (deprecated) (string)
description Short Description of the project, in English (deprecated) (string)
reforestationCompanyName_en Name of the reforestation company in English (string)
reforestationCompanyName_fr Name of the reforestation company in French (string)
reforestationCompanyAddress_en Physical address of the reforestation company in English (string)
reforestationCompanyAddress_fr Physical address of the reforestation company in French (string)
reforestationCompanyWebsite_en Website address of the reforestation company in English (string)
reforestationCompanyWebsite_fr Website address of the reforestation company in French (string)
reforestationProjectCountry_en Country of the reforestation project in English (string)
reforestationProjectCountry_fr Country of the reforestation project in French (string)
reforestationProjectDescription_en Description of the reforestation project in English (string
reforestationProjectDescription_fr Description of the reforestation project in French (string)
reforestationProjectImageURL_en Image URL of the reforestation project (in English when applicable) ( string)
reforestationProjectImageURL_fr Image URL of the reforestation project (in French when applicable) ( string)
reforestationProjectState_en State or province where the reforestation project is located in English ( string)
reforestationProjectState_fr State or province where the reforestation project is located in French ( string)
reforestationProjectWebsite_en Website address of the reforestation project in English (string)
reforestationProjectWebsite_fr Website address of the reforestation project in French (string)

https://api.digitalhumani.com/project
[
  { 
      "reforestationCompanyName_fr": "OneTreePlanted",
      "reforestationProjectImageURL_en": "https://cdn.shopify.com/1/products/California_One_Tree_Planted.png",
      "reforestationCompanyName_en": "OneTreePlanted",
      "reforestationProjectCountry_en": "United States",
      "reforestationCompanyAddress_en": "145 Pine Haven Shores Rd #1000D Shelburne, Vermont, 05482, USA",
      "created": "2018-11-17T09:06:00.725Z",
      "reforestationProjectWebsite_en": "https://onetreeplanted.org/united-states/products/california-forests",
      "name": "California OneTreePlanted",
      "reforestationProjectState_fr": "Californie",
      "reforestationProjectWebsite_fr": "https://onetreeplanted.org/united-states/products/california-forests",
      "reforestationProjectCountry_fr": "États-Unis",
      "reforestationProjectState_en": "California",
      "updated": "2019-05-19T19:19:26.180Z",
      "reforestationProjectDescription_fr": "Projet de reforestation en Californie, États-Unis",
      "reforestationProjectDescription_en": "Reforestation project in California, United States",
      "reforestationCompanyWebsite_fr": "https://onetreeplanted.org/",
      "reforestationCompanyWebsite_en": "https://onetreeplanted.org/",
      "reforestationCompanyAddress_fr": "145 Pine Haven Shores Rd #1000D Shelburne, Vermont, 05482, USA",
      "description": "California OneTreePlanted",
      "id": "91111111",
      "reforestationProjectImageURL_fr": "https://cdn.shopify.com/s/files/California_One_Tree_Planted.png"
    },
    {
      "reforestationCompanyName_fr": "WeForest",
      "reforestationProjectImageURL_en": "https://www.weforest.org/sites/IMG_20190423_132725_0.jpg",
      "reforestationCompanyName_en": "WeForest",
      "reforestationProjectCountry_en": "India",
      "reforestationCompanyAddress_en": "Ogentroostlaan 15, 3090 Overijse, Belgium",
      "created": "2018-12-12T09:05:00.725Z",
      "reforestationProjectWebsite_en": "https://www.weforest.org/project/india-khasi-hills",
      "name": "Khasi Hills in India, WeForest",
      "reforestationProjectWebsite_fr": "https://www.weforest.org/project/india-khasi-hills",
      "reforestationProjectCountry_fr": "Inde",
      "updated": "2019-05-19T19:24:10.761Z",
      "reforestationProjectDescription_fr": "Projet de reforestation aux Khasi Hills en Inde",
      "reforestationProjectDescription_en": "Reforestation project in the Khasi Hills in India",
      "reforestationCompanyWebsite_fr": "https://www.weforest.org/",
      "reforestationCompanyWebsite_en": "https://www.weforest.org/",
      "reforestationCompanyAddress_fr": "Ogentroostlaan 15, 3090 Overijse, Belgique",
      "description": "Khasi Hills in India, WeForest",
      "id": "96666666",
      "reforestationProjectImageURL_fr": "https://www.weforest.org/sites/default/IMG_20190423_132725_0.jpg"
    }
  ]

/project/:id Edit

Get Project by ID

The following method allows you to retrieve the details of a single reforestation project.

https://api.digitalhumani.com/project/:id
Parameters
Type Params Data Type
URL_PARAM id string

id Id of the reforestation project for which you want to get the details. Example of an id: 93333333 (Project Ids are 8 digits long). The complete list of available projects is listed in the Appendix 1.

Status: 200

Response will be an object that has the following attributes:

created Creation date of the project in the RaaS database (ISO 8601 Date and Time format)
updated Date of the last modification of the project information (ISO 8601 Date and Time format)
id Unique identifier of the project (string)
name Short name of the project, in English (deprecated) (string)
description Short Description of the project, in English (deprecated) (string)
reforestationCompanyName_en Name of the reforestation company in English (string)
reforestationCompanyName_fr Name of the reforestation company in French (string)
reforestationCompanyAddress_en Physical address of the reforestation company in English (string)
reforestationCompanyAddress_fr Physical address of the reforestation company in French (string)
reforestationCompanyWebsite_en Website address of the reforestation company in English (string)
reforestationCompanyWebsite_fr Website address of the reforestation company in French (string)
reforestationProjectCountry_en Country of the reforestation project in English (string)
reforestationProjectCountry_fr Country of the reforestation project in French (string)
reforestationProjectDescription_en Description of the reforestation project in English (string)
reforestationProjectDescription_fr Description of the reforestation project in French (string)
reforestationProjectImageURL_en Image URL of the reforestation project (in English when applicable) ( string)
reforestationProjectImageURL_fr Image URL of the reforestation project (in French when applicable) ( string)
reforestationProjectState_en State or province where the reforestation project is located in English ( string)
reforestationProjectState_fr State or province where the reforestation project is located in French ( string)
reforestationProjectWebsite_en Website address of the reforestation project in English (string)
reforestationProjectWebsite_fr Website address of the reforestation project in French (string)

https://api.digitalhumani.com/project/96666666
{
  "reforestationCompanyName_fr": "WeForest",
  "reforestationProjectImageURL_en": "https://www.weforest.org/sites/IMG_20190423_132725_0.jpg",
  "reforestationCompanyName_en": "WeForest",
  "reforestationProjectCountry_en": "India",
  "reforestationCompanyAddress_en": "Ogentroostlaan 15, 3090 Overijse, Belgium",
  "created": "2018-12-12T09:05:00.725Z",
  "reforestationProjectWebsite_en": "https://www.weforest.org/project/india-khasi-hills",
  "name": "Khasi Hills in India, WeForest",
  "reforestationProjectWebsite_fr": "https://www.weforest.org/project/india-khasi-hills",
  "reforestationProjectCountry_fr": "Inde",
  "updated": "2019-05-19T19:24:10.761Z",
  "reforestationProjectDescription_fr": "Projet de reforestation aux Khasi Hills en Inde",
  "reforestationProjectDescription_en": "Reforestation project in the Khasi Hills in India",
  "reforestationCompanyWebsite_fr": "https://www.weforest.org/",
  "reforestationCompanyWebsite_en": "https://www.weforest.org/",
  "reforestationCompanyAddress_fr": "Ogentroostlaan 15, 3090 Overijse, Belgique",
  "description": "Khasi Hills in India, WeForest",
  "id": "96666666",
  "reforestationProjectImageURL_fr": "https://www.weforest.org/sites/default/IMG_20190423_132725_0.jpg"
}

/tree Edit

Plant one or many trees

The following method sends the request to plant one or many trees.

https://api.digitalhumani.com/tree + Body Parameters described below
Parameters
Type Params Data Type
Body Parameter enterpriseId string
Body Parameter projectId string
Body Parameter user string
Body Parameter treeCount integer

The request is encoded in JSON and the parameters need to be passed in the body of the request.

In the header, “Content-Type” requires to have a value of “application/json”

enterpriseId Id of your enterprise. Example of an enterprise id: 11111111 (Enterprise Ids are 8 digits long)
projectId Id of the reforestation project for where you want the trees to be planted. Example of an id: 93333333 (Project Ids are 8 digits long)
user End user by whom the trees were planted. Example of an user: email@test.com
treeCount Number of trees requested to plant. Example: 1

Status: 200

Response will be an object that has the following attributes:

uuid Universally Unique Identifier generated (string)
created Creation date of the trees in the RaaS database (ISO 8601 Date and Time format)
treeCount Number of trees requested to plant (integer)
enterpriseId Identifier of the enterprise (string)
projectId Identifier of the project (string)
user End user by whom the trees were planted (string)

https://api.digitalhumani.com/tree
Body parameters
{
  "treeCount": 1,
  "enterpriseId": "1234abcd",
  "projectId": "93322249",
  "user": "test_user_1"
}
{
  "uuid": "eef9f369-9ae0-45b8-ab07-10650f53a71e",
  "created": "2019-05-17T00:36:25.797Z",
  "treeCount": 2,
  "enterpriseId": "11111111",
  "projectId": "93333333",
  "user": "email@test.com"
}

/tree/:uuid Edit

Get details of a single request to plant one or many trees

The following method allows you to retrieve the details of a single request to plant trees.

https://api.digitalhumani.com/tree/:uuid-of-tree-planted
Parameters
Type Params Data Type
URL_PARAM uuid string

uuid uuid of the trees for which you want to get the details. Example of an uuid: eef9f369-9ae0-45b8-ab07-10650f53a71e (uuids are 36 digits long)

Status: 200

Response will be an object that has the following attributes:

uuid Universally Unique Identifier generated (string)
created Creation date of the trees in the RaaS database (ISO 8601 Date and Time format)
treeCount Number of trees requested to plant (integer)
enterpriseId identifier of the enterprise (string)
projectId identifier of the project (string)
user End user by whom the trees were planted (string)

https://api.digitalhumani.com/tree/bcd35c97-d66c-412e-89ae-ecbac0f629ac
{
  "projectId": "81818182",
  "created": "2020-04-11T18:01:40.441Z",
  "uuid": "bcd35c97-d66c-412e-89ae-ecbac0f629ac",
  "user": "1",
  "treeCount": 1,
  "enterpriseId": "33333333"
}

/tree Edit

Count trees for a user

The following method allows you to retrieve the number of trees planted by a specific user

https://api.digitalhumani.com/tree?enterpriseId=:enterpriseId&user=:user
Parameters
Type Params Data Type
QUERY PARAM enterpriseId string
QUERY PARAM user string

enterpriseId Id of your enterprise. Example of an enterprise id: 11111111 (Enterprise Ids are 8 digits long)
user End user by whom the trees were planted. Example of an user: email@test.com

Status: 200

Response will be an object that has the following attributes:

enterpriseId Identifier of the enterprise
user End user by whom the trees were planted
count Number of trees planted by a specific user

https://api.digitalhumani.com/tree?enterpriseId=48a45261&user=test_user_1
{
  "enterpriseId": "48a45261",
  "user": "test_user_1",
  "count": 4
}

/enterprise/:id/treeCount/:month Edit

Count trees for an enterprise by month

The following method allows you to retrieve the number of trees planted by an enterprise for a specific month

https://api.digitalhumani.com/enterprise/:id/treeCount/YYYY-MM
Parameters
Type Params Data Type
URL_PARAM id string
URL_PARAM month string

id Id of your enterprise. Example of an enterprise id: 11111111 (Enterprise Ids are 8 digits long)
month Month for which you want to count the number of trees planted. Example of a month: 2020-02

Status: 200

Response will be an object that has the following attributes:

count Number of trees planted by the enterprise for a specific month

https://api.digitalhumani.com/enterprise/11111111/treeCount/2020-02
{
  "count": 17
}

/enterprise/:id/treeCount Edit

Count trees for an enterprise for any range of date

The following method allows you to retrieve the number of trees planted by an enterprise for any range of date.

https://api.digitalhumani.com/enterprise/:id/treeCount?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
Parameters
Type Params Data Type
URL_PARAM id string
QUERY PARAM startDate date (YYYY-MM-DD)
QUERY PARAM endDate date (YYYY-MM-DD)

id Id of your enterprise. Example of an enterprise id: 11111111 (Enterprise Ids are 8 digits long)
startDate Start Date of the range to specify (start-date will be included in the results). Date format is as follow: (YYYY-MM-DD)
endDate End Date of the range to specify (end-date will be included in the results). Date format is as follow: (YYYY-MM-DD)

Status: 200

Response will be an object that has the following attributes:

count Number of trees planted by the enterprise for the specified range

https://api.digitalhumani.com/enterprise/11111111/treeCount?startDate=2010-03-01&endDate=2030-01-01
{
  "count": 57
}

List of projects Edit

Here is the complete list of available projects from our 6 reforestation partners. They are all available in all environments.

Note 1: For an up-to-date list, please use the “/Project GET” method to retrieve the current list.

Note 2: Because of an unusual high demands for trees in the last few months, availability of certain projects will have to be confirmed.

Reforestation Organization Location Project ID Link to the details of the project
ChaseAfrica Kenya 32146688 chaseafrica.org.uk
Community Forests International Canada (Acadia) 66661111 forestsinternational.org/restoration/acadianforest
Conserve Natural Forests Thailand 17222233 conservenaturalforests.org/reforestation
OneTreePlanted Australia 93322350 onetreeplanted.org/collections/asia/products/australia
OneTreePlanted Brazil 92222222 onetreeplanted.org/collections/latin-america/products/brazil-forests
OneTreePlanted Canada (British Columbia) 61616161 onetreeplanted.org/collections/canada/products/british-columbia-forests
OneTreePlanted Canada (Ontario) 82828283 onetreeplanted.org/collections/canada/products/ontario
OneTreePlanted Canada (Québec) 82828282 onetreeplanted.org/collections/canada/products/quebec
OneTreePlanted Canada (New-Brunswick) 41721322 onetreeplanted.org/collections/canada/products/new-brunswick
OneTreePlanted Colombia 77112002 onetreeplanted.org/collections/latin-america/products/colombia
OneTreePlanted Côte D’Ivoire 77222222 onetreeplanted.org/collections/africa/products/cote-d-ivoire
OneTreePlanted Denmark 77119009 onetreeplanted.org/collections/europe/products/denmark
OneTreePlanted Ethiopia 93333333 onetreeplanted.org/collections/africa/products/ethiopia
OneTreePlanted Ghana 93333366 onetreeplanted.org/collections/africa/products/ghana
OneTreePlanted Guatemala ca9692a1 onetreeplanted.org/collections/latin-america/products/guatemala-forests
OneTreePlanted Haiti ca9692a0 onetreeplanted.org/collections/latin-america/products/haiti
OneTreePlanted Honduras 97133435 onetreeplanted.org/collections/latin-america/products/honduras
OneTreePlanted Iceland 77115005 onetreeplanted.org/collections/europe/products/iceland
OneTreePlanted Indonesia 93322249 onetreeplanted.org/collections/asia/products/indonesia
OneTreePlanted India 95555557 onetreeplanted.org/collections/asia/products/india
OneTreePlanted Kenya 94444444 onetreeplanted.org/collections/africa/products/kenya
OneTreePlanted Malawi 77223333 onetreeplanted.org/collections/africa/products/malawi
OneTreePlanted Mexico 77111001 onetreeplanted.org/products/mexico
OneTreePlanted New Zealand 77111010 onetreeplanted.org/collections/the-pacific/products/new-zealand
OneTreePlanted Peru 77113003 onetreeplanted.org/collections/latin-america/products/peru
OneTreePlanted Philippines 93322255 onetreeplanted.org/collections/asia/products/philippine
OneTreePlanted Romania 77116006 onetreeplanted.org/collections/europe/products/romania
OneTreePlanted Rwanda 93333377 onetreeplanted.org/collections/africa/products/rwanda
OneTreePlanted Spain 77118008 onetreeplanted.org/collections/europe/products/spain
OneTreePlanted Tanzania 77114004 onetreeplanted.org/collections/africa/products/tanzania
OneTreePlanted Uganda 93333777 onetreeplanted.org/collections/africa/products/uganda
OneTreePlanted USA (Appalachia) 77224444 onetreeplanted.org/collections/united-states/products/appalachia
OneTreePlanted USA (California) 91111111 onetreeplanted.org/collections/united-states/products/california-forests
OneTreePlanted USA (Florida) 81818181 onetreeplanted.org/collections/united-states/products/florida-forests
OneTreePlanted USA (Oregon) 91919191 onetreeplanted.org/collections/united-states/products/oregon-trees
OneTreePlanted Vietnam 95555555 onetreeplanted.org/collections/asia/products/vietnam
OneTreePlanted Where the trees are needed the most 06032322 onetreeplanted.org
Planting on Demand Indonesia 22224444 plantingondemand.org
Planting on Demand Philippines 22223333 plantingondemand.org
Sustainable Harvest International Belize 52223885 www.sustainableharvest.org/programs
Sustainable Harvest International Honduras 52223774 www.sustainableharvest.org/programs
TIST India 81818182 program.tist.org/india
TIST Kenya 81818183 program.tist.org/kenya
To be determined Where they are needed most 14442771  

Back to the main page of the RaaS (Reforestation as a Service) main page at DigitalHumani.com