Documentation menu

Quickstart

The happy path, end to end: authenticate, find an event, add a carbon-source record, submit it for review, and read the computed result — six calls.

Real data, real quotas: There is no sandbox environment yet. Creating events counts toward your plan's event quota, and the create call returns 402 QUOTA_EXCEEDED when the quota is reached. For integration development, work inside one dedicated test event.

1. Authenticate

Exchange credentials for a token bundle. Use a dedicated service-account user provisioned for the integration — see Authentication for credential-handling guidance.

curl -X POST https://api.carbon-calculator.eventzero.io/api/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "svc-integration@your-org.com", "password": "<password>"}'

# → { "success": true, "data": { "accessToken": "…", "refreshToken": "…", "expiresIn": 3600, … } }

2. List your events

All reads and writes are scoped to your organization automatically. Lists are paginated with page/limit.

curl https://api.carbon-calculator.eventzero.io/api/v2/events?page=1&limit=25 \
  -H "Authorization: Bearer <accessToken>"

# → { "success": true, "data": { "items": [ { "_id": "665f…", "title": "…", … } ], "pagination": { … } } }

3. Create a carbon-source record

Each event has per-type sub-collections (flights, accommodation, venue, waste, …). Fields vary by type; ownership and workflow flags are server-controlled and ignored if sent.

curl -X POST https://api.carbon-calculator.eventzero.io/api/v2/events/<eventId>/flights \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "from": "SYD", "to": "SIN", "class": "economy", "passengers": 12 }'

# → 201 { "success": true, "data": { "_id": "<recordId>", "eventId": "<eventId>", "submitted": false, … } }

4. Submit it for review

Submitting hands the record to the event team's review queue. Managers then review and approve it — only approved records count toward the event's computed footprint. See Approval workflow.

curl -X POST https://api.carbon-calculator.eventzero.io/api/v2/events/<eventId>/flights/<recordId>/submit \
  -H "Authorization: Bearer <accessToken>"

# → { "success": true, "data": { "_id": "<recordId>", "submitted": true, … } }

5. Read the computed result

The result is the event's server-calculated carbon footprint built from approved records.

curl https://api.carbon-calculator.eventzero.io/api/v2/events/<eventId>/results \
  -H "Authorization: Bearer <accessToken>"

# → { "success": true, "data": { /* computed carbon result for the event */ } }
RESULT_NOT_FOUND: A 404 with code RESULT_NOT_FOUND means no result has been computed for the event yet (for example, nothing has been approved).

6. Refresh when the access token expires

Access tokens expire after expiresIn seconds. Exchange the refresh token for a new access token — the original refresh token stays valid until it expires.

curl -X POST https://api.carbon-calculator.eventzero.io/api/v2/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "<refreshToken>"}'

# → { "success": true, "data": { "accessToken": "…", "expiresIn": 3600, … } }  (no new refreshToken)

The same flow in JavaScript and Python

JavaScript (fetch)
const BASE = "https://api.carbon-calculator.eventzero.io/api/v2";

const login = await fetch(`${BASE}/auth/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: process.env.EZ_EMAIL, password: process.env.EZ_PASSWORD }),
});
const { data: tokens } = await login.json();

const results = await fetch(`${BASE}/events/${eventId}/results`, {
  headers: { Authorization: `Bearer ${tokens.accessToken}` },
});
const { data: carbon } = await results.json();
Python (requests)
import os, requests

BASE = "https://api.carbon-calculator.eventzero.io/api/v2"

tokens = requests.post(f"{BASE}/auth/login", json={
    "email": os.environ["EZ_EMAIL"],
    "password": os.environ["EZ_PASSWORD"],
}).json()["data"]

headers = {"Authorization": f"Bearer {tokens['accessToken']}"}
carbon = requests.get(f"{BASE}/events/{event_id}/results", headers=headers).json()["data"]