> For the complete documentation index, see [llms.txt](https://docs-integration.squake.earth/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-integration.squake.earth/audits/auditable-reporting.md).

# 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

```json
{
  "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 — 201 Created (Example)

```json
[
  {
    "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 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)

```json
{
  "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)

```json
{
  "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

```bash
# 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.