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

# Create a headroom import

`POST /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:edit`

Create a pending headroom import of an external contractual entity and sign the URL its CSV is uploaded to. Each category in the file replaces the entity's rows for it once applied; categories not in the file are untouched.

## Path parameters

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

## Request body

- CreateHeadroomImportRequestBody
  - `filename` string, required: Name of the file to upload, for display

## Response `201`

Created response.

- HeadroomImportUploadResult
  - `id` string, regexp, required: Headroom import ID
  - `upload_headers` object, required: Headers the upload must send, or GCS rejects it
  - `upload_url` string, required: Signed URL to PUT the CSV to, valid for one hour

## Other responses

- `400`: BadRequest: Internal entity or invalid filename
- `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.create_headroom_import` removed and replaced with `pricing-category#create_headroom_import`
- **2026-10-26** `7ff7ee94b30e`: 2 info
  - api operation id `pricing-category#create_headroom_import` removed and replaced with `pricing-category.create_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/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)