> ## 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.
# Overview
> Welcome to the Hireflix docs.
## Integration Overview
Before diving into specific API calls, it’s helpful to understand the typical workflow of integrating Hireflix into an Applicant Tracking System (ATS) or any other platform. This overview will outline the best practices at a high level, so you know where each part of the API fits into your integration.
Before you can invite candidates through the API, you first need to create positions in the [Hireflix Dashboard](https://admin.hireflix.com/en/jobs). A position represents a set of interview questions, settings, and branding that all invited candidates will see.
Once positions are set up, recruiters will want to invite candidates directly from their own interface. This usually happens through a button such as *‘Send Video Interview’* or as part of an automated workflow. For example, when a candidate moves into a specific stage of the recruitment pipeline.
Behind the scenes, your system makes an API call to Hireflix to trigger the invite. The API also supports bulk invites
After sending invites, recruiters need to track who has completed the interview and who is still pending.
* **Webhooks (recommended):** Subscribe to Hireflix webhooks to update candidate stage in real time (e.g., completed, shortlisted).
* **Polling (alternative):** If webhooks aren’t possible, periodically query the API for interview stage.
After a candidate completes their interview, you need to make the video responses available in your app. You can:
1. **Share a link:** Generate a public URL via the Hireflix API so recruiters can watch the recording without logging in.
2. **Embed or store videos:** Fetch video URLs (and transcripts) from the API to play them directly in your platform or save them to your own storage.
## Quickstart
Get your **API key** to start **using the Hireflix API** and learn **how to use a playground like Apollo Studio** for quick experimentation without writing any code.
Follow our three-step quickstart guide.
The Hireflix API is built using GraphQL, a modern query language for APIs.
## Workflow Guides
Explore the different features Hireflix offers.
Fetch, update, archive, or delete positions.
Invite candidates, fetch or score interviews, ...
Learn how you can react to Hireflix events.
## Frequent Questions
Yes, you can embed a Hireflix Interview using an iFrame, customize its appearance, listen for events like "interview\.finished", and even skip the intro screen for a seamless candidate experience.
When sending GraphQL requests through web-based clients or tools, the `query` field must be a **valid JSON string**. That means the entire GraphQL query must be on **one line**, and all double quotes `"` inside the query need to be **escaped** ( e.g., `\"`). This ensures the JSON remains valid and can be parsed correctly.
In Hireflix, each email can only be invited once per position. If you need to re-invite the same candidate, you must first delete the existing interview.
Yes, but it's not recommended. This makes the integration much more complex. It is better for interviews to be created in Hireflix since our whole UI is already optimized for integration with Hireflix.
Use the Hireflix API to retrieve recent account activity, such as user actions, timestamps, and IPs. The logs cover the last two months and can be paginated using skip and limit.
Learn how to pass candidate information (like name, email, or phone) through URL parameters in a Hireflix public interview link. This lets candidates skip manual input, which is ideal when redirecting them from your own form or onboarding flow.
Yes. You can search for candidates using the `interviewList` query on a specific position. This allows you to filter by email, name, and combine conditions using `AND/OR` logic. The response returns a list of interviews, and you can choose exactly which fields to retrieve (e.g., interview ID, candidate email, etc.).
**Yes.** You can manage users via GraphQL mutations, allowing you to add or remove company members programmatically.
**Add a User**
```
mutation {
Company {
Member {
add(email: "the-candidate-email")
}
}
}
```
**Remove a User**
```
mutation {
Company {
Member {
remove(id: "user-id-here", email: "the-candidate-email")
}
}
}
```
**Yes,** all requests must be **authenticated** using your **API key**. You can retrieve:
* All IP addresses used during the interview
* User agents
* Interview thumbnail links
**Yes.** You can retrieve a candidate’s geolocation data (derived from their IP address) through the API.
⚠️ **Important:**\
Location data is based on IP detection. If a candidate is using a **VPN or proxy**, the returned location may not reflect their real physical location.
In GraphQL, mutation queries always expect a return. For example, the [invite a candidate](/features/interviews/inviting-candidate) mutation fails if you don't specify return fields.
The Hireflix API follows the **GraphQL error model**, meaning requests always return an **HTTP 200 OK** response, even when an error occurs. Instead of relying on status codes, you should inspect either:
* The `errors` array (for most mutations and queries) or
* The `__typename` field (for union-type mutations that encode errors as types).
Usually, a **code 400** indicates a bad request and a **code 500** indicates an internal server error.
When integrating Hireflix inside an **iOS WebView (WKWebView)**, you may encounter one of the following issues:
* **“Open this on Safari”**
* **“Your camera or microphone is not working”**
These issues are related to how iOS handles WebViews and media permissions. Click on this card to learn more how to solve this issue.