Integrate Hireflix with your ATS/system through our API

Updated 6 days 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.

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

• 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

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

Q3: Once an interview is completed by a candidate, how do I send back a link with the interview response to my ATS/system? I can't find the URL in the wehbook payload!

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

#And this below is an example of the payload you will receive 

{
  "data": {
    "Interview": {
      "share": {
        "externalLink": {
          "url": "https://shared.hireflix.com/interview/64790100-17c1-4eee-b016-b366d2abcb18"
        }
      }
    }
  }
}

(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?

Yes, I will put some examples below, although you can do it yourself > 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 on Hireflix as the URL where the wehbook will send the information. 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.

• interview.finish > triggers as soon as an interview is completed by a candidate
• interview.status-change > triggers as soon as the status of the interview changes, this could be because an interview has been completed, or it has been moved to Preselected or Discarded
• interview.create > triggers when a candidate is invited to an interview
• interview.delete > triggers when an interview is deleted
• interview.score-updated > triggers when the global score of a candidate is updated (Commenting on the candidate doesn't actually trigger this)

EXAMPLES

#THIS IS AN EXAMPLE OF THE INTERVIEW.FINISH RESPONSE. THIS EVENT TRIGGERS ONCE AN INTERVIEW IS FINALIZED
{
  "event": "interview.finish",
  "data": {
    "id": "643e972db7d39e63cf468844", #this is the ID of the interview
    "position": {
      "id": "63d00b73df403de202d97e73", #this is the ID of the position
      "name": "Graduate Program NYU"
    },
    "externalId": "eyJwYXJ0bmVySWQiOiI4YzRkZGY3NC0xZGI0LTRkNzktYTBmOC0xZWUzYWE3MzRsdLCJvcmdhbml6YXRpb25JZCI6IjY4MTEyYTMzLTViMGEtNDc0Zi05NTY5LTUxZGJiMWUwZTA4YiIsInVuaXF1ZUlkIjoiMjU5NTU1ZTItOWNmZi00OGRjLWJjODQtYTFlZDA5NTE0ZjIxIn0=",
    "status": "completed",
    "hash": "TgTZ88Fe",
    "createdAt": 1681823533373,
    "candidate": {
      "name": "Wayne Knight",
      "email": "wayne.knight@example.com",
      "phone": null
    },
    "score": {
      "value": null
    },
    "completed": 1683705149534,
    "deleted": null,
    "archived": null,
    "finalist": null,
    "answered": true,
    "thumbnail": "https://media.hireflix.com/5f3245ab1008ea4e503b49ff/answer/643e972db7d39e6a21468847/00001-thumbnail.png?Expires=1683705234384&Key-Pair-Id=APKAWC67OMKLN2YILG76&Signature=OoT4Mdi9TaFufnHylZYcxDyqR-ezzGuEt~C1XQzBSxj4Y2e-i-B-WnnzQb3jjnGdrnyNLvs7Pit-76M44KL~XKJe4CaZfy0HvbTGmMOVw6adESuQD5qJ5nucypd7tiisdggyB0Q6YyfYTUL179M5C3cxPdFcYOblSQzK-3d3YQorp~h4nU1zhz9yt5S7IjV1zDYqIVJFy3kThs596LiSD7Vx20CFi7is1NUFofI0Hp78onfbnqedIsEd8rLm4NdsFh0BcFqOHzym1qi1fsctwnRkA2iOAcBZrww3ZMkyhOIDGPk9NP1-1igvERCzYgvETJuj2HYZq7YDasVkxG5tA__",
    "url": {
      "public": "https://app.hireflix.com/TgTZ88Fe", #this is basically the link to take the interview as a candidate
      "short": "hflx.io/c/TgTZ88Fe",
      "private": "https://admin.hireflix.com/jobs/63d00b73df403de202d97e73/interview/643e972db7d39e63cf468844" #This is the link to access the candidate response in the hireflix admin. It needs autentication. Keep in mind this is not the shareable URL that is an open link... that shareable link you need to create using a mutation. 
    }
  },
  "date": 1683705149611
}

#THIS IS AN EXAMPLE OF THE INTERVIEW.CREATE PAYLOAD. IT IS WHAT GETS RETURNED AFTER AN INVITATION TO AN INTERVIEW IS MADE

{
  "event": "interview.create",
  "data": {
    "id": "645b4dbceasas62c007dcbdb6",
    "position": {
      "id": "63d00b73df4asasase202d97e74",
      "name": "Chief Technology Officer"
    },
    "externalId": null,
    "status": "pending",
    "hash": "ItZ9V0pK",
    "createdAt": 1683705276776,
    "candidate": {
      "name": "Antonio Webhook ",
      "email": "antonio+webhook@hireflix.com",
      "phone": null
    },
    "score": {
      "value": null
    },
    "completed": null,
    "deleted": null,
    "archived": null,
    "finalist": null,
    "answered": false,
    "thumbnail": null,
    "url": {
      "public": "https://app.hireflix.com/ItZ9V0pK",  #this is basically the link to take the interview as a candidate
      "short": "hflx.io/c/ItZ9V0pK",
      "private": "https://admin.hireflix.com/jobs/63d00b73df4asasase202d97e74/interview/645b4dbcea4462c007dcbdb6" #This is the link to access the candidate response in the hireflix admin. It needs autentication. Keep in mind this is not the shareable URL that is an open link... that shareable link you need to create using a mutation. 
    }
  },
  "date": 1683705276846
}

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

Q10: What if I want to show the actual videos of the candidate responses on my ATS/system instead of a link? 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. 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)

• Teamtailor: https://www.loom.com/share/3d120ca9dca04745b300c4045c470121
• Recruitee: https://www.loom.com/share/f6bd54a8df5c43e0abf3943171ea91c3
• SmartRecruiters: https://www.loom.com/share/514e87338334445db21226a2cc81c815
• Greenhouse: https://www.loom.com/share/9b221352873245a7a1e369bee254709c
• Workable: https://www.loom.com/share/8e7091f1d172417c8f846ea318a1b155
• JazzHR: https://www.loom.com/share/4d1aa981eae64db186122385cfffb48f

Integrations where JOB <> INTERVIEW matching happens on Hireflix side

• BambooHR: https://www.loom.com/share/a7f8c9a787fa406eb2e2f6913ebb5048
• Lever: https://www.loom.com/share/c2a6b4beb34c47c593437698cd27ec9b

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:

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.

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

Q18: How can I fetch the completed interviews from a specific position?

First of all, in Hireflix interviews can be in one of 4 stages.

• invited (means they have not answered yet). This is called "pending" on the API
• to evaluate (they answered). This is called "completed" on the API
• shortlisted (they answered). This is called "finalist" on the API
• discarded (they answered). This is called "archived" on the API

If you want to fetch the ones that have completed the interview, then you will have to fetch the ones in completed, finalist and archived stages.

See below a query that fetches the interview ID's of all interviews in the shortlisted stage (called "finalist" in the API). You can do the same for the rest of the stages.

            query{
              position(id:"#HERE YOUR POSITION ID"){
                paginatedInterviews(
                  pagination:{limit:50} #you could put any other limit here
                  status:finalist
                )
                {
                  results{
                    id
                    status
                  }
                }
              }
            }

Q18: How can I fetch a list of all my candidate notification templates and their ID's?

You can fetch the list of templates and their ID by using the query below 😊🙏. In the query below we are fetching the email ones.

query {
  Template(type: "email") {
    list {
      id
      name
    }
  }
}

Q19: I am actually showing the video URL directly on my ATS once an interview is completed. How can I make it so that the video is playable directly from my system?

You just need to put the URL of the video in a HTML video tag <video src=heretheURL />.

Useful queries and mutations you will need in order to allow your users to invite candidates to a Hireflix Interview from your ATS and then see the responses once the interview is finalized.

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. Usually only positions that are OPEN are the ones that makes sense to be displayed on the ATS. 

3. Invite a candidate to a Hireflix Interview

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

4. Once you have received the interview.finish webhook, create a Shareable link for the interview so you can include it in your system

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?

Related Articles

• Example of Video Interview done with Hireflix
• Integrating Hireflix with Greenhouse: Setup and guide
• Connect with 1500+ apps through Zapier