---
title: "List headroom imports"
method: GET
path: "/ops/contractual_entities/{entity}/headroom_imports"
tags: ["ops", "ops-contractual-entities"]
---

# List headroom imports

`GET /ops/contractual_entities/{entity}/headroom_imports`

## Request

- Base URL: `https://api.topi-staging.eu`
- URL: `https://api.topi-staging.eu/ops/contractual_entities/{entity}/headroom_imports`
- Auth: OAuth 2
  - Authorization code: `/oauth2/authorize`
  - Token URL: `/oauth2/token` scopes: `ops-pricing-category:read`

List the headroom imports of an external contractual entity, most recently uploaded first

## Path parameters

- `entity` string, required: External contractual entity code

## Query parameters

- `status` 'pending' | 'validated' | 'invalid' | 'applied': Only imports in this status
- `limit` integer: the size of the page, capped at 100
- `page` integer: the index of the page, zero-based

## Response `200`

OK response.

- HeadroomImportListResult
  - `headroom_imports` HeadroomImportSummary[], required: The page of imports, most recently uploaded first
    - `applied_at` string, date-time: When the import was applied; absent unless applied
    - `applied_by` string: Who applied the import; absent unless applied
    - `category_count` integer, required: Number of categories in a validated or applied import; 0 otherwise
    - `filename` string, required: Name of the uploaded file
    - `id` string, regexp, required: Headroom import ID
    - `status` 'pending' | 'validated' | 'invalid' | 'applied', required: Import status
    - `uploaded_at` string, date-time, required: When the import was created
    - `uploaded_by` string, required: Who created the import
    - `validation_error_count` integer, required: Number of errors of an invalid import; 0 otherwise
  - `pagination` PaginationResult, required
    - `limit` integer: the size of the page
    - `page` integer: the index of the page
    - `totalPages` integer: Total amount of pages available
    - `totalRows` integer: The total amount of rows

## Other responses

- `400`: BadRequest: The entity is internal
- `401`: Unauthorized: Unauthorized response.
- `403`: InvalidScopes: Forbidden response.
- `404`: NotFound: Unknown contractual entity

## Changes

- **2026-10-27** `ac6979514123`: 1 info
  - api operation id `pricing-category.list_headroom_imports` removed and replaced with `pricing-category#list_headroom_imports`
- **2026-10-26** `7ff7ee94b30e`: 2 info
  - api operation id `pricing-category#list_headroom_imports` removed and replaced with `pricing-category.list_headroom_imports`
  - api tag `ops-contractual-entities` added
- **2026-10-13** `8b81f586c754`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/topi/apis/topi-public-api/changes/ops/contractual_entities/:entity/headroom_imports/get.md)

---

[API](https://skmtc.dev/topi/apis/topi-public-api.md) - [All operations](https://skmtc.dev/topi/apis/topi-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/topi/apis/topi-public-api/revisions/09f585e29aa8?raw)