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

> Create a new position (interview template) via the Hireflix API: name, tags, questions, outro, and video content.

## When to use this

A **position** is an interview template — it holds a name, one or more questions (steps), an optional outro, and optional intro/outro/question videos. Use `createPosition` whenever you want to set up a new role programmatically instead of using the Hireflix dashboard. Once a position exists, you invite candidates to it to actually create interviews (see [Inviting a Candidate](https://docs.hireflix.com/tech/features/interviews/inviting-candidate.md)).

Videos are optional — you can attach an intro, outro, and/or per-question video, covered in [Adding video content to a position](#adding-video-content-to-a-position) below.

Want candidates to answer while looking at an image, such as a diagram or a chart? See [Adding an Image Prompt Question](https://docs.hireflix.com/tech/features/positions/image-prompt-questions.md). Images are uploaded differently from videos, and only one image per question is supported.

> [!TIP]
>
> If you want a **unique video for every question** on every position, it's usually faster to build that position from the Hireflix dashboard — recording and uploading several question videos per position through the API means several reserve-upload round trips per position.
>
> The API really shines for **bulk-creating positions or interviews** where you don't need a bespoke video per question. A common pattern: record **one intro and one outro video**, upload each **once**, and reuse their `mediaId` across every position you create via the API. You still get a personal-feeling candidate experience (a real face on the intro/outro) without re-uploading video per position.
>
> **-> Want to run this entirely from a script or backend server? See [Bulk-Creating Positions with a Script](https://docs.hireflix.com/tech/features/positions/bulk-creating-positions.md).**

## Before you start

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`. Unlike updating or archiving a position, creating one needs no prior IDs — `createPosition` is often the very first mutation you'll call against the API.

## GraphQL Playground

[https://cdn.hireflix.com/graphql-playground/index.html?query=CreatePosition\&url=https://api.hireflix.com/me](https://cdn.hireflix.com/graphql-playground/index.html?query=CreatePosition\&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 example — the same `CreatePosition` mutation shown in the **Basic** tab below. See that tab (and the other tabs in the **Create examples** section) for the full mutations and field notes covering every scenario.

## Create examples

Each tab below shows a variation of the same `createPosition` mutation, from a minimal position to one with tags, an outro, and multiple questions.

> [tab] Basic
>
> The smallest valid position: a name and one question. `answerFormat: { video: {} }` uses the default recording settings (120s max duration, 30s to think, no retakes).
>
> ```graphql theme={null}
> mutation CreatePosition {
>   createPosition(input: {
>     name: "Junior Developer"
>     steps: [
>       {
>         QA: {
>           title: "Tell us about yourself"
>           answerFormat: {
>             video: {}
>           }
>         }
>       }
>     ]
>   }) {
>     ... on MutationCreatePositionSuccess {
>       data {
>         id
>         name
>       }
>     }
>     ... on ValidationError {
>       message
>       fieldErrors { path message }
>     }
>   }
> }
> ```
>
> * **name** – required, 1–50 characters.
> * **steps** – required, at least 1 entry (max 50). Each `QA` step needs a `title` and an `answerFormat`.
> * **answerFormat.video** – required for a QA step. An empty object `{}` just means "use the defaults" — no custom duration, thinking time, or retakes.

> [tab] With tags & outro
>
> Adds `tags` for categorization and a custom `outro` screen shown to candidates after they finish.
>
> ```graphql theme={null}
> mutation CreatePosition {
>   createPosition(input: {
>     name: "Senior DX Researcher"
>     tags: ["DX", "DevRel"]
>     steps: [
>       {
>         QA: {
>           title: "Tell us about yourself"
>           answerFormat: {
>             video: {
>               maxDurationSeconds: 120
>               timeToThinkSeconds: 20
>               numAllowedRetakes: 0
>             }
>           }
>         }
>       }
>     ]
>     outro: {
>       title: "Thank you for applying!"
>       subtitle: "We'll reach out in 5 business days."
>     }
>   }) {
>     ... on MutationCreatePositionSuccess {
>       data {
>         id
>         name
>       }
>     }
>     ... on ValidationError {
>       message
>       fieldErrors { path message }
>     }
>   }
> }
> ```
>
> * **tags** – up to 5 tags, each 1–25 characters.
> * **answerFormat.video** – here the defaults are set explicitly instead of left as `{}`: `maxDurationSeconds` (60–900), `timeToThinkSeconds` (-1 to 600, `-1` disables the countdown), `numAllowedRetakes` (-1 to 100, `-1` unlimited, `0` none). If you're not sure what these should be, [Tailoring the Interview](https://docs.hireflix.com/user/building-the-interview/tailoring-the-interview.md) explains what each setting means for the candidate (answering time limit, thinking time, retakes) from the dashboard's point of view — the same concepts, just named slightly differently in the UI.
> * **outro.title** / **outro.subtitle** – both required once you include `outro` at all. Note the input field is `subtitle`, but it comes back as `description` when you query it (see the next tab).

> [tab] Full example
>
> Combines tags, an outro, **two** questions with different settings, and an `introVideo` that references an **existing** `mediaId`.
>
> > [!WARNING]
> >
> > This example does not upload a new video — `introVideo.mediaId` assumes you already have a `mediaId` from a previous upload. To upload a brand-new video and get a `mediaId`, see [Adding video content to a position](#adding-video-content-to-a-position) below.
>
> ```graphql theme={null}
> mutation CreatePosition {
>   createPosition(input: {
>     name: "My Position"
>     tags: ["DevRel", "DX"]
>     introVideo: {
>       mediaId: "6a8817e6c7f9fbb562980914"
>     }
>     outro: {
>       title: "Thanks for applying!"
>       subtitle: "We'll be in touch soon."
>     }
>     steps: [
>       {
>         QA: {
>           title: "Tell us about yourself"
>           answerFormat: {
>             video: {}
>           }
>         }
>       }
>       {
>         QA: {
>           title: "Why do you want this role?"
>           answerFormat: {
>             video: {
>               maxDurationSeconds: 300
>               timeToThinkSeconds: 60
>               numAllowedRetakes: -1
>             }
>           }
>         }
>       }
>     ]
>   }) {
>     ... on MutationCreatePositionSuccess {
>       data {
>         id
>         name
>         tags
>         outro {
>           title
>           description
>         }
>       }
>     }
>     ... on ValidationError {
>       message
>       fieldErrors { path message }
>     }
>   }
> }
> ```
>
> * **steps** accepts multiple `QA` entries — each one becomes a separate question, played in the order of the array. There's no `order` field to set; the `order` you see when querying a position is derived from this.
> * The second question sets `numAllowedRetakes: -1` (unlimited retakes) and a longer `maxDurationSeconds`/`timeToThinkSeconds` than the first, which uses the defaults (`{}`).
> * **introVideo.mediaId** references a video that was **already uploaded** — this mutation itself doesn't upload anything. Keep reading below to see how to get a real `mediaId`.

> [!NOTE]
>
> None of the examples above upload a new video — `mediaId` fields only **reference** media that already exists in your account. To upload a video and obtain a real `mediaId`, follow [Adding video content to a position](#adding-video-content-to-a-position) below, then come back and drop the returned `mediaId` into `introVideo`, `outro.video`, or a step's `questionFormat.video`.

> [!TIP]
>
> You can always verify what you created by opening [admin.hireflix.com/jobs](https://admin.hireflix.com/jobs) and searching for the position by name.

## Handling the response

`createPosition` returns a union type — always branch on the possible cases:

* **`MutationCreatePositionSuccess`** – the position was created; read it from `data`.
* **`ValidationError`** – one or more fields failed validation; inspect `fieldErrors` for the offending `path` and `message`.
* **`MediaNotFoundError`** – a `mediaId` you referenced (e.g. in `introVideo`) doesn't exist, doesn't belong to your company, or its upload reservation was never completed.
* **`MediaFileTooLargeError`** / **`MediaFileUploadMimeTypeNotSupportedError`** / **`MediaMimeTypeMismatchError`** – only relevant if you're referencing a media asset with the wrong type or size for where it's used.
* **`MediaFileUploadTooBigError`** – only relevant for [image prompt questions](https://docs.hireflix.com/tech/features/positions/image-prompt-questions.md): an uploaded image is over 10 MB.
* **`ThemeNotFoundError`** / **`UsersNotFoundError`** / **`TemplatesNotFoundError`** – the `themeId`, `users`, or notification `template` IDs you passed don't exist or aren't accessible to you.

## Key reminders

* **`name`** is required, 1–50 characters.
* **`steps`** is required — at least 1, max 50. Each step currently supports the `QA` type.
* **`public`** defaults to `true` if omitted.
* **`mediaId` fields never upload anything** — they only reference media created via a `reservePosition*VideoUpload` mutation (see below).
* **Video files**: 150 MB max, any video format/codec (MP4 H.264 is a safe default). **4:3** aspect ratio fills the screen best; 16:9 works but shows black bars. See [Video requirements](#video-requirements) below.
* **Image prompt questions** use `questionFormat.image` and a multipart upload in the same request, with **one image per question** (10 MB max). See [Adding an Image Prompt Question](https://docs.hireflix.com/tech/features/positions/image-prompt-questions.md).
* **`themeId`** must be a theme in your own account. Create one with `createTheme` (`name` and `primaryColor` are required; `logo` is a multipart file upload), and change it later with `updateTheme`.
* Verify a position was created by checking [admin.hireflix.com/jobs](https://admin.hireflix.com/jobs) and searching by name.
* Unsure what `maxDurationSeconds`, `timeToThinkSeconds`, or `numAllowedRetakes` should be set to? See [Tailoring the Interview](https://docs.hireflix.com/user/building-the-interview/tailoring-the-interview.md) for what each setting means for candidates.

## Adding video content to a position

A position can show a video in three places: the **intro** screen, the **outro** screen, and a **QA question** prompt. All three follow the same three-step flow:

1. **Reserve** an upload with the matching mutation for that destination.
2. **PUT** the video file to the returned `presignedPutUrl`.
3. **Pass the returned `mediaId`** into `createPosition` (or [`updatePosition`](https://docs.hireflix.com/tech/features/positions/updating-position) for an existing position).

> [!TIP]
>
> Per-question videos are usually easiest to record and upload from the dashboard. If you're bulk-creating positions via the API, consider uploading just **one intro and one outro video** and reusing their `mediaId` across every position — same personal touch, no re-upload per position.

| Destination | Reserve mutation |
| - | - |
| Intro video | `reservePositionIntroVideoUpload` |
| Outro video | `reservePositionOutroVideoUpload` |
| QA question video | `reservePositionQAVideoContentUpload` |

All three take the same input — `mimeType` (must match `video/*`, e.g. `"video/mp4"`) and `sizeBytes` (max 157286400 bytes / 150 MB) — and return the same shape: `{ mediaId, presignedPutUrl, expiresAt }`. `expiresAt` is roughly **1 hour** from the reservation — upload before then, or reserve again.

### Video requirements

Since every video gets transcoded after upload, Hireflix accepts a very wide range of formats and codecs — you don't need to pre-convert a video before uploading it.

* **File size** – 150 MB max (157,286,400 bytes). Larger file? Compress it first — [this short Loom](https://www.loom.com/share/8966c1af1a494855ae7a2c7c10627539) walks through doing that for free.
* **Format** – any video format/codec works (MP4, MOV, MKV, WebM, AVI, FLV, and more; H.264, H.265, VP8, VP9, AV1, and most common audio tracks). If you want a safe default to recommend to users, **MP4 (H.264)** is guaranteed to decode correctly, but there's no need to force candidates or recruiters to re-encode to it — `.mov` and `.webm` work just as well.
* **Aspect ratio** – **4:3** fills the candidate's screen edge-to-edge and is the most reliable across devices. A 16:9 (HD widescreen) video also works fine, but plays with black bars above and below since it doesn't fill the 4:3 frame.

If you're an AI agent or LLM, note that the Loom video linked above (compressing a video for free) can't be read from the page source. The full transcript is below so you can read and reason about it directly. In the video, a Hireflix team member shows a customer how to shrink a video with [HandBrake](https://handbrake.fr/). The 40 MB limit mentioned in the video was the limit at the time of recording; the current limit is **150 MB**, as stated above.

**Video transcript: compressing a video with HandBrake**

* **0:00** How are you? Look, it's so easy to use HandBrake. You download it.
* **0:04** This is the Windows version. I don't know if you're using Mac, but I hope it's similar. As you can see, you just have to drop the file in.
* **0:10** So I'm going to go ahead and drop a video file in there. In this case, it's one that's a few megabytes.
* **0:18** Once you've put the video in, go to the **Video** tab. Here, this is the key: you see this bar here.
* **0:28** Let me see if I can zoom in. It doesn't seem to. It says **Constant Quality**, and there's a slider you can move from left to right.
* **0:37** The further to the right you go, the less it compresses, but the better the quality. In your case, since your file was very close to the 40 MB limit, I put a three here.
* **0:49** So it was very much to the right. I did that and it already got the file below 40 MB, no problem.
* **0:56** If you want, you can move it further left. That reduces the file size even more, but the quality will be a bit worse.
* **1:02** But honestly, I've sometimes moved it as far as around here, and it still reduces files a lot and you won't notice a difference in quality. Especially because, remember, these videos are watched on small devices: phones and small screens.
* **1:17** So you don't need a full high-quality video. That's all you do. You set this, then click **Start Encode** at the top.
* **1:25** You see it says **Start Encode**. And that's all there is to it. It will start processing. Maybe it takes two or three minutes.
* **1:32** Once it's done, you can check the video it produces, and it's going to be perfect. If you have any other questions, let me know.

### Uploading the file

Once you have a `presignedPutUrl`, PUT the raw file to it with a matching `Content-Type`:

```bash theme={null}
curl -X PUT '<presignedPutUrl>' \
  -H "Content-Type: video/mp4" \
  --upload-file "/path/to/video.mp4"
```

> [!WARNING]
>
> **Common pitfalls:**
>
> * **Always single-quote the URL.** Some shells (zsh in particular, via `url-quote-magic`) will auto-insert backslashes before `?`, `=`, and `&` when you paste an unquoted or double-quoted URL, silently corrupting the signature and producing an `AccessDenied` error. Wrapping it in single quotes (`'...'`) avoids this entirely.
> * **`Content-Type` must exactly match** the `mimeType` you declared when reserving the upload.
> * **Upload before `expiresAt`.** If it expires, re-run the reserve mutation for a fresh URL.
> * A successful PUT to the presigned URL returns an empty `200 OK` body — check the HTTP status, not the response content.

With the file uploaded, the `mediaId` from step 1 is ready to use. The tabs below show each reserve mutation paired with the `createPosition` call that uses its `mediaId`, followed by a full example combining all three.

> [tab] Intro video
>
> **1. Reserve the upload:**
>
> ```graphql theme={null}
> mutation ReserveIntroVideo {
>   reservePositionIntroVideoUpload(input: {
>     mimeType: "video/mp4"
>     sizeBytes: 10485760
>   }) {
>     ... on MutationReservePositionIntroVideoUploadSuccess {
>       data {
>         mediaId
>         presignedPutUrl
>         expiresAt
>       }
>     }
>     ... on ValidationError {
>       validationMessage: message
>       fieldErrors { path message }
>     }
>     ... on MediaFileTooLargeError { tooLargeMessage: message }
>     ... on MediaFileUploadMimeTypeNotSupportedError { mimeTypeMessage: message }
>   }
> }
> ```
>
> **2. PUT the file** to `presignedPutUrl` (see [Uploading the file](#uploading-the-file) above).
>
> **3. Use the `mediaId` in `createPosition`:**
>
> ```graphql theme={null}
> mutation CreatePosition {
>   createPosition(input: {
>     name: "Senior DX Researcher"
>     introVideo: {
>       mediaId: "<mediaId-from-step-1>"
>     }
>     steps: [
>       {
>         QA: {
>           title: "Tell us about yourself"
>           answerFormat: { video: {} }
>         }
>       }
>     ]
>   }) {
>     ... on MutationCreatePositionSuccess {
>       data {
>         id
>         name
>         intro { id url }
>       }
>     }
>     ... on MediaNotFoundError { notFoundMessage: message }
>     ... on ValidationError {
>       validationMessage: message
>       fieldErrors { path message }
>     }
>   }
> }
> ```

> [tab] Outro video
>
> **1. Reserve the upload:**
>
> ```graphql theme={null}
> mutation ReserveOutroVideo {
>   reservePositionOutroVideoUpload(input: {
>     mimeType: "video/mp4"
>     sizeBytes: 10485760
>   }) {
>     ... on MutationReservePositionOutroVideoUploadSuccess {
>       data {
>         mediaId
>         presignedPutUrl
>         expiresAt
>       }
>     }
>     ... on ValidationError {
>       validationMessage: message
>       fieldErrors { path message }
>     }
>     ... on MediaFileTooLargeError { tooLargeMessage: message }
>     ... on MediaFileUploadMimeTypeNotSupportedError { mimeTypeMessage: message }
>   }
> }
> ```
>
> **2. PUT the file** to `presignedPutUrl` (see [Uploading the file](#uploading-the-file) above).
>
> **3. Use the `mediaId` in `createPosition`:**
>
> > [!NOTE]
> >
> > `outro.title` and `outro.subtitle` are both required as soon as you include `outro`, even if all you want to change is the video.
>
> ```graphql theme={null}
> mutation CreatePosition {
>   createPosition(input: {
>     name: "Senior DX Researcher"
>     outro: {
>       title: "Thanks for applying!"
>       subtitle: "We'll be in touch soon."
>       video: {
>         mediaId: "<mediaId-from-step-1>"
>       }
>     }
>     steps: [
>       {
>         QA: {
>           title: "Tell us about yourself"
>           answerFormat: { video: {} }
>         }
>       }
>     ]
>   }) {
>     ... on MutationCreatePositionSuccess {
>       data {
>         id
>         name
>         outro {
>           title
>           description
>           media { id url }
>         }
>       }
>     }
>     ... on MediaNotFoundError { notFoundMessage: message }
>     ... on ValidationError {
>       validationMessage: message
>       fieldErrors { path message }
>     }
>   }
> }
> ```

> [tab] QA question video
>
> **1. Reserve the upload:**
>
> ```graphql theme={null}
> mutation ReserveQAVideoContent {
>   reservePositionQAVideoContentUpload(input: {
>     mimeType: "video/mp4"
>     sizeBytes: 10485760
>   }) {
>     ... on MutationReservePositionQAVideoContentUploadSuccess {
>       data {
>         mediaId
>         presignedPutUrl
>         expiresAt
>       }
>     }
>     ... on ValidationError {
>       validationMessage: message
>       fieldErrors { path message }
>     }
>     ... on MediaFileTooLargeError { tooLargeMessage: message }
>     ... on MediaFileUploadMimeTypeNotSupportedError { mimeTypeMessage: message }
>   }
> }
> ```
>
> **2. PUT the file** to `presignedPutUrl` (see [Uploading the file](#uploading-the-file) above).
>
> **3. Use the `mediaId` as the step's question content:**
>
> ```graphql theme={null}
> mutation CreatePosition {
>   createPosition(input: {
>     name: "Senior DX Researcher"
>     steps: [
>       {
>         QA: {
>           title: "Watch this and respond"
>           questionFormat: {
>             video: {
>               mediaId: "<mediaId-from-step-1>"
>             }
>           }
>           answerFormat: { video: {} }
>         }
>       }
>     ]
>   }) {
>     ... on MutationCreatePositionSuccess {
>       data {
>         id
>         name
>         stepTemplates(input: {}) {
>           ... on AdminQAStep {
>             id
>             title
>             questionFormat {
>               ... on AdminQAVideoContent {
>                 media { id url }
>               }
>             }
>           }
>         }
>       }
>     }
>     ... on MediaNotFoundError { notFoundMessage: message }
>     ... on ValidationError {
>       validationMessage: message
>       fieldErrors { path message }
>     }
>   }
> }
> ```
>
> * `questionFormat.video.mediaId` is the **question prompt** (what the candidate watches before answering) — it's separate from `answerFormat`, which controls the candidate's recorded response.

> [tab] Full example
>
> > [!WARNING]
> >
> > This assumes you've already run **three separate reserve calls** — one each via `reservePositionIntroVideoUpload`, `reservePositionOutroVideoUpload`, and `reservePositionQAVideoContentUpload` — uploaded each file, and are using their three distinct `mediaId` values below. A `mediaId` reserved for one destination is not interchangeable with another.
>
> ```graphql theme={null}
> mutation CreatePosition {
>   createPosition(input: {
>     name: "Senior DX Researcher"
>     tags: ["DX", "DevRel"]
>     introVideo: {
>       mediaId: "<intro-mediaId>"
>     }
>     outro: {
>       title: "Thanks for applying!"
>       subtitle: "We'll be in touch soon."
>       video: {
>         mediaId: "<outro-mediaId>"
>       }
>     }
>     steps: [
>       {
>         QA: {
>           title: "Watch this and respond"
>           questionFormat: {
>             video: {
>               mediaId: "<qa-question-mediaId>"
>             }
>           }
>           answerFormat: {
>             video: {
>               maxDurationSeconds: 180
>               timeToThinkSeconds: 30
>               numAllowedRetakes: 1
>             }
>           }
>         }
>       }
>     ]
>   }) {
>     ... on MutationCreatePositionSuccess {
>       data {
>         id
>         name
>         tags
>         intro { id url }
>         outro {
>           title
>           description
>           media { id url }
>         }
>         stepTemplates(input: {}) {
>           ... on AdminQAStep {
>             id
>             title
>             questionFormat {
>               ... on AdminQAVideoContent {
>                 media { id url }
>               }
>             }
>           }
>         }
>       }
>     }
>     ... on MediaNotFoundError { notFoundMessage: message }
>     ... on ValidationError {
>       validationMessage: message
>       fieldErrors { path message }
>     }
>   }
> }
> ```

> [!TIP]
>
> Open [admin.hireflix.com/jobs](https://admin.hireflix.com/jobs), find the position by name, and preview it to confirm the intro/outro/question videos play back correctly.

> [card] [Learn next?](https://docs.hireflix.com/tech/features/positions/image-prompt-questions.md)
>
> Let's learn how to add an image prompt question, where candidates answer while looking at an image.


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