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, by default, sends them an email invite. If you’d rather send the invitation from your own system, see Sending invitations from your own system.

​

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.
• disableNotifications – optional. Set to true to stop Hireflix from sending any notifications to the candidate. See Sending invitations from your own system.
• urls – the generated candidate’s interview link (public, private, and short-hand url).

​

Example Response

{
  "data": {
    "inviteCandidateToInterview": {
      "__typename": "InterviewType",
      "id": "68d4164f19367e041b2030c0",
      "urls": {
        "short": "https://hflx.io/c/tCDBFCpb2ncH",
        "private": "https://admin.hireflix.com/jobs/68b43e38b19cf131a17c543f/interview/6a4e5650d7604850f07dd77e",
        "public": "https://app.hireflix.com/tCDBFCpb2ncH"
      }
    }
  }
}

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.

​

Sending invitations from your own system

By default, Hireflix emails the candidate their invitation (if the position is configured to send notifications). If you want to send the invitation from your own system instead, for example from your ATS or with your own email templates, set disableNotifications: true. Hireflix then sends no notifications to the candidate.

mutation InviteCandidateWithoutNotifications {
  inviteCandidateToInterview(
    input: {
      positionId: "<position-id>"
      candidate: {
        email: "[e-mail]"
        firstName: "Jane"
        lastName: "Doe"
      }
      externalId: "YOUR_SYSTEM_ID"
      disableNotifications: true
    }
  ) {
    __typename
    ... on InterviewType {
      id
      urls {
        short
        public
      }
    }
  }
}

Take urls.short (or urls.public) from the response and include it in the message you send to the candidate. Without that link, the candidate has no way to reach the interview.

Add the error types from the full example above to your selection set as well, so you can handle cases like a candidate who was already invited.

​

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.