---
title: "Apply a headroom import"
method: POST
path: "/ops/contractual_entities/{entity}/headroom_imports/{id}/apply"
tags: ["ops", "ops-contractual-entities"]
---

# Apply a headroom import

`POST /ops/contractual_entities/{entity}/headroom_imports/{id}/apply`

## Request

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

Apply a validated headroom import: replace the entity's rows for every category in it, in one transaction. Applying an applied import returns it unchanged.

## Path parameters

- `entity` string, required: External contractual entity code
- `id` string, regexp, required: Headroom import ID

## Response `200`

OK response.

- HeadroomImport
  - `applied_at` string, date-time: When the import was applied; absent unless applied
  - `applied_by` string: Who applied the import; absent unless applied
  - `contractual_entity` string, required: External contractual entity code
  - `filename` string, required: Name of the uploaded file
  - `id` string, regexp, required: Headroom import ID
  - `preview` HeadroomImportCategoryPreview[], required: One entry per category in the file, ordered by identifier, when validated or applied; empty otherwise. A validated import is compared with the entity's current rows; an applied one lists the values it wrote
    - `current_default_tenure` integer: Default tenure today; absent when there is none or the import is applied
    - `id` string, regexp, required: Pricing category ID
    - `identifier` string, required: Pricing category identifier
    - `new_default_tenure` integer: Default tenure the import sets; absent when it disables every tenure
    - `newly_covered` boolean: Whether the entity has no rows for the category yet; absent once the import is applied
    - `tenures` HeadroomImportTenurePreview[], required: One entry per supported tenure
      - `becomes_disabled` boolean, required: Whether the tenure is enabled today and the import disables it
      - `current` ContractualEntityHeadroom
        - `expected_residual_value_ratio` number, double: Expected residual value ratio; absent when unspecified, which only a disabled tenure may be
        - `headroom_ratio` number, double: Headroom ratio; absent when the tenure is disabled
        - `is_default` boolean, required: Whether this is the default tenure of the category
        - `tenure` integer, required: Tenure in months
      - `new` ContractualEntityHeadroom, required
        - `expected_residual_value_ratio` number, double: Expected residual value ratio; absent when unspecified, which only a disabled tenure may be
        - `headroom_ratio` number, double: Headroom ratio; absent when the tenure is disabled
        - `is_default` boolean, required: Whether this is the default tenure of the category
        - `tenure` integer, required: Tenure in months
      - `tenure` integer, required: Tenure in months
  - `status` 'pending' | 'validated' | 'invalid' | 'applied', required: pending: waiting for the file to be validated; validated: ready to apply; invalid: the file has errors, upload a corrected one as a new import; applied
  - `uploaded_at` string, date-time, required: When the import was created
  - `uploaded_by` string, required: Who created the import
  - `validation_errors` HeadroomImportValidationError[], required: Every error of an invalid import; empty otherwise
    - `message` string, required: What is wrong
    - `pricing_category_identifier` string: Category of a category- or row-level error; absent on file-level errors
    - `row` integer: 1-based CSV line of a row-level error; absent on file- and category-level errors

## Other responses

- `400`: BadRequest: The entity is internal
- `401`: Unauthorized: Unauthorized response.
- `403`: InvalidScopes: Forbidden response.
- `404`: NotFound: Unknown contractual entity or import
- `409`: Conflict: The import is pending or invalid

## Changes

- **2026-10-27** `ac6979514123`: 1 info
  - api operation id `pricing-category.apply_headroom_import` removed and replaced with `pricing-category#apply_headroom_import`
- **2026-10-26** `7ff7ee94b30e`: 2 info
  - api operation id `pricing-category#apply_headroom_import` removed and replaced with `pricing-category.apply_headroom_import`
  - 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/:id/apply/post.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)