> ## Documentation Index
> Fetch the complete documentation index at: https://hireflixsl.mintlify.site/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 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](/quickstart) 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.
</Warning>

<iframe src="https://cdn.hireflix.com/graphql-playground/index.html?query=InviteCandidateToInterview&url=https://api.hireflix.com/me" width="100%" height="750" />

### Explanation

* **positionId** – the ID of the Hireflix position you want to invite the candidate to. You can find this ID by [fetching positions](/features/positions/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.
* **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"
      }
    }
  }
}
```

<Info>
  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](/faqs/add-params-to-public-interview) explains how to do this.
</Info>

### 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 title="✅ 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**
</Accordion>

<Card color="#5863ff" icon="arrow-right" horizontal href="/features/interviews/creating-shareable-link" title="Learn next?">
  Let's learn how to create a shareable interview URL.
</Card>