RESTful API
RESTful API
The EcoMachter RESTful API gives you programmatic access to share (give, donate, send) adopted trees with customers, employees or other relations.
Version Information
This page describes version 1.0 of the EcoMatcher RESTful API; this is the latest version.
Overview
Get started
Before you get started, you’ll need to create and account and adopt some trees. Next you need to contact us to request access to the API; this will give you a unique key which is needed for using the API.
API url
All API resources are accessed from a base URL. This URL will be mentioned in the email you will receive with your API key.
Authentication
All calls to the what3words API must be authenticated by a valid API key; this needs to be specified as an HTTP request header. If an invalid API key is passed or if the API key is missing, an HTTP status of 401 Unauthorized will be returned in both the response headers and in the response status field.
A valid API key must be passed as a request header in the form x-api-key: [API-KEY].
CORS headers
All EcoMatcher API resources support Cross-Origin Resource Sharing or CORS. Each response from the EcoMatcher API will contain the Access-Control-Allow-Origin: * header, that enables CORS. This would allow JavaScript requests to be made to the API that span domain boundaries, however, since it exposes your API key in front-end JavaScript, enabling everyone that reads your code to give trees on behalf of you, you SHOULD NOT use front end JavaScript when using the API.
JSON responses
All responses to API requests are provided in the JSON format.
/dcus endpoint
Description
The /dcus endpoint is a resource that refers to all Digital Cause Units (DCUs). Each DCU represents one or more trees.
The /dcus endpoint accepts a request using the POST method to allocate and/or send trees to our contacts.
Prerequisites
- A valid API key linked to your account
- Sufficient number of adopted trees available for allocating / sending to contacts
- In case you use the API to send an email: a correctly configured email template
Request body
The request body specification is described through the following JSON Schema:
[code language=”javascript”]
here
[/code]
Some options can be specified in the request body:
- “send_email”: true/false. Default true. If false, no email will be sent by EcoMatcher, only the trees will be allocated and codes and links returned
- “store_meta”: true/false. Default false. If true, meta data that is sent in the request (see example), and which could be used in the mail merge, will be stored by EcoMatcher after usage, for possible future use. By default this data is not stored separately after sending an email (only the email message itself is logged, if send_email=true).
- “meta_data” may include any values you would like to use in your email template or other meta_data you would like to store.