Whether you are a customer or partner of CodeSignal, you can use CodeSignal’s API and webhooks to build custom, direct integrations that can be as simple or as powerful as you need. CodeSignal provides a GraphQL API for exposing test, certification, and interview data that you can read and edit, and a set of webhooks to notify you of events. In this article, we’ll explain how you can use CodeSignal’s API and webhooks to automate and scale your workflow, from sending tests, to notifying or reminding candidates, to evaluating and analyzing results in bulk. (We’ll be referring often to our API documentation, so you might want to keep a copy handy!)
CodeSignal’s API vs ATS Integrations: What’s the Difference?
An ATS (applicant tracking system) like Greenhouse or Lever can automatically send and track CodeSignal assessments, keep your team on the same page with notifications, and give your organization tools for gathering and exploring data about your hiring funnel.
If you already use an ATS, integrating your ATS with CodeSignal should take care of most of your organization’s needs. But sometimes you might want to access data or receive notifications that aren’t covered by your ATS. Your ATS will tend to pull simple data from CodeSignal, like the candidate’s overall score, with a link to view the test in CodeSignal’s UI. But what if you want to get more details directly from CodeSignal to conduct sophisticated analytics, for example to bring certain aspects of candidate performance (like the languages tested) into your internal reporting? That’s where CodeSignal’s GraphQL API will come in handy, and make these types of queries really simple. And while your ATS will by default notify you when a CodeSignal Test or Certify result is “ready,” sometimes you might want to get notifications for the stages of progression along the way—for example, if you want to send a candidate a reminder when their test is started but not finished (and they’re nearing the time limit!). To listen for more complex statuses like these, you’ll need to use CodeSignal’s webhooks.
CodeSignal’s API and webhooks can also help your team build custom integrations in settings where a different system is used in place of a standard ATS—for example, in schools, which use specialized student management systems, or at large tech companies that have built their own custom internal ATS.
Also, if you are a productivity tool or recruiting platform with customers that use CodeSignal (for example, an interview scheduling service), you can use our API to develop a close integration between your service and CodeSignal. (Contact [email protected] if you want to become an integration partner.)
API Keys and Security
We know how important it is to protect your candidates’ personal information. Our webhook notifications are signed with a 256-bit hash of a secret key that you should always use to verify that the data came from our platform. We also use HTTPS/SSL and recommend that you do the same by providing an HTTPS endpoint URL for the webhook. Our GraphQL API keys, which are managed in your CodeSignal Admin page, should always be kept secret, and for security best practices can be configured with specific permissions to limit them to only the type of data they need to access.
To get started with CodeSignal’s API, you will need to make sure that you have API and webhooks enabled for your CodeSignal account (if you do, you will see an Integrations link in the dropdown under your profile). Contact [email protected] to learn more. Once enabled, you can visit the Integrations page and then select API Keys to create new keys.
Building with GraphQL
What is GraphQL?
Fun fact: the API we expose to read and edit your organization’s CodeSignal data is the same exact API our engineering team uses internally, so you can be sure that it’s developer-friendly and always up-to-date and well-maintained. We built our API in GraphQL, a query language developed by Facebook as an alternative to REST.
Just like traditional REST APIs, GraphQL specifies how to request data via HTTP and receive a formatted response (GraphQL returns JSON). Just like REST, GraphQL supports both data retrieval (via a Query) and data manipulation (via a Mutation). But the difference is that REST is based on the concept of a list of resources that have different endpoints, whereas GraphQL is based on the idea of a schema with relationships, accessed from a single endpoint. In our opinion, this design offers a superior developer experience, at least when it comes to the kinds of use cases our API supports.
With REST APIs, you often need to make multiple calls to different endpoints; in order to formulate your query, you first have to learn about how the data was structured internally by the API developer. But when developing with GraphQL, all you need to care about is the schema, which describes a hierarchy of data objects. You select into this nested data to ask the system for exactly what you need. In this way, GraphQL keeps payload sizes down and performance up, and makes it easy to modify and reuse queries.
Let’s say you want to add some of CodeSignal’s detailed testing data to a report about recent candidates at your company. With a REST API, you would need to make 5 queries to do something like the following:
- Look up a company test session
- Look up the company tests associated with that test session
- Look up the three tasks associated with the test session to fetch their titles and descriptions (you would need a separate query for each task)
With GraphQL, you can do all this in one single query. For example:
query {
companyTestSession(id: "YOUR_TEST_SESSION_ID") {
result {
score
solvedTaskCount
}
test {
id
title
}
tasks {
task {
title
description
}
}
}
}You can learn more about GraphQL here, or check out this primer that compares GraphQL to REST.
CodeSignal’s GraphQL Playground
You can read about the type of data you can query and edit through the schema definitions in our GraphQL documentation. Even better, you can explore the GraphQL API straight from your browser using our GraphQL Playground.
The GraphQL Playground is a shell for making API calls that run against CodeSignal’s live backend. You can use the Playground to inspect the schema, try out queries, and correct any syntax errors before incorporating those calls into your code (be aware if trying out any GraphQL Mutations that you will be editing production data!). Learn more about using CodeSignal’s Playground.
Querying data
At a high level, CodeSignal’s GraphQL library exposes the following kinds of data for querying:
- Tests, both standardized tests and tests created by your company, including what tasks (questions) it has, and an invitation URL to take the test.
- Test sessions, including the completion status, the time it was started and completed, what test it was, who was taking the test, and the results if available, with the overall score and list of results per task.
- Individual tasks within a test or test session, including the type of task, the text of the question, and the full answer given.
- All live interviews for a given candidate, including the status, the start and end time, the interview feedback (notes and score ratings) and a URL to access the live interview and replay.
- Company settings, such as your plan information and other configuration details with CodeSignal.
Example: Anonymizing interview notes
Let’s imagine that your organization uses CodeSignal Interview to conduct your technical interview process remotely. Candidates go through several interviews, and a hiring committee reviews the feedback and makes an objective decision. To help prevent bias, the hiring committee is composed of people who have never met the candidate, and don’t know their name, age, race, or gender.
One problem is that the interviewers’ notes, which are important for the committee to review, might contain some revealing information, such as gendered pronouns. To avoid this, you might want to write a script that strips your interviewers’ notes of potentially biasing information. For each candidate up for review, your script would grab all the live interview notes and apply an NLP engine (or rules-based heuristics) to the text that can anonymize certain identifying words (e.g. “she” becomes “they”). CodeSignal’s GraphQL API makes it easy to retrieve the notes from all live interviews with a candidate.
Example: Analyzing interview data
With CodeSignal’s API, it’s possible to gain more insight into your candidates, questions, and tests. By querying for results for a specific test, you could build a dashboard that shows how challenging your questions are based on how candidates score on average. You might use this data to adjust your questions and remove ones that appear to be either too easy or too challenging, or to compare your different tests (e.g. front-end skills assessments vs. backend skills assessments) to make sure that you don’t have any outliers in terms of how various candidate pools perform. If you store additional custom information about your candidates such as their years of experience or education level, you could bring in CodeSignal data to run a bulk analysis of different candidate profiles. These are just a few ideas, but we would love to hear more about how you use CodeSignal’s API (and please let us know if there is any data that isn’t currently exposed that you would like to pull into your reports or dashboards).
Creating and modifying data
At a high level, CodeSignal’s GraphQL library exposes the follow kinds of mutations:
- Creating and modifying tests
- Creating and modifying tasks for tests
- Creating and modifying live interviews
- Creating test sessions
- Creating certification requests
- Editing your company’s membership roles
Example: Integrating with your custom ATS
If your organization has its own in-house system (i.e., you don’t use an ATS that CodeSignal supports), you can use CodeSignal’s API to integrate our Test and Interview products with your backend and automate the busywork out of your processes.
For instance, when a recruiter passes someone to the technical interview stage, your system could automatically call CodeSignal’s createCompanyTestSession Mutation to create an interview; this could trigger an email to the candidate containing the link, in whatever way you’d like to present it. To update the candidate’s status in your system, you could listen for the companyTestSessionStarted and companyTestSessionFinished webhooks (more on these in the next section). Finally, when the test is finished, you could query for the companyTestSession’s source code, score, and languages, and save all of that information in your custom ATS for easy access and review later.
Building with Webhooks
A webhook is a common way to subscribe to event notifications from an app. When the event you’re interested in happens, CodeSignal (the webhook provider) will send an HTTP POST request to the URL endpoint that you specified (the webhook receiver), with a payload containing more information.
You might want to set up a CodeSignal webhook so that when an event occurs in our platform—for example, a candidate completing a skills test—you can automatically trigger a follow-up action on your end. For example, you could use webhooks to send a message to your recruiting team via Slack, or add the candidate’s results to an internal spreadsheet. You can set up webhooks programmatically using your own internal endpoints, or you can use a tool like Zapier to connect CodeSignal events to your apps.
Events
CodeSignal’s webhooks can notify you as candidates begin and complete testing and certification. To see more details about these event types, including sample payloads, you can view the full documentation here.
- companyTestSessionStarted: when a candidate started a test session.
- companyTestSessionFinished: when a candidate completed a test session.
- certificationResultPending: when a candidate finished a standardized test session where the results are autoshared with your company. This event lets you know that the test was completed while CodeSignal’s team is still working on the certification.
- certificationResultNotCertified: when CodeSignal’s team denies the certification (a list of reasons is provided).
- certificationResultShared: when CodeSignal’s team completes its certification and shares the results, or when a candidate shares results from a previous certification.
- certificationRequestExpired: when your request for a certification test result couldn’t be fulfilled within the expiration window.
- certificationRequestRejected: when the candidate explicitly rejected the certification request (either refused to take the test or to share existing certification results).
Integrating with apps
The options for building with webhooks are limited only by your imagination. One idea is to connect your webhook to a Slack workflow so that you can message your team as candidates progress through different stages of the interview, letting them know when they need to touch base. With a service like Zapier, you can connect CodeSignal webhook notifications to hundreds of applications that you might use to manage your hiring process—like Google Sheets, Gmail, Dropbox, Outlook, SendGrid, and many more—without having to write any code.
Configuring webhooks
To create new webhook receivers, visit the Manage Webhooks page (Integrations > Webhooks) in your CodeSignal admin account. See the documentation for complete information on how to configure your webhooks and check that they are active and healthy.
Conclusion
We hope that this article has inspired you to build rich integrations with CodeSignal that work seamlessly with the systems and apps you use every day. If you are an existing customer and want to enable the API and webhooks for your CodeSignal account, please ping customer success. If you are a potential or existing partner who wants to integrate your application or service with CodeSignal, please reach out to our partnership team—we’d love to hear what you have in mind.