> ## 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: 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](#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](https://docs.hireflix.com/tech/quickstart.md) in the `headers`.

> [!WARNING]
>
> 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.

[https://cdn.hireflix.com/graphql-playground/index.html?query=InviteCandidateToInterview\&url=https://api.hireflix.com/me](https://cdn.hireflix.com/graphql-playground/index.html?query=InviteCandidateToInterview\&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. The full `InviteCandidateToInterview` mutation is reproduced below so you can read and reason about it directly.

```graphql theme={null}
mutation InviteCandidateToInterview {
  inviteCandidateToInterview(
    input: {
      candidate: {
        email: "jane.doe@example.com"
        firstName: "Jane"
        lastName: "Doe"
        phone: "+31495678066" # Optional
      }
      positionId: "<position-id>"
      externalId: "YOUR_SYSTEM_ID"
    }
  ) {
    __typename
    ... on InterviewType {
      id
      urls {
        private
        public
        short
      }
    }
    ... on InterviewAlreadyExistsInPositionError {
      code
      message
    }
    ... on ExceededInvitesThisPeriodError {
      code
      message
    }
    ... on InterviewExternalIdAlreadyExistsInPositionError {
      code
      message
    }
  }
}
```

* Replace `<position-id>` with a real position ID (see ["Fetching Positions"](https://docs.hireflix.com/tech/features/positions/fetching-positions.md) for how to obtain one).
* `candidate.phone` is optional, but if included must use full international format with a country code (e.g. `+1` for the US) or the invite fails.
* `externalId` is optional; use it to link the created interview back to a candidate record in your own system.
* `disableNotifications` is an optional `Boolean` on the input. If `true`, Hireflix sends no notifications to the candidate, so you must deliver the interview link (`urls.short` or `urls.public`) yourself. If `false` or omitted, notifications are sent only if the position is configured to send them.
* This mutation returns a **union type** — always request `__typename` and branch on it rather than assuming success. It resolves to `InterviewType` on success, or one of `InterviewAlreadyExistsInPositionError`, `ExceededInvitesThisPeriodError`, or `InterviewExternalIdAlreadyExistsInPositionError` on failure.
* `urls` (on `InterviewType`) — `public`/`short` are candidate-facing interview links, `private` is the admin link to view the interview in Hireflix.
* Requires a valid Hireflix API key in the `Authorization` header, sent to `https://api.hireflix.com/me`.

### Explanation

* **positionId** – the ID of the Hireflix position you want to invite the candidate to. You can find this ID by [fetching positions](https://docs.hireflix.com/tech/features/positions/fetching-positions.md).
* **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](#sending-invitations-from-your-own-system).
* **urls** – the generated candidate’s interview link (public, private, and short-hand url).

### Example Response

```json theme={null}
{
  "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"
      }
    }
  }
}
```

> [!NOTE]
>
> 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](https://docs.hireflix.com/tech/faqs/add-params-to-public-interview.md) 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**.

```graphql theme={null}
mutation InviteCandidateWithoutNotifications {
  inviteCandidateToInterview(
    input: {
      positionId: "<position-id>"
      candidate: {
        email: "jane.doe@example.com"
        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.

> [!NOTE]
>
> 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.

> [accordion] ✅ 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.
>
> ```graphql theme={null}
> mutation {
>
>   result1: inviteCandidateToInterview(input: {
>     positionId: "abc123"
>     candidate: { firstName: "Datta", email: "datta@example.com" }
>   }) {
>     ... on Interview { id }
>   }
>
>   result2: inviteCandidateToInterview(input: {
>     positionId: "abc123"
>     candidate: { firstName: "Datta2", email: "datta2@example.com" }
>   }) {
>     ... on Interview { id }
>   }
>
>   result3: inviteCandidateToInterview(input: {
>     positionId: "abc123"
>     candidate: { firstName: "Datta3", email: "datta3@example.com" }
>   }) {
>     ... 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**

> [card] [Learn next?](https://docs.hireflix.com/tech/features/interviews/creating-shareable-link.md)
>
> Let's learn how to create a shareable interview URL.


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