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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs-integration.squake.earth/audits/auditable-reporting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.