Introduction
Connect your own software to the trees, plantings, projects and recipients of your company on the WoodYouCare Platform.
The WoodYouCare Platform API lets your software read the trees your company contributes to, the plantings and projects behind them and the proof that comes with them, assign trees to your own customers and receive webhooks when something happens. It is a JSON REST API at https://woodyou.care/api/v2.
v2 is a design contract
The Platform is being rebuilt to this documentation: the API reference is the contract the Platform implements, written before the code. Names and shapes are settled; anything marked to be confirmed can still change before release. Existing integrations keep working on API v1 until its end date.
Who this is for
The API and webhooks are part of the Automate package of the Platform. Companies on Free, Proof or Share see their impact in the dashboard and on their public impact page; Automate adds the API, webhooks, integrations and exports on top of that.
Buying and donating trees is not part of this API. That happens with the WoodYouCare Foundation; the Platform receives every planting and allocation from the Foundation and shows the proof.
Quickstart
Create a token
An administrator of your company creates a token at Settings > API tokens in the Platform dashboard. Start with a test token: it only touches test data.
Make your first request
curl https://woodyou.care/api/v2/me \
-H "Authorization: Bearer wyc_test_..."The response tells you which company the token belongs to, which scopes it has and your rate limits.
List your allocations
curl "https://woodyou.care/api/v2/allocations?limit=10&expand[]=project" \
-H "Authorization: Bearer wyc_test_..."An allocation is a number of trees from one planting assigned to your company. It is the unit everything else hangs on: status, project, monitoring and verification.
Assign a tree to a customer
curl https://woodyou.care/api/v2/recipients \
-H "Authorization: Bearer wyc_test_..." \
-H "Idempotency-Key: 7f3c9e1a-2b4d-4c8e-9f0a-1d2e3f4a5b6c" \
-H "Content-Type: application/json" \
-d '{ "first_name": "Jane", "email": "jane@example.com", "language": "nl", "trees": 1, "external_reference": "ORDER-5012" }'The recipient gets a personal certificate, by email when you want. A test token assigns test trees and never emails.
Principles
- One token, one company. A token only ever sees the company it was created in.
- Never more than its owner. Every request is checked against the token's scopes and the live permissions of the person who created it.
- Stable contract. Fields are only added in
/v2. Breaking changes get a new version. - Counts are trees. The Platform reports absolute numbers of trees, with the statuses pledged, planted and monitored. It does not translate trees into other units.
- Times in UTC. Timestamps are ISO 8601 in UTC.
- Prefixed ids. Every id is a prefix plus 24 characters:
cmp_(company),alloc_(allocation),plt_(planting),prj_(project),ptn_(planting partner),rcp_(recipient),gift_(gift code),cert_(certificate),mon_(monitoring),ver_(verification),whe_(webhook endpoint) andevt_(event).
Objects
| Object | What it is |
|---|---|
company | Your company on the Platform, the tenant of the token, with tree totals |
allocation | Trees from one planting assigned to your company, with status pledged, planted or monitored |
planting | A batch of trees planted by a planting partner, with its proof dossier: species, polygon, photos, monitoring |
project | The site a planting belongs to, with country, ecosystem type, polygon and verification |
planting_partner | The organisation that planted, as registered by the Foundation |
monitoring | A survival measurement of a planting or project |
verification | An external verification statement of a project; what the verification stamp shows |
recipient | A person or customer you assigned trees to, with a personal certificate |
gift_code | A code a person claims at /gift to become a recipient |
certificate | A certificate for the company, a recipient or a claimed gift, with a public verification page |
webhook_endpoint, event | Where the Platform sends events, and the event log for reconciliation |