How-to: Inviting a Candidate

When to use this

Use this mutation when you want to invite a candidate to a Hireflix interview for a position from your own system. This creates a new interview instance for that candidate and automatically sends them an email invite.

GraphQL Request

Use this mutation to invite a candidate to a specific position. Don’t forget to replace the input parameters, optionally including an external ID linking to a candidate record in your own system. Don’t forget to update the Hireflix API Key in the headers.

Adding a phone number is optional. But if you include it, use the full international format with country code, e.g. +1 for the US. Without a country code, the invite will fail.

Explanation

• positionId – the ID of the Hireflix position you want to invite the candidate to. You can find this ID by fetching positions.
• candidate – required details about the candidate (email, first name, last name).
• externalId – optional field to link this interview to a candidate record in your system.
• url – the generated candidate’s interview link (public and short).

Example Response

{
  "data": {
    "inviteCandidateToInterview": {
      "__typename": "InterviewType",
      "id": "68d4164f19367e041b2030c0",
      "url": {
        "short": "https://hflx.io/c/HQ2oCtTC",
        "public": "https://app.hireflix.com/HQ2oCtTC"
      }
    }
  }
}

If you want to provide a public form for users to apply, you can pass parameters to public links, such as email and first name. This FAQ guide explains how to do this.

Tips

• Handle errors gracefully:
  • If the candidate has already been invited, you’ll see InterviewAlreadyExistsInPositionError.
  • If you hit the maximum limit of invitations per month for your plan, you’ll see ExceededInvitesThisPeriodError.
  • If you’ve already used the external ID when inviting candidates, you’ll see InterviewExternalIdAlreadyExistsInPositionError .
• Use externalId so you can match records with candidate records in your own system.
• For bulk invites, loop through multiple candidates and send one mutation per candidate.

✅ FAQ: How can I invite multiple candidates at once?

While you must call the mutation once per candidate, you can still send multiple invitations in a single HTTP request using GraphQL aliases. This allows you to batch multiple mutations together.

mutation {

  result1: inviteCandidateToInterview(input: {
    positionId: "abc123"
    candidate: { firstName: "Datta", email: "[e-mail]" }
  }) {
    ... on Interview { id }
  }

  result2: inviteCandidateToInterview(input: {
    positionId: "abc123"
    candidate: { firstName: "Datta2", email: "[e-mail]" }
  }) {
    ... on Interview { id }
  }

  result3: inviteCandidateToInterview(input: {
    positionId: "abc123"
    candidate: { firstName: "Datta3", email: "[e-mail]" }
  }) {
    ... on Interview { id }
  }
}

In this example:

• result1, result2, and result3 are GraphQL aliases
• Each alias represents a separate mutation call
• All mutations are sent in one HTTP request

Learn next?

Let’s learn how to create a shareable interview URL.