Introduction

Welcome to SkootEco's API 👋 You can use this API to plant trees, recover plastic bottles, and offset emissions. Make an impact for yourself, your business, or your customers and showcase your sustainability efforts on your SkootEco impact profile.

We have language bindings in cURL, JavaScript, and Python. You can view code examples for each request in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Find out more about SkootEco and what we do at https://skoot.eco.

Core concepts

Allocation

Allocation is the umberella term for planting certified trees, recovering plastic bottles from the world's oceans, and offsetting carbon emissions by funding climate projects.

Allocate trees = plant trees
Allocate plastic = recover plastic bottles
Allocate projects = offset carbon emissions

You can use our API to allocate trees, bottles, and offset with a profile.

Profile

A profile is connected to one or more email addresses and has:

a unique identifier profile_id
a human-friendly identifier handle
an impact profile which showcases your sustainability efforts https://skoot.eco/<handle>

Every certified tree, plastic bottle, and verified offset has a primary profile it is attributed to.

You will need a profile to use this API - create your profile here.

Allocate with another profile

A tree, bottle, or verified offset can also be attributed to another profile who has been involved in planting the tree, recovering the bottle, or purchasing the verified offset.

diagram showing the relation between a company planting a tree and the customer for whom they are doing the allocation

This could be a customer who's sale you are planting a tree for, or a business you are purchasing carbon offset with.

Any allocations made with another profile will appear on both users' impact profiles as follows:

example of attribution planting as it appears in the activity feed of an impact profile

To allocate with a customer or another profile, supply their details in the metadata.with field in your allocation request.

Collaborators

You can add collaborators to a profile to allow other users to manage it as if it were their own profile. Invite collaborators on the dashboard under Settings > Collaborators.

Authentication

Include your API token in request headers


# Validate your API token works
curl --location 'https://eco.skoot.io/api/key/validate' \
--header 'Authorization: Bearer key_123'


const axios = require("axios");

let config = {
  method: "get",
  maxBodyLength: Infinity,
  url: "https://eco.skoot.io/api/key/validate", // Validate your API token works
  headers: {
    Authorization: "Bearer key_123",
  },
};

axios
  .request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });


import requests

headers={
  'Authorization': 'Bearer key_123'
}

# Validate your API token works
response = requests.request("GET", "https://eco.skoot.io/api/key/validate", headers=headers)

print(response.text)

Make sure to replace key_123 with your API key.

Skoot uses API keys to allow access to the API. You can generate a new API key on the dashboard by following this guide.

SkootEco's API expects the API key to be included in all API requests in a header that looks like:

Authorization: Bearer key_123

Validate an API token

200 OK Response body


{
  "valid": "True",
  "_id": "abc123"
}

Use this endpoint to check if an API token is valid.

HTTP Request

GET https://eco.skoot.io/api/key/validate

Include your API token in the Authorization header.

Make an allocation

Allocate trees, bottles, carbon offset


curl --location --request PATCH 'https://api.skoot.eco/profile/<profile_id>/allocate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer key_123' \
--data-raw '{
    "metadata": {
      "activity": "A coffee for the planet"
      "via": "skoot_api",
      "with": "customer@email.com",
    },
    "allocations": [
      {
        "type": "trees",
        "quantity": 10,
        "unit": "Trees"
      },
      {
        "type": "plastic",
        "quantity": 10,
        "unit": "Bottles"
      },
      {
        "type": "projects",
        "quantity": 0.0001,
        "unit": "Metric Tons"
      }
    ]
}'


// Node + axios
const axios = require("axios");
let data = JSON.stringify({
  metadata: {
    with: "customer@email.com",
    via: "skoot_api",
    activity: "A coffee for the planet",
  },
  allocations: [
    {
      type: "trees",
      quantity: 10,
      unit: "Trees",
    },
    {
      type: "projects",
      quantity: 0.0001,
      unit: "Metric Tons",
    },
    {
      type: "plastic",
      quantity: 10,
      unit: "Bottles",
    },
  ],
});

let config = {
  method: "patch",
  maxBodyLength: Infinity,
  url: "https://api.skoot.eco/profile/<profile_id>/allocate",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer key_123",
  },
  data: data,
};

axios
  .request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });


import requests
import json

url = "https://api.skoot.eco/profile/<profile_id>/allocate"

payload = json.dumps({
  "metadata": {
    "with": "customer@email.com",
    "via": "skoot_api",
    "activity": "A coffee for the planet"
  },
  "allocations": [
    {
      "type": "trees",
      "quantity": 10,
      "unit": "Trees"
    },
    {
      "type": "projects",
      "quantity": 0.0001,
      "unit": "Metric Tons"
    },
    {
      "type": "plastic",
      "quantity": 10,
      "unit": "Bottles"
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer key_123'
}

response = requests.request("PATCH", url, headers=headers, data=payload)

print(response.text)

Make sure to replace key_123 and <profile_id> with your API key and profile ID.

Use this endpoint to allocate trees, bottles, and carbon offset to a profile.

HTTP Request

PATCH https://api.skoot.eco/profile/<profile_id>/allocate

URL Parameters

Parameter	Description
`profile_id`	The ID of the profile to which trees/bottles/offset are being allocated

Request Body

Attribute	Description
`metadata`	(Optional) Object Information about the allocation being performed
`metadata.activity`	(Optional) String Name of the activity associated with this allocation e.g. offsetting my taxi journey, tree planted for every newsletter sign up, recover a bottle per pint sold.
`metadata.via`	(Optional) String Platform via which the allocation is being made i.e. `skoot_api`
`metadata.with`	(Optional) String, Object Make this allocation with another profile. Can be: a `profile_id`, an email address, or an object `{"email":"email@address.com", "first_name":"Bob", "last_name":"TheBuilder"}` If no profile exists for the email address, an invite will be sent to create one. Any allocations attributed to another profile will appear on both users' impact profiles. More about allocating with other profiles.
`allocations`	Array of objects An array of the assets being allocated. Must contain at least one item.
`allocations[].type`	String The type of allocation. Can be `trees`, `plastic`, or `projects`
`allocations[].quantity`	Integer, Decimal The quantity of trees, bottles, or offset to allocate. Provide an integer for trees & plastic bottles. Offset is measured in metric tonnes of carbon to offset and accepts a decimal amount i.e. `"quantity": 1.0` allocates 1 tonne = 1000kg. Note: The API does not accept zero quantities. If you want to allocate e.g. just trees, only supply the trees item in the `allocations` array.
`allocations[].unit`	String Corresponds to the value of `allocations[].type`. Can be: `Trees` when `allocations[].type == trees` `Bottles` when `allocations[].type == plastic` `Metric Tons` when `allocations[].type == projects`
`allocations[].project_id`	(Optional) String If not provided, the default project IDs will be used: `ER-002` Reforesting mangroves in Kenya `PB-001` Preventing ocean plastic `PR-004` Green Infra Wind Project

Response Body

The above command returns a 201 Created and JSON structured like this:


{
  "id": "<profile_id>",
  "access": {
    "owner": "restaurant@pinkpig.coffee"
  },
  "details": {
    "type": "business",
    "description": "",
    "handle": "the-pink-pig",
    "display_name": "The Pink Pig",
    "urls": {
      "website": ""
    }
  },
  "api": {
    "status": "active",
    "expiry": "unlimited"
  },
  "statistics": {
    "profile": {
      "trees": {
        "title": "Trees planted",
        "value": 10,
        "unit": "Trees"
      },
      "plastic": {
        "title": "Plastic",
        "value": 20,
        "unit": "Bottles"
      },
      "carbon_projects": {
        "title": "Carbon projects",
        "value": 1.0,
        "unit": "Metric Tons"
      },
      "emissions_countered": {
        "title": "Emissions countered",
        "value": 1.0,
        "unit": "Metric Tons"
      }
    }
  }
}

Attribute	Description
`id`	String ID of the primary profile for this allocation
`access.owner`	String Email address of the user that owns this profile. This email is used to login to your dashboard to manage this profile.
`access.collaborators`	(Optional) Array of strings Array of email addresses which have access to login to this profile. Not returned if there are no collaborators on this profile. Learn more about collaborators.
`details`	Object Information about the primary profile. Can all be managed via your dashboard.
`details.type`	String Profile type. Can be `personal` or `business`.
`details.description`	String About this profile. Appears on the impact profile.
`details.handle`	String The handle for this profile. Use this to find your impact profile at `https://skoot.eco/<handle>`.
`details.display_name`	String The name publically displayed on your impact profile.
`details.urls.website`	String The website link displayed publically on your impact profile
`api`	(Optional) Object Information about the API token used in this request
`api.status`	String Access status for this API key. Can be `active`.
`api.expiry`	String Access status for this API key. Can be a date or `unlimited`.
`api.token`	(Optional) String If an API token has been created as part of this request, this is the created token.
`statistics.profile`	Object All-time total allocation counts for this profile. Also displayed on your impact profile at `https://skot.eco/<handle>`. If any of these counts are zero, that count's whole object will not be returned e.g. if zero trees, will not return `"trees": {"title": "Trees planted", "value": 0, "unit": "Trees"}` but instead just unset the `"trees"` property on `statistics.profile`
`statistics.profile.trees.title`	String `Trees planted`
`statistics.profile.trees.unit`	String `Trees`
`statistics.profile.trees.value`	Integer All-time total count of trees planted on this profile. Note: because allocation occurs asynchronously, this figure might not include any trees allocated in this request.
`statistics.profile.plastic.title`	String `Plastic planted`
`statistics.profile.plastic.unit`	String `Bottles`
`statistics.profile.plastic.value`	Integer All-time total count of plastic bottles recovered on this profile. Note: because allocation occurs asynchronously, this figure might not include any bottles allocated in this request.
`statistics.profile.carbon_projects.title`	String `carbon_projects`
`statistics.profile.carbon_projects.unit`	String `Metric Tons`
`statistics.profile.carbon_projects.value`	Decimal All-time total count of carbon offset via climate projects on this profile, measured in metric tonnes. Note: because allocation occurs asynchronously, this figure might not include any offset allocated in this request.
`statistics.profile.emissions_countered`	Legacy statistic - do not use. To be deprecated.

Profile

Get profile by ID


curl --location 'https://api.skoot.eco/profile/<profile_id>' \
--header 'Authorization: Bearer key_123'


const axios = require("axios");

let config = {
  method: "get",
  maxBodyLength: Infinity,
  url: "https://api.skoot.eco/profile/<profile_id>",
  headers: {
    Authorization: "Bearer key_123",
  },
};

axios
  .request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });


import requests

url = "https://api.skoot.eco/profile/<profile_id>"

headers = {
  'Authorization': 'Bearer key_123'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

HTTP Request

GET https://api.skoot.eco/profile/<profile_id>

URL Parameters

Parameter	Description
`profile_id`	The ID of the profile to be fetched. You must have access to this profile in order to get it - either own it or be a collaborator.

Response Body


{
  "id": "<profile_id>",
  "access": {
    "owner": "restaurant@pinkpig.coffee",
    "collaborators": ["jo@pinkpig.coffee"]
  },
  "details": {
    "type": "business",
    "description": "The Pink Pig Coffee House serves sustainable coffee and good vibes.",
    "handle": "the-pink-pig",
    "display_name": "The Pink Pig",
    "urls": {
      "website": "https://the-pink-pig.skoot.eco"
    }
  },
  "billing": {
    "invoicing": true
  },
  "statistics": {
    "profile": {
      "trees": {
        "title": "Trees planted",
        "value": 10,
        "unit": "Trees"
      },
      "plastic": {
        "title": "Plastic",
        "value": 20,
        "unit": "Bottles"
      },
      "emissions_countered": {
        "title": "Emissions countered",
        "value": 1.0,
        "unit": "Metric Tons"
      },
      "carbon_projects": {
        "title": "Carbon projects",
        "value": 1.0,
        "unit": "Metric Tons"
      }
    }
  }
}

Attribute	Description
`id`	String ID of the primary profile for this allocation
`access.owner`	String Email address of the user that owns this profile. This email is used to login to your dashboard to manage this profile.
`access.collaborators`	(Optional) Array of strings Array of email addresses which have access to login to this profile. Not returned if there are no collaborators on this profile. Learn more about collaborators.
`details`	Object Information about the primary profile. Can all be managed via your dashboard.
`details.type`	String Profile type. Can be `personal` or `business`.
`details.description`	String About this profile. Appears on the impact profile.
`details.handle`	String The handle for this profile. Use this to find your impact profile at `https://skoot.eco/<handle>`.
`details.display_name`	String The name publically displayed on your impact profile.
`details.urls.website`	String The website link displayed publically on your impact profile.
`billing`	(Optional) Object Contains any bespoke information about this profile's billing set up.
`billing.invoicing`	(Optional) Boolean This profile pays charges accummulated by invoice when `true`.
`billing.email`	(Optional) Boolean Email address used for all billing communication.
`statistics.profile`	Object All-time total allocation counts for this profile. Also displayed on your impact profile at `https://skot.eco/<handle>`. If any of these counts are zero, that count's whole object will not be returned e.g. if zero trees, will not return `"trees": {"title": "Trees planted", "value": 0, "unit": "Trees"}` but instead just unset the `"trees"` property on `statistics.profile`
`statistics.profile.trees.title`	String `Trees planted`
`statistics.profile.trees.unit`	String `Trees`
`statistics.profile.trees.value`	Integer All-time total count of trees planted on this profile. Note: because allocation occurs asynchronously, this figure might not include any trees allocated in this request.
`statistics.profile.plastic.title`	String `Plastic planted`
`statistics.profile.plastic.unit`	String `Bottles`
`statistics.profile.plastic.value`	Integer All-time total count of plastic bottles recovered on this profile. Note: because allocation occurs asynchronously, this figure might not include any bottles allocated in this request.
`statistics.profile.carbon_projects.title`	String `carbon_projects`
`statistics.profile.carbon_projects.unit`	String `Metric Tons`
`statistics.profile.carbon_projects.value`	Decimal All-time total count of carbon offset via climate projects on this profile, measured in metric tonnes. Note: because allocation occurs asynchronously, this figure might not include any offset allocated in this request.
`statistics.profile.emissions_countered`	Legacy statistic - do not use. To be deprecated.

Using this API

Errors

Response body for a 400 error


{
  "title": "400 Bad Input",
  "description": "Allocation failed"
}

Response body for an unauthorised request


{
  "title": "403 Forbidden"
}

The API returns any errors with a relevant HTTP status code and a summary of the error encountered in the response body.

Limits

There are limits on how much can be allocated via the API per request and per time period.

Allocation type	Per request	Per day	Per Week	Per Month
Trees	100	1000	10,000	50,000
Plastic Bottles	100	1000	10,000	50,000
Carbon Offset	5t	10t	100t	500t

Pricing

You will be charged monthly for any trees, bottles, or offset allocated in the previous month period.

Allocation Type	Price
Trees	£0.50 per tree
Plastic Bottles	£0.05 per bottle
Carbon Offset	£0.015 per kg

Billed monthly to the payment method associated with your API key's profile. There is no minimum charge - you will not be charged if you don't make any allocations.

Resources

No-code options

Use our API without writing a line of code! Find out more about our no-code integrations at https://developer.skoot.eco/integrations

How to generate an API token

You will need a SkootEco profile in order to create and manage your API tokens.

Follow this guide to create a profile and generate a token in order to start using the API.

Postman collection

Find our Postman collection here

This includes mocked endpoints you can hit to receive realistic data.