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:
- 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.
- 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.
- You’ll receive an invoice from the reforestation organization and be able to remit payment directly to them.
- 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
Shopify via Mesa | Digital Humani Mesa Integration
A Mesa integration that allows you to integrate Digital Humani into your Shopify store. Note that we’ll be launching our own Shopify application in the near-future.
Zapier | Digital Humani App
WooCommerce | Digital Humani for WooCommerce
A WooCommerce integration created and maintained by our partners at WooNinja (thanks!)
Magento | Reforestation Integration
Microsoft Power Platform Connector | Digital Humani Connector
Cyclr | Digital Humani Connector
SDKs
JavaScript | impe93/digital-humani-js-sdk
A JavaScript SDK and npm package created and maintained by community member Lorenzo Imperatrice
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
Go | AidanFogarty/go-digital-humani
A Go SDK created and maintained by community member Aidan Fogarty
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.
/user/whoami Edit
Get Authenticated User
The following method allows you to retrieve the details of your authenticated user.
https://api.digitalhumani.com/user/whoami
Status: 200
Response will be an object containing the details of your authenicated user, including internal user ID, user name and email, and ID of user’s associated enterprise (enterpriseId).
https://api.digitalhumani.com/user/whoami
{
"id": "abcd1234",
"email": "test@test.com",
"firstName": "Test",
"lastName": "User",
"enterpriseId": "1111111"
}
/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 array of objects representing each project. The projects have the following attributes:
- id - Unique identifier of the project (string)
- name - Short name of the project (string)
- reforestationProjectDescription_en - Description of the reforestation project (string)
- reforestationProjectState_en - State or province where the reforestation project is located (string)
- reforestationProjectCountry_en - Country of the reforestation project (string)
- reforestationProjectWebsite_en - Website address of the reforestation project (string)
- reforestationCompanyName_en - Name of the reforestation organization managing the project (string)
If you are looking for more information on each project, please see GET /project/:id. Note that _en indicates the English language version of the attributes
https://api.digitalhumani.com/project
[
{
"id": "91111111",
"name": "California OneTreePlanted",
"reforestationProjectDescription_en": "Reforestation project in California, United States",
"reforestationProjectState_en": "California",
"reforestationProjectCountry_en": "United States",
"reforestationProjectWebsite_en": "https://onetreeplanted.org/united-states/products/california-forests",
"reforestationCompanyName_en": "OneTreePlanted",
},
{
"id": "96666666",
"name": "Khasi Hills in India, WeForest",
"reforestationProjectDescription_en": "Reforestation project in the Khasi Hills in India",
"reforestationProjectState_en": "Khasi Hills",
"reforestationProjectCountry_en": "India",
"reforestationProjectWebsite_en": "https://www.weforest.org/project/india-khasi-hills",
"reforestationCompanyName_en": "WeForest",
}
]
/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
}
/enterprise/:id/treeCount/total Edit
Count the total number of trees for an enterprise
The following method allows you to retrieve the total number of trees planted by an enterprise.
https://api.digitalhumani.com/enterprise/:id/treeCount/total
Parameters
| Type | Params | Data Type |
|---|---|---|
| URL_PARAM | id | string |
id Id of your enterprise. Example of an enterprise id: 11111111 (Enterprise Ids are 8 digits long)
Status: 200
Response will be an object that has the following attributes:
count Total number of trees planted by the enterprise
https://api.digitalhumani.com/enterprise/11111111/treeCount/total
{
"count": 126
}
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