API Docs

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)
active - Indicator of project’s active/inactive status (boolean)
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": "44116666",
    "name": "Africa OneTreePlanted",
    "active": true,
    "reforestationProjectDescription_en": "Reforestation projects in Africa",
    "reforestationProjectCountry_en": "Africa",
    "reforestationProjectWebsite_en": "https://onetreeplanted.org/collections/africa",
    "reforestationCompanyName_en": "OneTreePlanted",
    
  },
  {
    "id": "52223885",
    "name": "Belize SustainableHarvest",
    "active": true,
    "reforestationProjectDescription_en": "Reforestation project in Belize",
    "reforestationProjectCountry_en": "Belize",
    "reforestationProjectWebsite_en": "https://www.sustainableharvest.org/programs",
    "reforestationCompanyName_en": "Sustainable Harvest International",
  }
]

/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: 44116666 (Project Ids are 8 digits long). You can find a complete list of available projects listed in the Appendix.

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)
active - Indicator of project’s active/inactive status (boolean)
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/44116666

{
    "id": "44116666",
    "name": "Africa OneTreePlanted",
    "active": true,
    "description": "Africa OneTreePlanted",
    "reforestationCompanyName_fr": "OneTreePlanted",
    "reforestationProjectImageURL_en": "",
    "reforestationCompanyName_en": "OneTreePlanted",
    "reforestationProjectCountry_en": "Africa",
    "reforestationCompanyAddress_en": "145 Pine Haven Shores Rd #1000D Shelburne, Vermont, 05482, USA",
    "created": "2024-05-23T09:05:00.725Z",
    "reforestationProjectWebsite_en": "https://onetreeplanted.org/collections/africa",
    "reforestationProjectWebsite_fr": "https://onetreeplanted.org/collections/africa",
    "reforestationProjectCountry_fr": "Afrique",
    "location_en": "Africa",
    "updated": "2024-05-23T19:21:44.646Z",
    "reforestationProjectDescription_fr": "Projets de reforestation en Afrique",
    "reforestationProjectDescription_en": "Reforestation projects in Africa",
    "reforestationCompanyWebsite_fr": "https://onetreeplanted.org/",
    "reforestationCompanyWebsite_en": "https://onetreeplanted.org/",
    "reforestationCompanyAddress_fr": "145 Pine Haven Shores Rd #1000D Shelburne, Vermont, 05482, USA",
    "reforestationProjectImageURL_fr": ""
}

/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: 44116666 (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": "44116666",
  "user": "test_user_1"
}

{
  "uuid": "eef9f369-9ae0-45b8-ab07-10650f53a71e",
  "created": "2019-05-17T00:36:25.797Z",
  "treeCount": 2,
  "enterpriseId": "11111111",
  "projectId": "44116666",
  "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": "44116666",
  "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.

Note 3: Please validate that a project has an “active” status of “true”. Only “active” projects are available for donations.

Reforestation Organization	Location	Project ID	Project Details
Mount Kenya Trust	Kenya	32146688	https://mountkenyatrust.org
Community Forests International	Canada (Acadia)	66661111	https://forestsinternational.org
Conserve Natural Forests	Thailand	17222233	https://conservenaturalforests.org
OneTreePlanted	Europe	44117777	https://onetreeplanted.org/collections/europe
OneTreePlanted	India	95555557	https://onetreeplanted.org/collections/asia/products/india
OneTreePlanted	Mexico	77111001	https://onetreeplanted.org/products/mexico
OneTreePlanted	Africa	44116666	https://onetreeplanted.org/collections/africa
OneTreePlanted	United States	44112222	https://onetreeplanted.org/collections/united-states
OneTreePlanted	North America	44111111	https://onetreeplanted.org/collections/north-america
OneTreePlanted	Brazil	92222222	https://onetreeplanted.org/collections/latin-america/products/brazil-forests
OneTreePlanted	Biodiversity - Various	22775008	https://onetreeplanted.org/collections/africa/products/biodiversity
OneTreePlanted	Africa - AFR100 project	37083883	https://onetreeplanted.org/collections/africa/products/afr100
OneTreePlanted	Fire Forest Recovery - Various	83380611	https://onetreeplanted.org/products/forest-fire-recovery
OneTreePlanted	Canada	44113333	https://onetreeplanted.org/collections/canada
OneTreePlanted	Latin America	44114444	https://onetreeplanted.org/collections/latin-america
OneTreePlanted	Peru	77113003	https://onetreeplanted.org/collections/latin-america/products/peru
OneTreePlanted	Asia	44115555	https://onetreeplanted.org/collections/asia
OneTreePlanted	Where the trees are needed the most	06032322	https://onetreeplanted.org/
OneTreePlanted	Mangroves	41783460	https://onetreeplanted.org/collections/asia/products/mangroves
Planting on Demand	Indonesia	22224444	https://plantingondemand.org
Planting on Demand	Philippines	22223333	https://plantingondemand.org
Sustainable Harvest International	Belize	52223885	https://sustainableharvest.org/programs
Sustainable Harvest International	Honduras	52223774	https://sustainableharvest.org/programs
TIST	India	81818182	https://program.tist.org/india
TIST	Kenya	81818183	https://program.tist.org/kenya
To be determined	Where they are needed most	14442771	See Choosing a Reforestation Project

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

Documentation

APIs

Appendix 1

Introduction Edit

Getting Started Edit

Accessing the API Edit

Authentication Edit

Billing Edit

Sandbox Environment Edit

Choosing a Reforestation Project Edit

SDKs & Integrations Edit

Integrations

SDKs

/user/whoami Edit

/enterprise/:id Edit

Parameters

/project Edit

/project/:id Edit

Parameters

/tree Edit

Parameters

/tree/:uuid Edit

Parameters

/tree Edit

Parameters

/enterprise/:id/treeCount/:month Edit

Parameters

/enterprise/:id/treeCount Edit

Parameters

/enterprise/:id/treeCount/total Edit

Parameters

List of projects Edit