Auditable Reporting

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 Mode

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.

Audit logs are immutable and intended for compliance and verification.

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.

---

🔐 Authentication

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

---

🧾 Create Auditable Entities (optional but recommended)

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

Endpoints

• 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 Example

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

Create — 201 Created (Example)

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

---

🧮 Performing Calculations in Audit Mode

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.

Endpoint

• POST /v2/calculations

Request (Flight example; DEFRA)

{
  "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"
    }
  ]
}

Notes

• 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 (200 OK — condensed)

{
  "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 Logs

• GET /v2/audits — list all audit logs for your account.

• GET /v2/audits/{id} — retrieve full details for a single audit log.

Examples

# 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 Handling

Status	Meaning
200	Success
201	Created (Auditable entity)
400	Bad request
401/403	Authentication/authorization failed
404	Not found

---

📚 See Also

• 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.