> ## 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: Fetching Positions

## When to use this

Use this query when you want to display the list of available positions from Hireflix inside your own system. Positions act as interview templates, each containing a set of questions and settings for a role.

## GraphQL Request

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=FetchPositions\&url=https://api.hireflix.com/me](https://cdn.hireflix.com/graphql-playground/index.html?query=FetchPositions\&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 `FetchPositions` query is reproduced below so you can read and reason about it directly.

```graphql theme={null}
query FetchPositions {
  positions {
    id
    name
    tags
    archivedAtISO
  }
}
```

* `positions` takes no arguments and returns **every position** on the account — filter client-side (e.g. on `archivedAtISO`) rather than expecting server-side filtering.
* `id` is the position identifier needed to invite candidates ([`InviteCandidateToInterview`](https://docs.hireflix.com/tech/features/interviews/inviting-candidate)) or list its interviews ([`ListPositionInterviews`](https://docs.hireflix.com/tech/features/interviews/list-interviews-for-position)).
* `tags` are optional free-form labels (e.g. location, department) useful for disambiguating similarly named positions.
* `archivedAtISO` is `null` for open positions, and an ISO 8601 timestamp for archived ones — use it, not a separate boolean, to determine whether a position is still active.
* Other available fields not shown here: `createdAt` and `question.title` / `question.description` (per-question metadata for the position).
* Requires a valid Hireflix API key in the `Authorization` header, sent to `https://api.hireflix.com/me`.

### Explanation

* **id** – unique identifier for the position (needed for invites).
* **name** – title of the position (e.g. “Sales Manager”).
* **tags** – optional labels like location or department, useful to distinguish similar positions.
* **archivedAtISO** – Use this property to filter for active positions. If a position has been closed, the field contains a timestamp of when it was archived. If the value is `null`, the position is still open.

### **Other helpful fields**

* **createdAt** - the date the position was created (ISO datetime).
* **question.title** - an array of all interview question titles in the position.
* **question.description** - an array of all interview question descriptions.

### Example Response

```json theme={null}
{
  "data": {
    "positions": [
      {
        "id": "63d00b73df403de202d97e73",
        "name": "Sales Manager",
        "tags": ["US"],
        "archivedAtISO": null
      },
      {
        "id": "63d00b73df403de202d97e74",
        "name": "Sales Manager",
        "tags": ["UK"],
        "archivedAtISO": null
      }
    ]
  }
}
```

### Tips

* **Filter out archived**: Don’t show positions where `archived` is `true`.
* **Show tags for clarity**: Present “Sales Manager (US)” vs “Sales Manager (UK)”.

> [card] [Learn next?](https://docs.hireflix.com/tech/features/positions/updating-position.md)
>
> Let's learn how to update a position.


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