CarbonPass API

Programmatic access to your carbon data. Upload utility bills, retrieve scope-level emissions, and fetch your generated Carbon Reduction Plans from any language or platform.

REST APIBusiness+ plan

Get your API key

Authentication

All requests require a Bearer token in the Authorization header. API keys are prefixed with cp_live_ and act against your production data — there is no separate sandbox today.

bashcurl -H "Authorization: Bearer cp_live_your_key_here" \
  https://carbonpass.co/api/v1/company

API access is available on Business and Partner plans. Generate keys from your account settings.

Rate Limits

Rate limits are enforced per user account (every API key issued to the same user shares one bucket). When you exceed the limit, requests return 429 Too Many Requests.

Plan	Limit
Business	1,000 requests / hour
Partner	Unlimited

When the limit is exceeded, the response status is 429. Throttle headers (X-RateLimit-*) are coming soon — back off on a 429 in the meantime.

Endpoints

All endpoints use the base URL https://carbonpass.co/api/v1 and return JSON.

GET/api/v1/company

Retrieve your company profile, plan, sites, and the most recent session's emissions.

bashcurl -H "Authorization: Bearer cp_live_your_key_here" \
  https://carbonpass.co/api/v1/company

json{
  "data": {
    "id": "comp_8xK2mNpQ",
    "name": "Acme Industries Ltd",
    "sector": "Manufacturing",
    "city": "Birmingham",
    "employeeCount": 42,
    "planName": "business",
    "sites": [
      { "id": "site_3rZ1", "name": "Birmingham Warehouse", "city": "Birmingham", "employeeCount": 28 }
    ],
    "currentEmissions": {
      "reportingPeriod": "2025-26",
      "totalTco2e": 526.5,
      "scope1": 124.8,
      "scope2": 312.5,
      "scope3": 89.2
    },
    "passportUrl": "https://carbonpass.co/company/acme-industries",
    "passportActivated": true
  }
}

GET/api/v1/emissions

Retrieve scope-level emission totals across all sessions, with the contributing sessions listed for traceability. Optionally filter by site.

Parameter	Type	Required	Description
siteId	string	No	Filter to a specific site ID.

bashcurl -H "Authorization: Bearer cp_live_your_key_here" \
  "https://carbonpass.co/api/v1/emissions?siteId=site_3rZ1"

json{
  "data": {
    "reportingPeriod": "2025-26",
    "totalTco2e": 172.0,
    "scope1": { "total": 42.1, "breakdown": null },
    "scope2": { "total": 108.3, "breakdown": null },
    "scope3": { "total": 21.6, "breakdown": null },
    "perEmployee": 4.1,
    "sessions": [
      { "id": "sess_aB12", "siteId": "site_3rZ1", "siteName": "Birmingham Warehouse", "totalTco2e": 172.0, "createdAt": "2026-03-15" }
    ]
  }
}

POST/api/v1/bills

Upload a utility bill. The file is attached to your in-progress session. Calculation runs once you confirm the bill in the web app.

Parameter	Type	Required	Description
file	file	Yes	PDF, JPEG, or PNG of the utility bill (max 10 MB).
type	string	No	Bill type. Common values: electricity, gas, water, waste, fleet. The string 'fuel' is normalised to 'fleet' and 'unknown' to 'electricity'; other values are stored verbatim.
siteId	string	No	Optional Site to attach the bill to. Must belong to your company. Omit for company-wide bills.

bashcurl -X POST \
  -H "Authorization: Bearer cp_live_your_key_here" \
  -F "file=@invoice-mar-2026.pdf" \
  -F "type=electricity" \
  -F "siteId=site_3rZ1" \
  https://carbonpass.co/api/v1/bills

json{
  "data": {
    "id": "bill_9vW4kLpR",
    "status": "uploaded",
    "type": "electricity",
    "sessionId": "sess_aB12",
    "siteId": "site_3rZ1",
    "createdAt": "2026-04-06T14:30:00Z"
  }
}

GET/api/v1/crp/{id}

Fetch a CRP by ID. PDF download is currently web-app-only; a Bearer-auth PDF endpoint is coming soon.

Parameter	Type	Required	Description
id	string	Yes	The CRP ID (cuid) — get it from the web app once you have generated and published a CRP.

bashcurl -H "Authorization: Bearer cp_live_your_key_here" \
  https://carbonpass.co/api/v1/crp/crp_5tN8xBmQ

json{
  "data": {
    "id": "crp_5tN8xBmQ",
    "status": "published",
    "fyYear": "2026",
    "targetYear": "2050",
    "generatedAt": "2026-04-06T14:35:48Z",
    "sections": {
      "organisationDetails": true,
      "baselineEmissions": true,
      "currentEmissions": true,
      "reductionTargets": true,
      "reductionProjects": true,
      "environmentalMeasures": true,
      "declaration": true
    }
  }
}

Errors

All errors return a JSON body with at least an error field. Some routes also include message and status fields.

Status	Meaning	Example
400	Bad Request	Missing required field "type"
401	Unauthorized	Invalid or expired API key
403	Forbidden	Plan or scope check failed (e.g. Free plan without API access)
404	Not Found	CRP crp_xyz does not exist
429	Too Many Requests	Rate limit exceeded, retry after 45s
500	Internal Error	Unexpected server error
501	Not Implemented	Endpoint reserved for a future release

json{
  "error": "bad_request",
  "message": "Missing required field \"type\" in bill upload.",
  "status": 400
}

Webhooks

HMAC-signed webhook delivery is implemented and runs on every CRP generation in the web app and on every bill confirmation. Manage endpoints from your account settings at /account/webhooks (Business and Partner plans).

Event	Description
crp.generated	Fired when a Carbon Reduction Plan has been generated via the web app.
bill.confirmed	Fired when an uploaded bill has been parsed and confirmed by the user.
passport.activated	Fired when a CRP is published. (Event name is legacy; renaming to crp.published is on the roadmap.)

Example payload (PDF download is currently web-app-only; a Bearer-auth PDF endpoint is coming soon):

json{
  "event": "crp.generated",
  "timestamp": "2026-04-06T14:35:48Z",
  "data": {
    "id": "crp_5tN8xBmQ",
    "status": "draft"
  }
}

Verify the X-CarbonPass-Signature header by computing an HMAC-SHA256 of the raw request body with your webhook secret. Reject any request where the signature does not match.

Ready to integrate?

Start building with the CarbonPass API today. Generate your first API key and make your first request in minutes.

Get your API key Talk to our team