API Base URLs
The Terra API is mainly organized around the webhook pattern. Automated messages arrive at your designated address, whenever an activity is generated.
For activities in the past, or should you wish to fetch data manually, REST endpoints are also available.
Our API accepts JSON-encoded request bodies (where a body is required) or a standard set of query parameters, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.
See Integrations for a full list of API-based integrations.
The Terra API uses both API Keys and developer IDs (through the
X-API-Key header and
dev-id header respectively) to authenticate your requests. Both of these can be viewed on the Terra Dashboard.
On the dashboard you will have been given 3 sets of API Keys and developer IDs, one for production, staging and testing. Your staging and testing developer IDs each have a limit of 10 users whereas your production developer ID has no user limit.
Each of your API Keys are linked to a single specific developer ID - if you attempt to authenticate requests for one of your other developer IDs using the wrong API Key your request will be rejected with a
403 Forbidden status code. API Requests sent without authentication where it is required will also be rejected with the same status code.
Ensure that your API Keys are kept safe! If, at any point you accidentally leak any of your API Keys, you may contact [email protected] to get it replaced as well as the old one invalidated.
All API requests should be made using HTTPS.
The API uses multiple versions to prevent breaking changes impacting applications currently using the API. This version can be changed through the Terra Dashboard. Each of your developer IDs can be set to use different API versions so that you can develop on a newer API version without breaking your current implementation.
The current available versions are
Mark I and
Mark II. It is recommended that you use
Mark II if possible as it changed most if not all of our data models to have more consistent field naming as well as provide access to the integrations built exclusively upon the newer version.
Please don't hesitate to contact us if you experience any issues or would like to know more about the API versions.