Auditable Reporting & Audit Mode (SQUAKE API)

SQUAKE supports auditable reporting by creating immutable audit logs for calculations performed in audit mode. You can also associate audits with a legal entity using the Auditable Entities endpoints and the audit_for field in the calculation request.

When to use audit modeCopy Anchor Link

Rule of thumb: Past/post‑validated = audit mode; Future/pre‑booking = no audit mode.

• Use audit mode for finalized events: flown flights, completed stays/trips, historical backfills, invoice reconciliation/true‑ups, post‑issuance corrections.
• Do not use audit mode for changing scenarios: shopping/quotes, draft itineraries, forecasting/scenario planning, POS value requests.

Operational notes:

• Post‑booking calculations must use audit mode.
• Pre‑booking values must not be carried into post‑booking reporting—recalculate with audit mode once finalized.
• POS/preview requests must be sent without audit mode.

AuthenticationCopy Anchor Link

All endpoints require Bearer Token authentication. Audit logging must be enabled for your account.

Create auditable entities (optional but recommended)Copy Anchor Link

Create and manage legal entities to which your audit logs can be linked via audit_for on calculation requests.

EndpointsCopy Anchor Link

• GET /v2/audits/entities — List entities
• POST /v2/audits/entities — Create a new entity
• GET /v2/audits/entities/{id} — Retrieve a specific entity

Create: request exampleCopy Anchor Link

{
  "legal_name": "Test Company Inc.",
  "email": "user@example.com",
  "vat_id": "DE123456789",
  "external_id": "external-id",
  "address": {
    "city": "Berlin",
    "line1": "Street 1",
    "line2": "Building A",
    "email": "user@example.com",
    "country": "DE",
    "state": "BE",
    "postal_code": "12345"
  }
}

Create: response exampleCopy Anchor Link

[
  {
    "id": "0194d6b4-8711-7873-899d-c8133cd742f8",
    "legal_name": "Test Company Inc.",
    "email": "test@squake.earth",
    "vat_id": "DE123456789",
    "external_id": "external-id",
    "address": { "...": "..." }
  }
]

Performing calculations in audit modeCopy Anchor Link

Use the Calculations endpoint to compute emissions and create audit logs by setting items[].audit: true.
Associate a legal entity by setting audit_for at the root of the request body.

EndpointCopy Anchor Link

• POST /v2/calculations

Request: flight example with DEFRACopy Anchor Link

{
  "expand": ["items"],
  "carbon_unit": "tonne",
  "distance_unit": "kilometer",
  "audit_for": "0194d6b4-8711-7873-899d-c8133cd742f8",
  "items": [{
    "audit": true,
    "type": "flight",
    "methodology": "DEFRA",
    "external_reference": "INV-2025-0211-A",
    "origin": "BER",
    "destination": "CDG",
    "booking_class": "economy",
    "number_of_travelers": 1,
    "aircraft_type": "7M7",
    "fare_class": "Y",
    "airline": "LH",
    "radiative_forcing_index": true,
    "sustainable_fuels": {
      "carbon_reduction_percentage_of_total": 0.25
    },
    "energy_scope": "ttw"
  }]
}

NotesCopy Anchor Link

• expand: ["items"] returns per‑item emissions along with the total.
• items[].audit must be true to create audit logs (feature must be enabled).
• audit_for links the created audit logs to an Auditable entity.
• Location fields accept IATA/ICAO, UN/LOCODE, addresses, or lat/long. If distance_in_km is provided, it overrides origin/destination distance resolution.
• RFI: radiative_forcing_index controls the altitude multiplier (true by default for flights, if supported by the methodology).
• SAF: sustainable_fuels.carbon_reduction_percentage_of_total applies a reduction to computed emissions (outside current official frameworks).
• Energy scope: ttw (default wtw if not specified).

Response (condensed)Copy Anchor Link

{
  "carbon_quantity": 0.37,
  "carbon_unit": "tonne",
  "items": [{
    "carbon_quantity": 0.37,
    "carbon_unit": "tonne",
    "type": "flight",
    "methodology": "DEFRA",
    "external_reference": "INV-2025-0211-A"
  }]
}

Retrieving audit logsCopy Anchor Link

• GET /v2/audits — list all audit logs for your account.
• GET /v2/audits/{id} — retrieve full details for a single audit log.

ExamplesCopy Anchor Link

# List
curl --request GET "https://api.squake.earth/v2/audits" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

# Get by ID
curl --request GET "https://api.squake.earth/v2/audits/{id}" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

Error handlingCopy Anchor Link

See alsoCopy Anchor Link

• Calculations endpoint (POST /v2/calculations) for building audited requests.
• Auditable Entities endpoints for managing audit_for linkage.
• Methodology‑specific integration docs (e.g., DEFRA, ICAO, TIM) for field availability and defaults.