Integrate Hireflix with your ATS/system through our API

Updated 2 weeks ago by Antonio

Our GraphQL API is open and allows you to do everything. You can build an integration as deep or as quick as needed. The GraphQL API self-describes and is very easy to understand.

API Information

To see all the methods of our API, load https://api.hireflix.com in your browser. This will open a GraphQL Playground, where you can discover the different endpoints available and their documentation. The Playground will open 3 tabs, each describing our APIs and what they do, and how to authenticate them.

https://api.hireflix.com/ - Used to login, register [This is public-facing so GraphQLBin can instrospect it without authentication]

https://api.hireflix.com/interview - Used to submit interviews by candidates [This is public-facing so GraphQLBin can instrospect it without authentication]

https://api.hireflix.com/me - Used to manage your Hireflix company account [This is a private API that is only accessible once you use the correct Bearer authentication headers or an API Key. Graphqlbin.com won't introspect this unless you are logged in]

Steps to access the /me API (needs API key):

  • Register for free in hireflix.com. Once logged into your Hireflix account, create an API Key  https://admin.hireflix.com/en/my-account/api-keys
  • Include the API Key generated on the headers by clicking "HTTP Headers" on the tab below in the playground and substituting the "here-goes-the-api-key" (see on image below) string with the API key you copied:
  • If the API Key has been introduced correctly, the GraphQL documentation should appear like on the right hand sidde when you click on "Docs" like below

How to send a GraphQL Request programmatically to our API.

Regardless of the programming language you use, in order to make a GraphQL Request to our API, you have to issue an HTTP POST request with a JSON payload to https://api.hireflix.com/me

The content of the JSON payload must be the following:

{
  
"query": “the GraphQL query or mutation goes here as an inlined string"
 
}

Here you can find useful information on how to do this

FAQS

Q1: How do usual integrations work?

Step 1: your user will trigger invitations to the Hireflix interview from your ATS/system (ideally your system should support both individual and bulk invites).

  • This is usually done by selecting the candidate/s then clicking "Send Assessment" then a popup appears where the user can select which interview to send to those candidates. The list displays all open interviews (we call them positions) in Hireflix which you can fetch by calling our API
  • An alternative is to automatically trigger the invite when a candidate in a job Y is moved to a stage X. For this method you need to first have a way to assign a particular interview to a particular stage in that particular job. This allows for more automation but is usually more complex to implement unless your ATS/system already supports this
You just need to send us the name and email. We then handle all the invitation emails, reminders etc. Those can actually be configured by your users in Hireflix so you don't have to worry about it. If you didn't want your candidate's names and emails to be known from Hireflix, you could even send a dummy email-name as long as you can then track back the real name-email back in your platform. Of course for that approach we wouldn't be able to send invite emails and reminders etc.

Step 2: once the candidate has completed their interview you can then send a link back to your ATS/system with the full recorded interview so that it is copied on your candidate's profile. Your user will then be able to click the link and watch the interview without the need of logging anywhere.

Q2: How do I send/invite a candidate to an interview?

In our API the concept of "Interview" is the set of questions and answers that a candidate has completed or will complete for a specific Position. Using the API, given a Position (specified by the position id), you can invite a candidate to a Hireflix Interview using the Position => invite mutation.

The returning payload will show you a list of URLs that you can share with the candidate. Both the public URL and the short URL can be used by the candidate to take the interview.

mutation {
  Position(id: "623c66b61df8a64c6648f702") {
    invite(candidate: { name: "Daniel", email: "daniel@hireflix.com" }) {
      id
      url {
        public
        short
      }
    }
  }
}

The returned payload is something like this:
{
  "data": {
    "Position": {
      "invite": {
        "id": "6245f73243204affdfe27774",
        "url": {
          "public": "https://app.hireflix.com/_mpmxxxxxk",
          "short": "hflx.io/c/_mpmIW5k"
        }
      }
    }
  }
}

The link you need to use is the shareable link and it needs to be "created" for each interview using the "share" mutation

mutation {
  	Interview(id:"your-interview-id") {
    		share(durationInDays: 100) { // Sets for how many days the link will be valid
     			externalLink {
       				url // This is the URL of the newly created Shareable link. Prompt this URL to your users on your system so they can easily watch an interview without having to log in
      			}
    		}
  	}
}
The "share" mutation has an argument called durationInDays, which by default is set to 75 days. You can override it with any value. For security and usability, it is important to chose the right approach how to display these links on your ATS/system.

(Preferred approach) Generate a moderately long lived link dynamically every time someone in your ATS/system clicks on the "View Interview" button. This is safe because the links will eventually expire, but it is also user friendly enough because if you wanna share the candidate response with someone by sharing the link, you will be able to do so for some days without any issues.

Generate a moderately long lived link once, and also provide the admin link which never expires: Some platforms that can't change the link dynamically what they do is they paste on the candidate profile both the shareable link that expires in 75 days for easy access without login... and ALSO show the admin link which never expires but does require the user to be logged in in Hireflix to view the interview.

We do not suggest creating a very long lasting link and using that one... because it could pose a privacy risk if it gets leaked.

Q4: For webhooks, do you have documentation somewhere that outlines how webhook payloads back to the ATS/system (to notify us about interview events) works?

Go to admin.hireflix.com => Account => Webhooks, create a webhook with all the events available (see picture below) and as the URL, then go to webhook.site, create a temporary URL and set it. Save the webhook and then create an interview, complete it, move it between funnels using our frontend, and finally delete it. This way when you go back to webhook.site you will see the payload of each webhook.

If you want to validate if a webhook comes from Hireflix, I have put together documentation here on how to do so.

Q5: For embedding-iframe use cases, can I customize the look of the interview UI?

One you have created the interview link through the API, you can use some parameters to modify how the interview looks. Removing borders etc will allow you to more easily embed it on your app.

  • primaryColor: (hex color, without #) changes the color of the primary button 
  • buttonRadius: (hex color, without #) changes the curvature radius of the buttons
  • backgroundColor: (hex color, without #) changes the background color
  • simple: (true o false). True eliminates the background etc... making it easier to embed without changing the design etc.

E.g: https://app.hireflix.com/(HERE is the interview ID)?buttonRadius=5&simple=true&primaryColor=5dbfd1&backgroundColor=ffffff

Q6: Can there be more than one interview per position? It seems like that's possible but I can't figure how to create that setup in the Hireflix UI

A position is actually the set of questions the employer is asking and its configurations. An interview is actually each individual object that represents a candidate being invited to and taking the interview/questions for the position. Hence you can have for instance the position "Sales Manager" and then create N invitations for N candidates to that position yes.

In order to invite a candidate you use the position. In GraphQL there is a mutation called "invite" under the "Position" object (Position => invite) as explained previously.

Q7: Can an interview be deleted in case I need to invite the same candidate with same email again?

In Hireflix you can only invite one email to 1 position once. However if you delete the interview then you can of course invite that same email to the same position again. The "delete" mutation under "InterviewNestedMutation" deletes an Interview and this will allow you to invite the candidate again to the same position

Q9: What are the statuses that come through in the interview.status-change webhook?

The status that come are:

  • "archived" - this is the same as "discarded" an interview through our UI
  • "finalist" - this is the same as "preselected" an interview through our UI
  • "completed" - this is the same as the "to evaluate" stage which is the default stage where interviews go as soon as they are completed

The interview object that you can query using our API, returns a list of questions, each one with an answer. The answer object includes the URL of the video answer. For security reasons, this URL is a pre-signed URL, which means that it is short lived and after a while, it will expire and the video will not be able available anymore. For this reason is it advised to NOT save the URL on a database or other persistence mechanism, and instead, always query our API to retrieve the URL. Our system will always return a non-expired and ready-to-use URL for you.

For example, if you want to display interview videos on your frontend, every time a user loads the interview videos screen, your software will have to call our API to retrieve a fresh URL for each answer.

Q11: Can I allow my users to build interviews in my ATS/system instead of having to build them in Hireflix?

Answer here is yes, it can be done however it is not suggested since it makes the integration more complex. It is better for interviews to be created in Hireflix since our whole UX/UI is optimized already for that. Having said that if you did wanted to build this capability, please contact us.

Q12: What if I want to automatically store the candidate responses in my own server? How do I do that?

The interview object that you can query using our API, returns a list of questions, each one with an answer. The answer object includes the URL of the video answer. You can use that URL to download the video answer to your system. Be aware that as mentioned in Q10, URLs expire, so make sure to always retrieve a fresh URL from our API (in case you need to download the video again, or for other reasons)

Q13: Do you have examples of how the integration works already in some of the ATS's you integrated with? Also some general info about what Hireflix does?

Overall video explaining the value of Hireflix: https://www.loom.com/share/5560eeb24c03495bae651382852d060f

Overall video explaining how to create a Hireflix account and the platform features: https://www.loom.com/share/405f2a0f9de845798ab860b791939be3

Integrations where JOB <> INTERVIEW matching happens on ATS side (This is the recommended approach)

Integrations where JOB <> INTERVIEW matching happens on Hireflix side

Q14: I have an ATS I want to integrate Hireflix on my ATS so that invites can be triggered from my ATS and the completed interview is also shown on my ATS. What are the steps?

  1. Go to Hireflix => Your account => API Keys and create or copy an existing API Key to your clipboard
  2. Load our API Playground and Docs by opening https://api.hireflix.com in a web browser
  3. Here you will see three tabs open, go to the Administration API tab, and on the very bottom of the screen, open the "HTTP Headers" tab. Replace "your-api-key-goes-here” with your API Key.

This will have your GraphQL Playground set up to test our API.

Q15: I have an ATS I want to integrate Hireflix on my ATS so that invites can be triggered from my ATS and the completed interview is also shown on my ATS. What are the steps?

  1. Go to Hireflix => Your account => API Keys and create or copy an existing API Key to your clipboard
  2. Load our API Playground and Docs by opening https://api.hireflix.com in a web browser
  3. Here you will see three tabs open, go to the Administration API tab, and on the very bottom of the screen, open the "HTTP Headers" tab. Replace "your-api-key-goes-here” with your API Key.

Q16: Can I know the length of an interview response through the API?

Our API currently reports duration for individual videos of each interview. See the following GraphQL query:

{
  position(id: "position-id") {
    id
    paginatedInterviews(pagination: { limit: 1 }, status: completed) {
      count
      total
      lastCursor
      results {
        questions {
          answer {
            meta {
              duration // <===== Here the duration of the answer
            }
          }
        }
      }
    }
  }
}

Q17: Can I fetch the answer transcription from the API?

Yes you can. See below a query that fetches the transcription for a specific interview. Keep in mind that if the interview has 3 questions for instance, the transcript for each answer will come separately.

{
  interview(id: "HERE THE INTERVIEW ID") {
    questions {
      answer {
        transcription {
          languageCode
          text
        }
      }
    }
  }
}

Useful queries and mutations you will need in order to allow your users to invite candidates to a Hireflix Interview

1. Create an interview.finish webhook for your client so your system can receive interview.finish events whenever a candidate completes an interview

I suggest you doing this right after the client gives you their API KEY as part of the setup process.

For development purposes you can use the URL generated after loading https://webhook.site on your browser. It will let you see the full payload of the webhook.

mutation {
   	Webhooks {
    		create(url: "https://your-callback-url", events: ["interview.finish"])
   	}
}

2. Fetch a list of positions:

query {
	positions {
    		id
  		name
		// Here you can add any other property you are interested in. Remember to check the available fields in the Docs tab in the GraphQL Playground
  	}
}

You can then, present your users with a list of positions to choose from.

3. Invite a candidate to a Hireflix Interview

mutation {
  	Position(id: "the-position-id") {
    		invite(candidate: { email: “the-candidate-email”, name: “the-candidate-name"})
  	}
}

mutation {
  	Interview(id:"your-interview-id") {
    		share(durationInDays: 75) { // Remember you can change the duration in days a Shareable link is valid
     			externalLink {
       				url // This is the URL of the newly created Shareable link. Prompt this URL to your users on your system so they can easily watch an interview without having to log in
      			}
    		}
  	}
}

How did we do?

Powered by HelpDocs (opens in a new tab)