Partner API

This page provides information on how to integrate with TreeO2's adoption API for our partners.

Background

TreeO2 coordinates a program helping subsitence farmers and battling climate change. Farmers in Timor Leste that participate in our program plant trees on their farms. The location and species of each tree is recorded and the diameter of the tree is measured each year. As the tree grows, carbon is sequestered from the atmosphere into the tree. The resulting carbon credits are then sold, either directly to businesses looking to offset their emmissions or on carbon trading markets. The records of the trees are independently audited and have by the 'Gold Standard' certification body.

The 'Adopt-a-tree' program is a way for retail business and their customers help contribute to the TreeO2 program. During an online checkout flow, a customer is encouraged to 'adopt' a tree from the TreeO2 program by donating an additional fee for that tree, usually $1 Australian dollar. The customer is provided a URL to a page on the TreeO2 website showing the location of their tree and a photo and bio of the farmer on who's land the tree is growing.

Technical Overview

Participating businesses, known as 'Partners', have access to an API exposed from TreeO2. Using this API, partners can add new 'Adopters' and request that a tree is assigned to them. Other methods in the API allow partners to retrieve information about all the existing adopters and adopted trees associated with their organisation.

Importantly, the actual work presenting customers with information about the program and collecting the donation funds is done entirely on the partner website (or other systems). Donation funds should be collected as part of the normal checkout flow. The transfer of funds from the partner to TreeO2 happens manually with an invoice issued each month for all new adoptions recorded.

The TreeO2 partner API is built according to the JSON-RPC (remote procedure call) protocol.

Core info

API URL

The production base API URL is:

https://api.treeo2.org

TreeO2 also provides a demo API for learning and testing available at:

https://api.test.treeo2.org

Request format

All requests use application/json content type for all APIs. All requests must use the POST HTTP method.

The body of all requests in a JSON-RPC requests follows a very defined format:

{ "jsonrpc": "2.0", "id": "arbitraryRequestID", "method": "MethodName", "params": { "methodParameterName": "methodParameterValue" } }

The "arbitraryRequestID" is a value supplied by the partner and is returned in the response; generally this is a UUID. The "MethodName" value is the name of the method being called, see below for details of all the available methods and what they do. The object in the "params" property may have multiple properties, with the values for each property being a string, number, array or nested object.

Response format

All responses also come back as application/json and follow a regular format:

{ "jsonrpc": "2.0", "id": "arbitraryRequestID", "error": null, "result": { "resultPropetyName": "resultPropertyValue" } }

The value of the "result" property may be a string, number, array or object. Some methods may return a result of null.

Authentication

Authentication is provided with the inclusion of two headers in all requests:

• X-AppType header which should always have the value Partner
• Authorization header which should have the value Bearer yourAccessToken

Your access token will be provided directly from TreeO2 staff.

For testing purposes, you can use the access token 412ca109ecf4 on the test API.

Date/time format

Any property representing a date/time will be returned as string in ISO-8601 form, for example:

"adoptionDate": "2020-10-13T15:47:03.789+11:00"

Errors

Anything that the RPC API considers an invalid will be returned with an object "error" property of the response. Note that these errors will still come back with a 200 HTTP status code. If something really unexpected has happened, the response will be a 500 error.

{ "jsonrpc": "2.0", "id": null, "error": { "code": 1, "message": "Friendly error message, "data": null }, "result": null }

The value of the "data" property may include developer-specific information about an unexpected error.

Usage

A great way to just get started is to call the GetDashboardStats method. This simple call just returns some stats about the total number of trees, farmers and captured carbon in the TreeO2 system as a whole (nice to display on your own site).

To actually adopt a tree, there's really just one method to call, AdoptTrees. So let's assume that your customer has been through your checkout flow and has purchased a product and chosen to adopt a tree. Each customer will have a key, assigned by you, that identifies that customer, usually their customer ID or possibly their email (it's up to you, any string is fine). To adopt a new tree (or trees) for a customer, you simply need to call a single method:

• Call AdoptTrees, passing the following parameters:
  • adopter - a simple JSON object with properties for key, name and email
  • trees - the number of trees to be adopted. Must be a number between 1 and 50 (inclusive).

The TreeO2 API will send the customer an email confirming that they have adopted a tree and providing them a link to a page on the TreeO2 website showing the location and information about the farmers where their tree is growing. A URL to that page is also available in the returned adopter object in the "websiteURL" property.

curl examples

Here's a couple of examples of API requests made using curl.

GetCurrentPartner - returns the partner object identified by the supplied access token.

curl -X "POST" "https://api.test.treeo2.org/rpc" \ -H 'X-AppType: Partner' \ -H 'Authorization: Bearer 412ca109ecf4' \ -H 'Content-Type: application/json; charset=utf-8' \ -d $'{ "jsonrpc": "2.0", "id": "126cf21d-ebd3-4b66-82c5-8c7240dcd33a", "method": "GetCurrentPartner", "params": {} }'

AdoptTrees - the primary method to actually adopt trees for your customers.

curl -X "POST" "https://api.test.treeo2.org/rpc" \ -H 'X-AppType: Partner' \ -H 'Authorization: Bearer 412ca109ecf4' \ -H 'Content-Type: application/json; charset=utf-8' \ -d $'{ "jsonrpc": "2.0", "id": "4e73c3fa-5d88-4797-994e-8ec936f11a56", "method": "AdoptTrees", "params": { "adopter": { "name": "David Wallace", "key": "thepaleking@wemakeapps.net", "email": "thepaleking@wemakeapps.net" }, "trees": 2 } }'

Methods

This section lists all the methods for use in the partner API. Note that if all you want to do is adopt trees, then you will only ever need the adoptTrees method; everything else is just available for diagnosing issues or doing something more complex.

GetDashboardStats

Returns an object providing a range of key stats for the TreeO2 system as a whole.

Method parameters

None

Returns

Object with properties for each of different statistics.

{ "jsonrpc": "2.0", "id": "a66825b3-08da-46a0-803c-d3cf1c028332", "result": { "totalTreeCount": 320301, "totalFarmers": 990, "totalFarmerEarnings": 160150.5, "tonnesOfCarbonSequestered": 81372 } }

AdoptTrees

Adopts one or more trees for the supplied adopter. If an adopter exists matching the supplied key, the new trees will be added to that adopter's trees, otherwise a new adopter will be created. The full adopter record will be returned, with the newly adopted trees available in the returned model.

Method parameters

• adopter - type: Object. An object with required properties for this adopter, including:
  • name - type: String. The adopter's name.
  • key - type: String. A required key uniquely identifying this adopter.
  • email - type: String. An email address for this adopter.

Returns

Object with properties for the freshly updated adopter.

{ "jsonrpc": "2.0", "id": "259ecc79-1bd5-4e20-9348-b0ad7f0700e6", "result": { "name": "David Wallace", "email": "thepaleking@wemakeapps.net", "key": "thepaleking@wemakeapps.net", "publicWebsiteURL": "https://website.test.treeo2.org/adopt/3006564939", "trees": [ { "adoptionID": 5, "fobID": "11718", "treeTypeID": 30, "latitude": -8.6297392, "longitude": 126.6545512, "estimatedPlantedMonth": 12, "estimatedPlantedYear": 2017, "farmerAppUserID": 35, "farmerName": "Tome de Oliveira", "farmerBio": "Tome is a tree farmer in Baguia and start planting trees from 2016. He is a teacher. He grow the local food in bis garden. He want to plant the trees to prepare a better environment for his generation.", "farmerPhotoURL": "https://images.test.treeo2.org/app-users/c29bd502-ccd5-4720-967d-79661156a083", "adoptionDate": "2021-02-22T01:01:59.533+00:00" } ] } }

AdoptTree

Adopts a single new tree for the adopter identified by the supplied key. The full adopter record will be returned, with the newly adopted tree available in the returned model.

Method parameters

• adopter - type: Object. An object with required properties for this adopter, including:
  • name - type: String. The adopter's name.
  • key - type: String. A required key uniquely identifying this adopter.
  • email - type: String. An email address for this adopter.

Returns

Object with properties for the freshly updated adopter.

{ "jsonrpc": "2.0", "id": "259ecc79-1bd5-4e20-9348-b0ad7f0700e6", "result": { "name": "David Wallace", "email": "thepaleking@wemakeapps.net", "key": "thepaleking@wemakeapps.net", "publicWebsiteURL": "https://website.test.treeo2.org/adopt/3006564939", "trees": [ { "adoptionID": 18759, "fobID": "11718", "treeTypeID": 30, "latitude": -8.6297392, "longitude": 126.6545512, "estimatedPlantedMonth": 12, "estimatedPlantedYear": 2017, "farmerAppUserID": 5, "farmerName": "Tome de Oliveira", "farmerBio": "Tome is a tree farmer in Baguia and start planting trees from 2016. He is a teacher. He grow the local food in bis garden. He want to plant the trees to prepare a better environment for his generation.", "farmerPhotoURL": "https://images.test.treeo2.org/app-users/24727279-18ac-4f79-861a-2dca8240b448", "adoptionDate": "2021-02-22T01:01:59.533+00:00" } ] } }

GetCurrentPartner

Returns an object with information about the partner identified by the supplied access token. This is a good method to use as a 'hello world' attempt to get data from the API.

Method parameters

None

Returns

Object with properties describing the currently authenticated partner.

{ "jsonrpc": "2.0", "id": "a66825b3-08da-46a0-803c-d3cf1c028332", "result": { "id": 1, "name": "We Make Apps PTY LTD", "displayName": "We Make Apps", "websiteURL": "https://wemakeapps.net", "descriptionHTML": "<p>We Make Apps is an award-winning, Melbourne-based app development company. We've worked in close partnership with TreeO2 to help build the technology underpinning their groundbreaking work in mitigating climate change and empowering farmers in Timor Leste.</p>\r\n<p>We Make Apps is actually only set up as a 'test partner' in the TreeO2 system. If you're a genuine supporter of TreeO2 and have adopted a tree and you're seeing this, then it's likely something has gone a bit wrong in the machine. But, no worries, it's great that you've adopted a tree and rest assured that your contribution is helping!</p>", "contactName": "Mick Byrne", "contactEmail": "mick@wemakeapps.net", "contactPhone": "0416058108" } }

GetAdopter

Returns a single adopter for the current partner matching the supplied key. Returns null if no adopter is found.

Method parameters

• key - type: String. A key identifying the customer within the context of the partner's application. May be a customer ID or email address or other identifier.

Returns

Object with properties for the matching adopter, along with an array of trees adopted by this customer.

{ "jsonrpc": "2.0", "id": "64457096-0147-4f74-b2cc-b24560c6b197", "result": { "name": "David Wallace", "email": "thepaleking@wemakeapps.net", "key": "thepaleking@wemakeapps.net", "publicWebsiteURL": "https://website.test.treeo2.org/adopt/3006564939", "trees": [ { "adoptionID": 18759, "fobID": "11718", "treeTypeID": 30, "latitude": -8.6297392, "longitude": 126.6545512, "estimatedPlantedMonth": 12, "estimatedPlantedYear": 2017, "farmerAppUserID": 5, "farmerName": "Tome de Oliveira", "farmerBio": "Tome is a tree farmer in Baguia and start planting trees from 2016. He is a teacher. He grow the local food in bis garden. He want to plant the trees to prepare a better environment for his generation.", "farmerPhotoURL": "https://images.test.treeo2.org/app-users/24727279-18ac-4f79-861a-2dca8240b448", "adoptionDate": "2021-02-22T01:01:59.533+00:00" } ] } }

GetAdopters

Returns all of the adopters for the current partner.

Method parameters

None

Returns

Array of objects with properties for all adopters for this partner, along with an array of trees adopted for each customer.

{ "jsonrpc": "2.0", "id": "f9bfc62a-cdb4-4ec1-8bc0-274ffc9cd40a", "result": [ { "name": "David Wallace", "email": "thepaleking@wemakeapps.net", "key": "thepaleking@wemakeapps.net", "publicWebsiteURL": "https://website.test.treeo2.org/adopt/3006564939", "trees": [ { "adoptionID": 18759, "fobID": "11718", "treeTypeID": 30, "latitude": -8.6297392, "longitude": 126.6545512, "estimatedPlantedMonth": 12, "estimatedPlantedYear": 2017, "farmerAppUserID": 5, "farmerName": "Tome de Oliveira", "farmerBio": "Tome is a tree farmer in Baguia and start planting trees from 2016. He is a teacher. He grow the local food in bis garden. He want to plant the trees to prepare a better environment for his generation.", "farmerPhotoURL": "https://images.test.treeo2.org/app-users/24727279-18ac-4f79-861a-2dca8240b448", "adoptionDate": "2021-02-22T01:01:59.533+00:00" }, { "adoptionID": 18759, "fobID": "11719", "treeTypeID": 30, "latitude": -8.6285462, "longitude": 126.6531275, "estimatedPlantedMonth": 11, "estimatedPlantedYear": 2017, "farmerAppUserID": 5, "farmerName": "Tome de Oliveira", "farmerBio": "Tome is a tree farmer in Baguia and start planting trees from 2016. He is a teacher. He grow the local food in bis garden. He want to plant the trees to prepare a better environment for his generation.", "farmerPhotoURL": "https://images.test.treeo2.org/app-users/24727279-18ac-4f79-861a-2dca8240b448", "adoptionDate": "2021-02-22T01:01:59.533+00:00" } ] }, { "name": "Hilary Mantel", "email": "tommy.cromwell@wemakeapps.net", "key": "tommy.cromwell@wemakeapps.net", "publicWebsiteURL": "https://website.test.treeo2.org/adopt/541708869", "trees": [ { "adoptionID": 18750, "fobID": "11710", "treeTypeID": 30, "latitude": -8.6276565, "longitude": 126.654657, "estimatedPlantedMonth": 11, "estimatedPlantedYear": 2017, "farmerAppUserID": 5, "farmerName": "Tome de Oliveira", "farmerBio": "Tome is a tree farmer in Baguia and start planting trees from 2016. He is a teacher. He grow the local food in bis garden. He want to plant the trees to prepare a better environment for his generation.", "farmerPhotoURL": "https://images.test.treeo2.org/app-users/24727279-18ac-4f79-861a-2dca8240b448", "adoptionDate": "2021-02-22T01:01:59.533+00:00" } ] }, { "name": "Olga Tokarczuk", "email": "jacob@wemakeapps.net", "key": "jacob@wemakeapps.net", "publicWebsiteURL": "https://website.test.treeo2.org/adopt/850404657", "trees": [] } ] }

AddAdopter

Creates a new adopter record associated with the current partner (with no adopted trees). Will require the partner key is unique amongst adopters associated with this partner.

Method parameters

• adopter - type: Object. An object with required properties for this adopter, including:
  • name - type: String. The adopter's name.
  • key - type: String. A key uniquely identifying this adopter.
  • email - type: String. An email address for this adopter.

Returns

Object with properties for the newly created adopter.

{ "jsonrpc": "2.0", "id": "f208142f-4cc7-413c-bdbe-0f20c8e31766", "result": { "name": "Olga Tokarczuk", "email": "jacob@wemakeapps.net", "key": "jacob@wemakeapps.net", "publicWebsiteURL": "https://website.test.treeo2.org/adopt/850404657", "trees": [] } }

UpdateAdopter

Updates an existing adopter record. Note that the adopter record is identified by the partner key, not the ID. Only the name and email address of the adopter can be updated.

Method parameters

• adopter - type: Object. An object with required properties for this adopter, including:
  • name - type: String. The adopter's name.
  • key - type: String. A key uniquely identifying this adopter. Must match the key of an existing adopter.
  • email - type: String. An email address for this adopter.

Returns

Object with properties for the freshly updated adopter.

{ "jsonrpc": "2.0", "id": "ece37137-54d2-49e8-be3d-516c5e0a5eee", "result": { "name": "Olga Tokarczuk", "email": "jakob@wemakeapps.net", "key": "jakob@wemakeapps.net", "publicWebsiteURL": "https://website.test.treeo2.org/adopt/850404657", "trees": [] } }

DeleteAdopter

Deletes an existing adopter record identified by the supplied key. This will also delete all the adopted trees associated with this adopter.

Method parameters

• key - type: String. A key identifying the customer to be deleted.

Returns

This object does not return any data.

{ "jsonrpc": "2.0", "id": "64457096-0147-4f74-b2cc-b24560c6b197", "result": null }