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. Don’t forget to send your Hireflix API Key in the X-API-KEY header to https://api.hireflix.com/me.

GraphQL Playground

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.

Basic details

Rename a position, replace its tags, or toggle its public visibility.

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.

Timing defaults

Set the default answer format for every QA step in the position. Individual questions can override these values (see the Questions tab).

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.

Questions (steps)

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:

query GetPositionSteps {
  position(id: "<position-id>") {
    id
    name
    stepTemplates(input: {}) {
      ... on AdminQAStep {
        id
        order
        title
        description
        answerFormat {
          ... on AdminQAVideoResponse {
            maxDurationSeconds
            timeToThink
            allowRetakes
          }
        }
      }
    }
  }
}

Then send the updated array. Include id to update an existing step; omit it to add a new one.

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. 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.

Outro

The outro is the screen candidates see after finishing the interview. Update its title and subtitle to set a custom thank-you message.

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.

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.

query GetTemplates {
  template(type: "email") {
    list {
      id
      name
      typeEnum
    }
  }
}

Repeat with type: "sms" or type: "whatsapp" for other channels.

candidateNotifications is fully replaced when provided. Include every notification you want active, not just the new ones.

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.

Full example

Before running this mutation, replace every placeholder with real values from your account:

• <position-id> – fetch with Fetching Positions.
• <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.

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.

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.
• 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.

Learn next?

Let’s learn how to archive a position.