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

# Understanding GraphQL Basics

> Learn how the GraphQL query language works to interact with Hireflix.

## Overview

The Hireflix API is built using **GraphQL**, a modern query language for APIs. Unlike REST, GraphQL uses a single endpoint where you describe exactly what data you need — no more, no less.

In this tutorial, you’ll learn:

* The difference between **queries** and **mutations**
* Why every mutation returns a **union type**, and how to use `__typename`
* How to interpret **success and error responses**

## Queries vs. Mutations

In GraphQL, every request is either a **query** or a **mutation**.

> [card] Query
>
> **Goal:** Fetch data without making changes.
>
> **Examples:** Listing positions or fetching interview results.

> [card] Mutation
>
> **Goal:** Make changes to data.
>
> **Examples:** Inviting a candidate, archiving a position, or deleting an interview.

### Example: Query

Let's look at this example query, which fetches the positions in your account. Add your API key at the top of the playground and click **Play** to run it against your own account:

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

```graphql theme={null}
query FetchPositions {
  positions {
    id
    name
    tags
    archivedAtISO
  }
}
```

Here's what each part means:

1. `query FetchPositions`
   * The keyword `query` tells GraphQL you're requesting data rather than changing it.
   * `FetchPositions` is an operation name. You can think of it like a label for your query. It's optional but useful for debugging or when running multiple queries.
2. `positions`
   * This is the root field being requested from the Hireflix API.
   * Each GraphQL API defines a schema describing which root fields are available. In this case, `positions` returns a **list of Position objects** (each representing a job).
3. `{ id name tags archivedAtISO }`
   * Inside the curly braces `{ ... }` you specify exactly which fields you want to retrieve for each position. You can only request fields defined by the schema for the `Position` type.
   * GraphQL only returns the fields you explicitly request: nothing more, nothing less. If you remove `tags`, it disappears from the response.

### **Response structure for a query:**

The shape of the response matches the query:

* The top-level `data` key always wraps your requested fields.
* Each object under `positions` contains exactly the fields you asked for. No hidden data or unused properties.

```json theme={null}
{
  "data": {
    "positions": [
      { "id": "68d53cf0a3d3c03c50f103c3", "name": "Sales Manager", "tags": ["sales"], "archivedAtISO": null },
      { "id": "68d53cf0a3d3c03c50f103c4", "name": "Marketing Lead", "tags": [], "archivedAtISO": "2026-07-08T13:27:37.333Z" }
    ]
  }
}
```

### Example: Mutation

Move an interview to the shortlisted stage. Fill in an `interviewId` in the **Variables** panel (if you followed the [playground tutorial](https://cdn.hireflix.com/graphql-playground/index.html), you already have demo interviews to use):

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

```graphql theme={null}
mutation ShortlistInterview($interviewId: ID!) {
  shortlistInterview(input: {
    interviewId: $interviewId,
  }) {
    ... on InterviewType {
      id
      stage
    }
  }
}
```

Let's break this down:

1. `mutation ShortlistInterview($interviewId: ID!)`
   * The keyword `mutation` tells GraphQL you want to change data. For example, creating, updating, or deleting something.
   * `ShortlistInterview` is the **operation name** (optional, but helpful for identifying the mutation later).
   * `$interviewId: ID!` declares a **variable**. Its value comes from the **Variables** panel, so you can reuse the same mutation for different interviews. The `!` means it's required.
2. `shortlistInterview(...)`
   * This is the mutation field. Think of it as a function exposed by the API.
   * The parentheses `( ... )` contain the arguments the mutation expects. Here, it accepts a single argument named `input`, which holds the `interviewId`.
   * The way the arguments are structured is determined by the mutation field. Each mutation has a different set of input parameters.
3. Selection set (the `{ ... }` after the mutation)
   * This part defines what data you want back. Even when you're modifying data, you can decide what to return, just like a query. In this case, we want the interview `id` and its new `stage`.
4. `... on InterviewType`
   * Every Hireflix mutation returns a **union type**: the result is either the object you changed or an error. `shortlistInterview` returns an `InterviewType` on success, or an error such as `InterviewNotFoundError`.
   * Because the API can't know in advance which type you'll get, you can't request `id` directly. You wrap the fields in an **inline fragment** (`... on InterviewType`) that says "if the result is an interview, give me these fields".
   * Requesting the fields without the fragment fails with an error like `Cannot query field "id" on type "MutationShortlistInterviewResult"`.

### Example: Mutation With Error Handling

The mutation above only asks for the success type. In a real integration you also want to know **why** a mutation failed. You do this by adding a fragment for each error type you want to handle, plus the `__typename` field:

[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($positionId: String!) {
  inviteCandidateToInterview(
    input: {
      candidate: {
        email: "jane.doe@example.com"
        firstName: "Jane"
        lastName: "Doe"
        phone: "+31495678066" # Optional
      }
      positionId: $positionId
      externalId: "YOUR_SYSTEM_ID"
    }
  ) {
    __typename
    ... on InterviewType {
      id
      urls {
        private
        public
        short
      }
    }
    ... on InterviewAlreadyExistsInPositionError {
      code
      message
    }
    ... on ExceededInvitesThisPeriodError {
      code
      message
    }
    ... on InterviewExternalIdAlreadyExistsInPositionError {
      code
      message
    }
  }
}
```

This mutation can return one of several result types. The ones handled here are:

* `InterviewType`: success (interview created).
* `InterviewAlreadyExistsInPositionError`: candidate already invited.
* `ExceededInvitesThisPeriodError`: plan limit reached.
* `InterviewExternalIdAlreadyExistsInPositionError`: another interview in this position already uses this `externalId`.

You can determine which result you received by checking the `__typename` field, which is why most Hireflix examples include it. You don't have to add a fragment for every possible error type: if the result is a type you didn't add a fragment for, you only get back `__typename`. So **always request `__typename`**, or you can end up with an empty object and no way to tell what happened.

In GraphQL, even when a mutation fails, the API still returns an HTTP **200** response. Errors are instead reported in one of two ways:

* As an **error object** identified by its `__typename` (for expected failures like the ones above), or
* Through an `errors` array (for invalid queries, missing fields, or authentication problems).

Because of this, you should **not rely on HTTP status codes like 400** to detect errors. Always inspect the response body instead.

**Response example (success)**

```json theme={null}
{
  "data": {
    "inviteCandidateToInterview": {
      "__typename": "InterviewType",
      "id": "68d4164f19367e041b2030c0",
      "urls": {
        "public": "https://app.hireflix.com/HQ2oCyTN",
        "short": "https://hflx.io/c/HQ2oCyTN"
      }
    }
  }
}
```

**Response example (candidate already exists)**

```json theme={null}
{
  "data": {
    "inviteCandidateToInterview": {
      "__typename": "InterviewAlreadyExistsInPositionError",
      "code": 409,
      "message": "Candidate already invited to this position."
    }
  }
}
```

## Summary

* **Queries** → Fetch data.
* **Mutations** → Modify data.
* **Union types** → Every mutation returns either a success type or an error type. Use `... on <Type>` to request fields for each.
* `__typename` → Always request it to find out which type you received.

> [!TIP]
>
> Want to try more? The [Hireflix Dev Playground](https://cdn.hireflix.com/graphql-playground/index.html) lists every query and mutation from these docs under **Examples** in the left menu.


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