Skip to main content

​
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. 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 status in real time (e.g., completed, shortlisted).
  • Polling (alternative): If webhooks aren’t possible, periodically query the API for interview status.
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.

Start here

Follow our three-step quickstart guide.

Understanding GraphQL Basics

The Hireflix API is built using GraphQL, a modern query language for APIs.

​
Workflow Guides

Explore the different features Hireflix offers.

Position Management

Fetch, update, archive, or delete positions.

Interview Management

Invite candidates, fetch or score interviews, …

Webhooks

Learn how you can react to Hireflix events.

​
Frequent Questions

Can I embed Hireflix on my website or app?

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.

How to Format GraphQL Queries as a One-Line Web Payload?

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.

Can I re-invite a candidate for a position?

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.

Can I allow my users to build interviews in my ATS instead of Hireflix?

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.

How can I fetch my account logs?

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.

How can I prefill parameters to public interview links?

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.

Is there a mutation to search for a candidate within my account?

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

Can I add or remove users programmatically through the API?

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")
    }
  }
}

Can I fetch the IP address, User Agent, and interview thumbnails through the API?

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

Can I retrieve a candidate’s location from their IP address using the API?

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.

I am getting an error "Field X of type Y must have a selection of subfields"

In GraphQL, mutation queries always expect a return. For example, the invite a candidate mutation fails if you don’t specify return fields.

Which errors does the Hireflix API return?

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.

I’m integrating Hireflix into my iOS app using a WebView. Why do I see errors like “Open this on Safari” or “Your camera or microphone is not working”?

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.