Skip to main content

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.

Query

Goal: Fetch data without making changes.Examples: Listing positions or fetching interview results.

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

Example: Mutation

Move an interview to the shortlisted stage. Fill in an interviewId in the Variables panel (if you followed the playground tutorial, you already have demo interviews to use):
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:
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)
Response example (candidate already exists)

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.
Want to try more? The Hireflix Dev Playground lists every query and mutation from these docs under Examples in the left menu.