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:
query FetchPositions- The keyword
querytells GraphQL you’re requesting data rather than changing it. FetchPositionsis 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.
- The keyword
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,
positionsreturns a list of Position objects (each representing a job).
{ 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 thePositiontype. - GraphQL only returns the fields you explicitly request: nothing more, nothing less. If you remove
tags, it disappears from the response.
- Inside the curly braces
Response structure for a query:
The shape of the response matches the query:- The top-level
datakey always wraps your requested fields. - Each object under
positionscontains exactly the fields you asked for. No hidden data or unused properties.
Example: Mutation
Move an interview to the shortlisted stage. Fill in aninterviewId in the Variables panel (if you followed the playground tutorial, you already have demo interviews to use):
Let’s break this down:
mutation ShortlistInterview($interviewId: ID!)- The keyword
mutationtells GraphQL you want to change data. For example, creating, updating, or deleting something. ShortlistInterviewis 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.
- The keyword
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 namedinput, which holds theinterviewId. - The way the arguments are structured is determined by the mutation field. Each mutation has a different set of input parameters.
- 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
idand its newstage.
- 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
... on InterviewType- Every Hireflix mutation returns a union type: the result is either the object you changed or an error.
shortlistInterviewreturns anInterviewTypeon success, or an error such asInterviewNotFoundError. - Because the API can’t know in advance which type you’ll get, you can’t request
iddirectly. 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".
- Every Hireflix mutation returns a union type: the result is either the object you changed or an error.
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 thisexternalId.
__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
errorsarray (for invalid queries, missing fields, or authentication problems).
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.

