Skip to main content

Getting started

This walks through one complete round trip: a synchronous call to confirm your key works, then a bulk call through the submit-and-poll loop.

1. Create an API key​

Create a key at API key management in the BeCause app, signed in as the profile you want the integration to act as. That choice matters — see Authentication.

2. Confirm the key works​

unit-types is a synchronous reference-data endpoint with no parameters, which makes it the cheapest way to prove your credentials and connectivity.

curl https://api.because.eco/api/v1/unit-types \
  -H "Authorization: YOUR_API_KEY"

A JSON array comes back immediately. If you get an authentication failure here, no other endpoint will work either — fix this first.

3. Map your properties onto BeCause companies​

Before you can read or write data about a property, BeCause needs to know which of its companies corresponds to your record. You send your own identifiers along with whatever public identifying information you hold, and BeCause matches them.

curl -X POST https://api.because.eco/api/v1/bulk/company-mappings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @mappings.json

The response carries a correlation id. Keep it.

4. Poll until it finishes​

curl https://api.because.eco/api/v2/bulk/tasks/{correlationId} \
  -H "Authorization: YOUR_API_KEY"

Repeat on an interval until the request reports a terminal state, then read the per-item results to see which of your records matched. See Asynchronous processing for what the states mean and what ordering guarantees you get.

5. Go on from there​

With your properties mapped, the rest of the API becomes useful:

  • Push data in — certifications and commitments, performance answers, calculator inputs and custom property values, all under Imports.
  • Pull data out — search companies, standards, framework answers and calculators under Searches, then download the result file.
  • Look things up — frameworks, groups, unit types and custom identifiers under Reference Data, all synchronous.

To watch the whole loop run as one job, the example workflows walk it end to end, first call to downloaded result.

When something does not work​

Check, in this order: the key is being sent in the Authorization header; the key belongs to the profile that owns the companies you are addressing; and the per-item results rather than the overall request status. Most surprises are one of those three.

If none of them explains it, send us the correlation id at support@because.eco — it is the fastest way for us to find your request.