CarbonPass API

Programmatic access to your carbon data. Generate CRPs, upload utility bills, and retrieve scope-level emissions 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_ for production and cp_test_ for sandbox environments.

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 API key. When you exceed the limit, requests return 429 Too Many Requests.

Plan	Limit
Business	1,000 requests / hour
Partner	Unlimited

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can throttle proactively.

Endpoints

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

GET/api/v1/company

Retrieve your company profile including total emissions, site count, and current financial year.

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

json{
  "id": "comp_8xK2mNpQ",
  "name": "Acme Industries Ltd",
  "industry": "Manufacturing",
  "financialYear": "2025-2026",
  "sites": 3,
  "totalEmissions": {
    "scope1": 124.8,
    "scope2": 312.5,
    "scope3": 89.2,
    "total": 526.5,
    "unit": "tCO2e"
  },
  "passportStatus": "active",
  "crpCount": 4
}

GET/api/v1/emissions

Retrieve a detailed scope breakdown of emissions. Optionally filter by financial year or site.

Parameter	Type	Required	Description
fy	string	No	Financial year, e.g. 2025-2026. Defaults to current.
siteId	string	No	Filter to a specific site ID.

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

json{
  "financialYear": "2025-2026",
  "siteId": "site_3rZ1",
  "siteName": "Birmingham Warehouse",
  "emissions": {
    "scope1": { "total": 42.1, "sources": { "naturalGas": 38.4, "fleet": 3.7 } },
    "scope2": { "total": 108.3, "sources": { "electricity": 108.3 } },
    "scope3": { "total": 21.6, "sources": { "water": 4.2, "waste": 17.4 } }
  },
  "unit": "tCO2e",
  "lastUpdated": "2026-03-15T10:22:00Z"
}

POST/api/v1/bills

Upload a utility bill for processing. The file is parsed automatically and emissions are calculated once confirmed.

Parameter	Type	Required	Description
file	file	Yes	PDF or image of the utility bill (max 10 MB).
type	string	Yes	Bill type: electricity, gas, water, or waste.
siteId	string	Yes	The site this bill belongs to.

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{
  "id": "bill_9vW4kLpR",
  "status": "processing",
  "type": "electricity",
  "siteId": "site_3rZ1",
  "fileName": "invoice-mar-2026.pdf",
  "uploadedAt": "2026-04-06T14:30:00Z",
  "estimatedCompletion": "2026-04-06T14:32:00Z"
}

POST/api/v1/crp/generate

Trigger generation of a Carbon Reduction Plan (CRP) for the current financial year. The CRP is published automatically once complete.

bashcurl -X POST \
  -H "Authorization: Bearer cp_live_your_key_here" \
  -H "Content-Type: application/json" \
  https://carbonpass.co/api/v1/crp/generate

json{
  "id": "crp_5tN8xBmQ",
  "status": "generating",
  "financialYear": "2025-2026",
  "createdAt": "2026-04-06T14:35:00Z",
  "estimatedCompletion": "2026-04-06T14:36:00Z"
}

GET/api/v1/crp/{id}

Check the status of a CRP. Once complete, the response includes a download URL for the PDF.

Parameter	Type	Required	Description
id	string	Yes	The CRP ID returned from the generate endpoint.

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

json{
  "id": "crp_5tN8xBmQ",
  "status": "complete",
  "financialYear": "2025-2026",
  "totalEmissions": 526.5,
  "reductionTarget": 12,
  "createdAt": "2026-04-06T14:35:00Z",
  "completedAt": "2026-04-06T14:35:48Z",
  "downloadUrl": "https://carbonpass.co/api/v1/crp/crp_5tN8xBmQ/download",
  "publicUrl": "https://carbonpass.co/crp/crp_5tN8xBmQ"
}

Errors

All errors return a JSON body with error and message fields.

Status	Meaning	Example
400	Bad Request	Missing required field "type"
401	Unauthorized	Invalid or expired API key
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

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

Webhooks

Configure webhook endpoints in your account settings to receive real-time notifications when key events occur. All payloads are signed with HMAC-SHA256 using your webhook secret.

Event	Description
crp.generated	Fired when a Carbon Reduction Plan has been generated and is ready for download.
passport.activated	Fired when a Carbon Passport is activated or renewed for your company.
bill.confirmed	Fired when an uploaded bill has been parsed and emissions have been calculated.

Example payload:

json{
  "event": "crp.generated",
  "timestamp": "2026-04-06T14:35:48Z",
  "data": {
    "id": "crp_5tN8xBmQ",
    "financialYear": "2025-2026",
    "totalEmissions": 526.5,
    "downloadUrl": "https://carbonpass.co/api/v1/crp/crp_5tN8xBmQ/download"
  }
}

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