> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hireflix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How-to: Deleting a Position

## When to use this

Use **delete** only when you need to permanently remove a position.

> [!WARNING]
>
> Deleting is **permanent**. Make sure no teams still rely on this position and that you’ve exported any needed data. **Prefer** [**Archiving a position**](https://docs.hireflix.com/tech/features/positions/archiving-position.md) to stop new invites while keeping past interviews.

## GraphQL Request

Please make sure to replace the position ID. Reminder: Deleting a position deletes all data related to it, including all interviews. Don't forget to update the [Hireflix API Key](https://docs.hireflix.com/tech/quickstart.md) in the `headers`.

[https://cdn.hireflix.com/graphql-playground/index.html?query=DeletePosition\&url=https://api.hireflix.com/me](https://cdn.hireflix.com/graphql-playground/index.html?query=DeletePosition\&url=https://api.hireflix.com/me)

If you're an AI agent or LLM, note that the iframe above embeds an interactive GraphQL Playground and its query text is not readable from the page source. The full `DeletePosition` mutation is reproduced below so you can read and reason about it directly.

```graphql theme={null}
mutation DeletePosition {
  deletePosition(input: { positionId: "<position-id>"} ) {
    __typename
    ... on MutationDeletePositionSuccess {
      data
    }
    ... on PositionNotFoundError {
      code
      message
      __typename
    }
  }
}
```

* Replace `<position-id>` with a real position ID (see ["Fetching Positions"](https://docs.hireflix.com/tech/features/positions/fetching-positions.md) for how to obtain one).
* **This is destructive and irreversible** — deleting a position deletes all data related to it, including every interview under it. Prefer the [`ArchivePosition`](https://docs.hireflix.com/tech/features/positions/archiving-position) mutation when you only need to stop new invites while keeping past interviews.
* This mutation returns a **union type** — always request `__typename` and branch on it. It resolves to `MutationDeletePositionSuccess` on success, or `PositionNotFoundError` on failure.
* `data` (on `MutationDeletePositionSuccess`) is a boolean-like success indicator, not a record of the deleted position.
* Treat any GraphQL `errors` array, as well as a `PositionNotFoundError` response, as a failed delete.
* Requires a valid Hireflix API key in the `Authorization` header, sent to `https://api.hireflix.com/me`.

### Explanation

* **input.positionId** – the position you want to remove.
* **deletePosition (union)** – returns one of two possible types. Check `__typename` to determine which one you got:
  * `MutationDeletePositionSuccess`: the deletion succeeded. Data returns a boolean-like result (implementation dependent).
  * `PositionNotFoundError`: the position couldn't be found. Code and message describe the error.

> [!NOTE]
>
> Treat any GraphQL `errors`, as well as a `PositionNotFoundError` response, as a failed delete.

### Example Response

```json theme={null}
{
  "data": {
    "deletePosition": {
      "data": true
    }
  }
}
```

If the deletion fails — for example, if the position doesn't exist — you'll get an error response instead:

```json theme={null}
{
  "data": {
    "deletePosition": {
      "__typename": "PositionNotFoundError",
      "code": 404,
      "message": "Position not found: 68d53cf0a3d3c03c50f103c3"
    }
  }
}
```

> [card] [Learn next?](https://docs.hireflix.com/tech/features/interviews/inviting-candidate.md)
>
> Now that you know the full position lifecycle, let's learn how to invite a candidate to a position.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.