API Technical Guide

Complete API reference for integrating Scope3Tracker into your systems

Base URL

https://scope3-tracker.vercel.app

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Get your token by signing up at /signup

Endpoints

POST /api/auth/signup

Create a new account

curl -X POST https://scope3-tracker.vercel.app/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "SecurePass123!",
    "name": "Your Name",
    "companyName": "Your Company"
  }'

POST /api/auth/login

curl -X POST https://scope3-tracker.vercel.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "SecurePass123!"
  }'

GET /api/suppliers

List all your suppliers

curl -X GET https://scope3-tracker.vercel.app/api/suppliers \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/suppliers

Add a new supplier

curl -X POST https://scope3-tracker.vercel.app/api/suppliers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Manufacturing",
    "category": "MANUFACTURING",
    "location": "Sweden"
  }'

GET /api/suppliers/:id

Get a specific supplier

curl -X GET https://scope3-tracker.vercel.app/api/suppliers/123 \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/suppliers/:id/emissions

Add emission data for a supplier

curl -X POST https://scope3-tracker.vercel.app/api/suppliers/123/emissions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "SCOPE_3",
    "amount": 2500.5,
    "unit": "tCO2e",
    "period": "2024-Q1"
  }'

POST /api/v1/emissions/bulk

🆕 Bulk emissions calculation with automatic CO2e computation

Supports up to 100 items per request. Automatically calculates emissions using versioned factors with inflation adjustment and data quality scoring.

curl -X POST https://scope3-tracker.vercel.app/api/v1/emissions/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emissions": [
      {
        "supplierId": "supplier-uuid",
        "ghgCategory": "CAT_1_PURCHASED_GOODS",
        "activityValue": 1000,
        "activityUnit": "kWh",
        "emissionFactorId": "EPA_2024_electricity_grid_mix_US",
        "isCustomFactor": false,
        "reportingPeriod": "2024-01-01T00:00:00Z",
        "verificationStatus": "ESTIMATED"
      },
      {
        "supplierId": "supplier-uuid",
        "ghgCategory": "CAT_4_UPSTREAM_TRANSPORT",
        "activityValue": 500,
        "activityUnit": "km",
        "emissionFactorId": "DEFRA_2023_truck_freight_UK",
        "isCustomFactor": false,
        "reportingPeriod": "2024-01-01T00:00:00Z",
        "verificationStatus": "ESTIMATED"
      }
    ]
  }'

# Response includes calculatedCO2e and dataQualityScore (1-3)
{
  "success": true,
  "count": 2,
  "data": [
    {
      "id": "emission-uuid",
      "supplierId": "supplier-uuid",
      "calculatedCO2e": 450.5,
      "dataQualityScore": 2,
      "ghgCategory": "CAT_1_PURCHASED_GOODS",
      ...
    }
  ]
}

✨ Features:

Automatic CO2e calculation using versioned emission factors
Inflation adjustment for spend-based factors (3% CAGR)
Unit normalization (g→kg, tonne→kg, mile→km)
Data quality scoring (1=Primary, 2=Secondary, 3=Tertiary)
Atomic transactions - all succeed or all fail
Supports all 15 GHG Protocol Scope 3 categories

Need Help?

Our team is here to help you integrate Scope3Tracker into your systems.

Get Started Now