ErgOpsDocs

Send your first API calculation

ErgOps Embedded is the integration surface for calculating traceable emissions for your customers. It uses the same governed factors, methodology lineage and customer accounts as the ErgOps workspace.

  1. Confirm that ErgOps Embedded access is enabled for your organization.
  2. Create or identify a Customer Account with an external reference.
  3. In ErgOps Embedded → Developers, create a Test API key with emissions:calculate, emissions:read and customers:read.
  4. Store the one-time key in your secret manager.
  5. Submit the calculation below, then read it with GET /calculations/{id}.
  6. Configure a Test webhook if event delivery is needed.
  7. Move to a separately created Live key after validating the integration.
export ERGOPS_BASE_URL="https://api.ergops.com/v1"
export ERGOPS_API_KEY="ergops_test_..."

curl "$ERGOPS_BASE_URL/emissions/logistics" \
  -H "Authorization: Bearer $ERGOPS_API_KEY" \
  -H "Idempotency-Key: shipment-93421" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_reference":"CUSTOMER-001",
    "external_reference":"SHIPMENT-93421",
    "mode":"ROAD",
    "origin":{"code":"GB-BHX","country":"GB"},
    "destination":{"code":"GB-MAN","country":"GB"},
    "cargo":{"value":10,"unit":"tonne"},
    "distance":{"value":550,"unit":"km"},
    "activity_date":"2026-09-27",
    "factor_reference":"YOUR_GOVERNED_FACTOR_KEY"
  }'

The API never accepts a raw numeric emission factor. factor_reference must resolve to an already governed active factor visible to the organization.

Read the result#

A successful response includes a public calculation ID, customer reference, tonne-kilometre activity, kgCO2e result, methodology boundary and safe factor lineage. Use GET /calculations/{id} with the same environment credential to retrieve it later.

Retry safely#

If the client times out, resend the identical payload with the same Idempotency-Key. ErgOps returns the same logical result and does not create another billable calculation.