> ## 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: Updating a Position

> Update position details via the Hireflix API: name, tags, visibility, timing defaults, questions, and candidate notifications.

## When to use this

Use the `updatePosition` mutation to change details of an existing position: rename it, adjust tags, change visibility, tweak interview timing defaults (max duration, thinking time, retakes), update questions, or configure candidate notifications.

`updatePosition` is a **partial update**. Only the top-level fields you include are changed; everything else stays untouched. Arrays (`steps`, `candidateNotifications`, `tags`, `users`) are the exception: when provided, they fully replace the existing values, so always fetch the current state before updating them.

## Before you start

You'll need the position's `id`. If you don't have it, see [Fetching Positions](https://docs.hireflix.com/tech/features/positions/fetching-positions.md). Don't forget to send your [Hireflix API Key](https://docs.hireflix.com/tech/quickstart.md) in the `X-API-KEY` header to `https://api.hireflix.com/me`.

## GraphQL Playground

[https://cdn.hireflix.com/graphql-playground/index.html?query=UpdatePosition\&url=https://api.hireflix.com/me](https://cdn.hireflix.com/graphql-playground/index.html?query=UpdatePosition\&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. It's preloaded with the basic-details example — the same `UpdatePositionBasics` mutation shown in the **Basic details** tab below, which updates a position's `name`, `tags`, and `public` visibility. See that tab (and the other tabs in the **Update examples** section) for the full mutations and field notes covering every update scenario.

## Update examples

Each tab below shows a focused example. All of them use the same `updatePosition` mutation, changing only the fields relevant to that task. The last tab shows a full example combining everything.

> [tab] Basic details
>
> Rename a position, replace its tags, or toggle its public visibility.
>
> ```graphql theme={null}
> mutation UpdatePositionBasics {
>   updatePosition(input: {
>     positionId: "<position-id>"
>     name: "Senior Software Engineer"
>     tags: ["engineering", "remote", "senior"]
>     public: true
>   }) {
>     ... on MutationUpdatePositionSuccess {
>       data {
>         id
>         name
>         tags
>       }
>     }
>     ... on PositionNotFoundError {
>       notFoundMessage: message
>     }
>     ... on ValidationError {
>       validationMessage: message
>       fieldErrors { path message }
>     }
>   }
> }
> ```
>
> * **name** – new title for the position.
> * **tags** – up to 5 tags, each up to 25 characters. The array **fully replaces** existing tags.
> * **public** – whether the position is publicly accessible.

> [tab] Timing defaults
>
> Set the default answer format for every QA step in the position. Individual questions can override these values (see the **Questions** tab).
>
> ```graphql theme={null}
> mutation UpdatePositionTiming {
>   updatePosition(input: {
>     positionId: "<position-id>"
>     stepDefaults: {
>       QA: {
>         answerFormat: {
>           video: {
>             maxDurationSeconds: 180
>             timeToThinkSeconds: 30
>             numAllowedRetakes: 2
>             allowReview: true
>             allowCameraSwitching: true
>           }
>         }
>       }
>     }
>   }) {
>     ... on MutationUpdatePositionSuccess {
>       data {
>         id
>         stepDefaults {
>           QA {
>             answerFormat {
>               video {
>                 maxDurationSeconds
>                 timeToThinkSeconds
>                 numAllowedRetakes
>               }
>             }
>           }
>         }
>       }
>     }
>     ... on ValidationError { message fieldErrors { path message } }
>   }
> }
> ```
>
> | Field | Range | Notes |
> | - | - | - |
> | `maxDurationSeconds` | 60–900 | Maximum answer duration in seconds. Replaces the deprecated `timeToAnswer` field. |
> | `timeToThinkSeconds` | -1 to 600 | Thinking time before recording starts. Use `-1` to disable. |
> | `numAllowedRetakes` | -1 to 100 | Number of retakes. Use `-1` for unlimited, `0` for none. |
> | `allowReview` | boolean | Let candidates review their answer before submitting. |
> | `allowCameraSwitching` | boolean | Let candidates switch cameras on mobile. |

> [tab] Questions (steps)
>
> > [!WARNING]
> >
> > When you provide `steps`, it **replaces all existing steps**. Always fetch the current steps first and include every question you want to keep.
>
> Fetch the current steps:
>
> ```graphql theme={null}
> query GetPositionSteps {
>   position(id: "<position-id>") {
>     id
>     name
>     stepTemplates(input: {}) {
>       ... on AdminQAStep {
>         id
>         order
>         title
>         description
>         questionFormat {
>           __typename
>           ... on AdminQAImageContent {
>             images { id }
>           }
>           ... on AdminQAVideoContent {
>             media { id }
>           }
>         }
>         answerFormat {
>           ... on AdminQAVideoResponse {
>             maxDurationSeconds
>             timeToThinkSeconds
>             numAllowedRetakes
>             transcriptionLanguage
>           }
>         }
>       }
>     }
>   }
> }
> ```
>
> `answerFormat` uses the same field names here as in the `updatePosition` input, so you can send the fetched values back without renaming them. A `null` value means the question uses the position default, so send it back as `null`. The older `timeToThink` and `allowRetakes` fields are deprecated; use `timeToThinkSeconds` and `numAllowedRetakes` instead.
>
> > [!WARNING]
> >
> > Resend each existing question's `questionFormat` too. If you leave it out, the question is saved as a text-only question and its image or video is removed. For an image prompt question, pass `questionFormat: { image: { mediaIds: ["<image-media-id>"] } }`. See [Adding an Image Prompt Question](https://docs.hireflix.com/tech/features/positions/image-prompt-questions.md#image-questions-in-updateposition).
>
> Then send the updated array. Include `id` to update an existing step; omit it to add a new one. Leave out `order`: it's not an input field, and questions play in the order of the `steps` array. To reorder questions, change their position in the array.
>
> ```graphql theme={null}
> mutation UpdatePositionSteps {
>   updatePosition(input: {
>     positionId: "<position-id>"
>     steps: [
>       {
>         QA: {
>           id: "<existing-step-id>"
>           title: "Experience in DevRel?"
>           description: "Keep it to 2 minutes"
>           answerFormat: {
>             video: {
>               maxDurationSeconds: null
>               timeToThinkSeconds: null
>               numAllowedRetakes: null
>             }
>           }
>         }
>       },
>       {
>         QA: {
>           title: "Why do you want this role?"
>           answerFormat: {
>             video: { 
>               maxDurationSeconds: 180
>               timeToThinkSeconds: 10
>               numAllowedRetakes: 2
>             }
>           }
>         }
>       }
>     ]
>   }) {
>     ... on MutationUpdatePositionSuccess { data { id } }
>     ... on ValidationError { message fieldErrors { path message } }
>   }
> }
> ```
>
> Per-step `answerFormat` values override the position's `stepDefaults` for that question only.
>
> * `answerFormat` requires at least one key. To use the position defaults for a field, set that key to `null`.
> * Include `id` to update an existing step; omit it to add a new one. A step sent with its existing `id` is updated in place and keeps that `id`. In the example above, the second step has no `id`, so it's added as a new question with custom `numAllowedRetakes`, `timeToThinkSeconds`, and `maxDurationSeconds` values that override the position defaults. The `description` field is optional but recommended.

> [tab] Outro
>
> The outro is the screen candidates see after finishing the interview. Update its `title` and `subtitle` to set a custom thank-you message.
>
> ```graphql theme={null}
> mutation UpdateOutro {
>   updatePosition(input: {
>     positionId: "<id>"
>     outro: {
>       title: "Thanks for applying!"
>       subtitle: "We'll be in touch within 5 business days."
>     }
>   }) {
>     ... on MutationUpdatePositionSuccess {
>       data {
>         id
>         outro {
>           title
>           description
>         }
>       }
>     }
>     ... on ValidationError {
>       message
>       fieldErrors { path message }
>     }
>   }
> }
> ```
>
> Both fields are optional. Include only the one you want to change; the other is left untouched as this is a partial update.

> [tab] Candidate notifications
>
> Candidate notifications are rules like "send this email template 48 hours after the invite". Templates are referenced by ID, so look them up first to map the IDs to human-readable names.
>
> ```graphql theme={null}
> query GetTemplates {
>   template(type: "email") {
>     list {
>       id
>       name
>       typeEnum
>     }
>   }
> }
> ```
>
> **Repeat** with `type: "sms"` or `type: "whatsapp"` for **other channels.**
>
> > [!WARNING]
> >
> > `candidateNotifications` is fully replaced when provided. Include every notification you want active, not just the new ones.
>
> ```graphql theme={null}
> mutation UpdatePositionNotifications {
>   updatePosition(input: {
>     positionId: "<position-id>"
>     candidateNotifications: [
>       {
>         type: EMAIL
>         template: "<invite-template-id>"
>         when: AFTER_INVITE
>         hours: 0
>       },
>       {
>         type: EMAIL
>         template: "<reminder-template-id>"
>         when: AFTER_INVITE
>         hours: 48
>       },
>       {
>         type: EMAIL
>         template: "<completion-template-id>"
>         when: AFTER_FINISH
>         hours: 0
>       }
>     ]
>   }) {
>     __typename
>     ... on MutationUpdatePositionSuccess { data { id } }
>     ... on ValidationError {
>       __typename
>       validationMessage: message
>       fieldErrors { path message }
>     }
>     ... on PositionNotFoundError {
>       notFoundMessage: message
>       __typename
>     }
>   }
> }
> ```
>
> | `when` | Timing anchor |
> | - | - |
> | `AFTER_INVITE` | Relative to when the candidate was invited. |
> | `AFTER_FINISH` | Relative to when the candidate completed the interview. |

> [tab] Full example
>
> > [!WARNING]
> >
> > Before running this mutation, replace every placeholder with real values from your account:
> >
> > * `<position-id>` – fetch with [Fetching Positions](https://docs.hireflix.com/tech/features/positions/fetching-positions.md).
> > * `<existing-step-id>` / `<another-step-id>` – fetch with the `stepTemplates` query in the **Questions (steps)** tab.
> > * `<invite-template-id>` / `<reminder-template-id>` / `<expiry-template-id>` – fetch with the `template(type: "email")` query in the **Candidate notifications** tab to see all available templates and their IDs.
>
> ```graphql theme={null}
> mutation UpdatePositionFull {
>   updatePosition(input: {
>     positionId: "<position-id>"
>     name: "Senior Software Engineer"
>     tags: ["engineering", "remote", "senior"]
>     public: true
>     outro: {
>       title: "Thanks for applying!"
>       subtitle: "We'll be in touch within 5 business days."
>     }
>     stepDefaults: {
>       QA: {
>         answerFormat: {
>           video: {
>             maxDurationSeconds: 180
>             timeToThinkSeconds: 30
>             numAllowedRetakes: 1
>             allowReview: true
>             allowCameraSwitching: true
>           }
>         }
>       }
>     }
>     steps: [
>       {
>         QA: {
>           id: "<existing-step-id>"
>           title: "Tell us about yourself"
>           description: "Keep it to 2 minutes"
>           answerFormat: {
>             video: {
>               maxDurationSeconds: null
>               timeToThinkSeconds: null
>               numAllowedRetakes: null
>             }
>           }
>         }
>       },
>       {
>         QA: {
>           title: "Why do you want this role?"
>           answerFormat: {
>             video: { maxDurationSeconds: 180 }
>           }
>         }
>       }
>     ]
>     candidateNotifications: [
>       {
>         type: EMAIL
>         template: "<invite-template-id>"
>         when: AFTER_INVITE
>         hours: 0
>       },
>       {
>         type: EMAIL
>         template: "<invite-reminder-template-id>"
>         when: AFTER_INVITE
>         hours: 48
>       },
>       {
>         type: EMAIL
>         template: "<completion-template-id>"
>         when: AFTER_FINISH
>         hours: 0
>       }
>     ]
>   }) {
>     __typename
>     ... on MutationUpdatePositionSuccess {
>       data {
>         id
>         name
>         tags
>         outro {
>           title
>           description
>         }
>         stepDefaults {
>           QA {
>             answerFormat {
>               video {
>                 maxDurationSeconds
>                 timeToThinkSeconds
>                 numAllowedRetakes
>               }
>             }
>           }
>         }
>       }
>     }
>     ... on PositionNotFoundError {
>       notFoundMessage: message
>     }
>     ... on ValidationError {
>       validationMessage: message
>       fieldErrors { path message }
>     }
>   }
> }
> ```

## Handling the response

`updatePosition` returns a union type. Always match on the possible cases:

* **`MutationUpdatePositionSuccess`** – the update succeeded; read the updated position from `data`.
* **`PositionNotFoundError`** – the `positionId` doesn't match any position on your account.
* **`ValidationError`** – one or more fields failed validation; inspect `fieldErrors` for the offending `path` and `message`.
* **Media errors** (`MediaNotFoundError`, `MediaFileUploadTooBigError`, ...) – only relevant when you pass videos or images; see [Adding an Image Prompt Question](https://docs.hireflix.com/tech/features/positions/image-prompt-questions.md#handling-the-response).

## Key reminders

* **Partial updates** – omitted top-level fields are left untouched.
* **Arrays replace entirely** – `steps`, `candidateNotifications`, `tags`, and `users` are fully replaced when provided. Fetch first, then update.
* **Keep question images and videos** – when resending `steps`, include each question's `questionFormat`, or its image or video is removed.
* **Step IDs stay the same** – a step sent with its existing `id` keeps that `id`; only steps sent without an `id` get a new one.
* **Template IDs** – use `template(type: "email") { list { id name } }` to map human-readable names to IDs before configuring notifications.
* **`maxDurationSeconds`** replaces the deprecated `timeToAnswer` field.

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


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