How can we help? 👋

Byteboard Lever Integration Setup

Complete the step-by-step guide here to ensure your Lever integration is set up successfully.


The Byteboard-Lever ATS integration will take care of the following parts of the candidate lifecycle:

  • You can invite candidates to take a Byteboard interview directly from Lever
  • You can review a candidate’s Byteboard results directly from Lever
  • You will not need to visit client.byteboard.dev/ to input candidate outcomes (Next Steps and Offer Status), which allows our team to seamlessly recalibrate your candidate ratings and offer you metrics on your hiring process with Byteboard
 
ℹ️
Even if your account is integrated with the Lever Applicant Tracking System (ATS), you can still send Byteboard interview invites and manage candidate outcomes data from client.byteboard.dev/ at any time. However, please be cautioned that any Byteboard interviews that aren’t initiated in Lever won't be tracked in Lever or otherwise connected to a Lever candidate record.
 

The following document outlines the steps for setting up your integration between Lever and Byteboard. It covers the following high level steps:

This guide is written to allow for a self-service Byteboard-Lever integration setup; please follow the steps outlined below to complete the Byteboard-Lever integration.

 
📤
If at any point you’d like to walk through the setup steps with the Byteboard team, please reach out to CS@byteboard.dev. We will work together to get you set up as quickly as possible!

Before you Begin

In order to set up the integration, you will need the following permissions:

  • Super Admin permissions in your Lever instance
  • Admin permissions in your Byteboard instance

First Enable The Lever Integration

To start, have a Byteboard admin visit the the Team Settings page of the Byteboard client dashboard to enable your integration.

  • Toggle the Lever Integration button ‘on’ to begin.
Notion image
‼️
Note: You will need to be a Lever Super Admin (user role permissions level in Lever) to enable the integration on the Lever side and complete the steps below.

1. Create & Upload Your API keys

📖
You will be setting up two API keys in Lever for Byteboard, one with just the permissions needed for initial setup, and the other with a reduced number of permissions. Once we are done with setup you can delete the ‘initial setup’ API key in your Lever instance.
 

Follow the instructions here to set up both an 1) Initial Setup API key and a 2) Permanent API key, including the permissions listed for each in the sections immediately below.

  • As a Super Admin user in Lever, navigate to Settings —> Integrations and API —> API Credentials
  • Click Generate New Key in the Lever API credentials section to create each of the needed API Keys outlined before
Notion image
🔒
More on Data Permissions: the Setup API Key allows our team to pull information needed for the various parts of the integration to work. For example, list stages allows us to identify what ID is used by Lever to represent the interview stage you use for “Byteboard”. The Permanent API Key allows our team to send interview invites to candidates and update Lever with the candidate’s Byteboard results when they are done.

a) Create API Key 1 — Initial Setup API Key [in Lever]

  1. Make sure to include all of the listed READ and WRITE permissions below to ensure correct integration functionality (by clicking the related checkboxes in the endpoints sections):
      • READ Endpoints Permissions
      • WRITE Endpoints Permissions
      Expand here for example screenshot of selecting API Key Permissions
      *Note — not all required permissions for the Setup API Key are displayed in the screenshot above
      *Note — not all required permissions for the Setup API Key are displayed in the screenshot above
 
🛑
Stop and check! Before you fully submit the page to create the Setup API Key, make sure to copy the full Setup API Key (screenshot below) and store it in a safe location on your device. You will need the setup API key for the next step (Step 2). *Note that you will not be able to access the full API key again once it’s been created.
Click
Click Copy Key to copy the Setup API Key and store it elsewhere before moving on to the next step
 

b) Create API Key 2 — Permanent API Key [in Lever]

  1. Make sure to include all of the listed READ and WRITE permissions below to ensure correct integration functionality:
      • READ Endpoints Permissions
      • WRITE Endpoints Permissions
      Expand here for example screenshot of selecting API Key Permissions
      *Note — not all required permissions for Permanent API Key are displayed in the screenshot above
      *Note — not all required permissions for Permanent API Key are displayed in the screenshot above
       
      🛑
      Stop and check! Before you fully submit the page to create the Permanent API Key, make sure to copy the full Permanent API Key (screenshot below) and store it in a safe location on your device. You will need to submit the full Permanent API key in your Byteboard portal. *Note that you will not be able to access the full API key again once it’s been created.
      Click
      Click Copy Key to copy the Permanent API Key and store it elsewhere before moving on to the next step
 

2. Once you’ve added all the permissions listed above, click DONE at the bottom of the page to save and create the API Key.

  • Toggle On the ‘Allow access to confidential data’ if you would like to give this API Key access to confidential job postings, opportunities, and requisitions in your Lever instance. Otherwise, you can leave this toggled Off.
Notion image
 

3. Once API key creation is completed in Lever, add your permanent API key to the team settings page in the Byteboard portal in the permanent key box in Step 1 and click Submit.

Notion image
 

2. Configure Stage Changes and Archive Reasons

a) Configure Stages

  1. Click the ‘Configure Stages’ button on the team settings page under the Configure Archive Reasons and State Changes heading.
    1. Notion image
  1. Upload your Setup API key from step 1 and click Submit.
      • *Please still keep this key saved for step 2b (Configure Archive Reasons)
      • You will then be directed to match your company’s Lever stages to the appropriate Byteboard Stages.
      Notion image
  1. Select the Lever Stages that should be mapped to the stages listed below and once an option is selected for each, click Map Stages:
      • Byteboard: The stage you would like to send a Byteboard interview at
        • i.e., once a candidate is sent to this Stage in Lever, they’ll be sent a Byteboard interview invitation through the Lever integration
      • Onsite: The stage after the Byteboard interview in your process
        • i.e., the stage that indicates the candidate moved forward in your interview process post Byteboard, even if your org does not label this as “onsite interview”
      • Offer: The stage that indicates a candidate received an offer
      Expand here for example screenshot of the completed Lever stage mappings
      *Note — the stage names in your Lever instance will likely be different from the examples here
      *Note — the stage names in your Lever instance will likely be different from the examples here
       
      ℹ️
      *Note that all three of these stages must be mapped in order for your Lever integration to be successfully completed. Only one value can be selected for each, and a Lever stage can only be mapped to one Byteboard stage.
      📤
      If your internal stages do not align with the options presented, please feel free to reach out to Byteboard at CS@byteboard.dev for recommended stage mapping.
      💡
      If the stages in your Lever instance change in the future, you can click back into the the ‘Configure Stages’ button on the team settings page, re-enter the Setup API Key (or create a new one), and click Edit to re-map the stages to Byteboard as needed. Once the changes are applied, click Map Stages again to save the new mappings.

b) Configure Archive Reasons

  1. Click the ‘Configure Archive Reasons’ button on the team settings page under the Configure Archive Reasons and State Changes heading.
    1. Notion image
  1. Upload your Setup API key from step 1 again and click Submit.
      • You will then be directed to match your company’s Lever archive reasons to the appropriate Byteboard Archive Reason.
      Notion image
  1. Select the Byteboard Offer Status option that should be mapped to each of the Lever Archive Reasons stages by clicking the arrow next to that Archive Reason and selecting the appropriate value
      • E.g., if a candidate is archived in Lever with the reason ‘Underqualified’, you may choose to map that value to the Byteboard ‘Rejected’ value for the candidate’s Offer Status
      • Map sure that each of the archive reasons has been mapped (they save automatically once an option is selected) before clicking out of the Lever Archive Reasons page
      ℹ️
      *Note that all relevant Archive Reasons must be mapped in order for your Lever integration to be successfully completed. Only one value can be selected for each.
      💡
      Your candidates’ Byteboard Offer Status data will begin to populate automatically via the integration for future candidates once they are archived in Lever
      Expand here for example screenshot of the completed Lever Archive Reasons mappings
      *Note — the archive reasons used in your Lever instance may be different from the examples here
      *Note — the archive reasons used in your Lever instance may be different from the examples here
 

The following chart shows some common archive reasons that are utilized in Lever:

Byteboard Lever Integration Field
Lever Archive Reason Examples
Rejected
Not a fit, Underqualified, Preferred another candidate, Overqualified, Keep for future opportunities, Motivations Misalignment, Misaligned values, Plagiarism, Junior for role
Withdrew
Withdrew
Offer Accepted
Hired
Offer Declined
Offer declined, accepted another offer
Not Applicable
Duplicate application, Unresponsive, Timing, Position closed, Location, Visa Status, Better for another role, Compensation Misalignment, Expired, Distance

3. Set Up Web Hooks

Follow the instructions here and complete the steps below to set up the two web hooks needed for this integration:

ℹ️
The web hooks allow Lever to send requests to Byteboard when certain actions are taken by you. For example, when you put a candidate in the “Byteboard” stage on Lever, Lever sends us a leverStageChange event so that we know to send an Byteboard interview invitation to the candidate.
 
  1. As a Super Admin user in Lever, navigate to Settings —> Integrations and API —> WEBHOOKS:
    1. Notion image
  1. Create one web hook for the Candidate State Change event (leverStageChange)
      • A. Toggle on the Candidate State Change event and click + Add webhook
      • B. Copy the State Change web hook URL from the Byteboard portal by clicking the Page icon next to it
      • C. Paste the Stage Change URL from the Byteboard Team Settings page (step 3 in Lever setup) directly into the Lever URL box
      • D. Copy the Signature token for the State Change web hook and store it in a secure place
        • ℹ️
          *You will need the signature token for this web hook to use in step 5 below
      Notion image
  1. Create one web hook for the Candidate Archive State Change event (leverArchiveChange)
      • A. Toggle on the Candidate Archive State Change event and click + Add webhook in that section
      • B. Copy the Archive Change web hook URL from the Byteboard portal by clicking the page icon next to it
      • C. Paste the Archive Change URL from the Byteboard Team Settings page (step 3 in Lever setup) directly into the Lever URL box
      • D. Copy the Signature token for the Archive Change web hook and store it in a secure place
        • ℹ️
          *You will need the signature token for this web hook to use in step 5 below
      Notion image
 
🚧
NOTE: If you try to test the connection after setting up the web hooks (by clicking Verify Connection in Lever on the web hook page), the request will fail. This is expected and does not mean your integration does not work.

4. Set Up Byteboard Tags

ℹ️
Candidate Tags tell the integration what kind of Byteboard interview (e.g., Senior SWE, Junior Web, etc.) that you would like a specific candidate to receive. Each tag
  1. Visit the team settings page of the Byteboard client dashboard to find Your Tags under Lever integration.
    1. Notion image
  1. Add these tags to a candidate record in Lever, starting with a test candidate if you would like.
    1. To do so, click the paper icon (copy) next to the desired Byteboard interview type to the right, and paste it as a tag on the candidate record in Lever
    2. 💡
      You must ensure that these tags are used for all candidates that you are inviting to take Byteboard through Lever or we cannot identify which interview type to send them. Once you’ve added a tag to at least one candidate in Lever, the tags should auto-populate for future candidates you’d like to invite to the same interview type!
      🏆
      A candidate must first be tagged BEFORE being moved into the Lever stage that is mapped to Byteboard, or else the Byteboard interview invite won’t send correctly.
      💡
      If you add new Byteboard Interview Types to your account at any point, visit the team settings page in your portal to copy over the new tag to Lever for use. Note that these tags are case sensitive and must match exactly how they are in the portal.

5. Upload Your Signing Tokens

ℹ️
The signing token is used to verify that a request really originated in Lever. This ensures that a third party cannot attempt to use the web hook urls to send invitations on your behalf.
  1. Follow the instructions here to generate signing tokens and copy them.
      • You will need to generate one for each web hook (stage change and archive reason)
      • Reference step 3 above (creating the web hooks) to see where you can access the signature tokens and copy them over from in Lever
  1. Upload your tokens to the team settings page under Upload Your Signing Tokens:
      • Once you’ve copied and pasted the two signature tokens, click Submit to save them
        • Notion image
      ℹ️
      Note, the portal will indicate once you’ve already submitted your signing tokens!

Testing the Lever Integration

Follow these steps below to send a test candidate Byteboard interview from your Lever instance and view the end-to-end data that is transmitted via the integration:

 
  1. Create a test candidate in Lever using the email of your Byteboard representative.
      • Using the Byteboard team member’s email address ensures that we can “take the interview” and grade it according to complete the test
  1. Apply a tag from the Setup Byteboard Tags section of your Byteboard Team Settings page to the test candidate record in Lever
      • *You can use the corresponding tag for any of the Interview Types you have set up in your Byteboard account
      • The tag MUST be applied to the candidate before moving on to step 3 below
  1. Move the candidate to the Byteboard stage.
      • This is the stage in your Lever instance that you mapped to correspond with sending the Byteboard interview invites.
  1. Verify that there is a note in the Byteboard stage in the Lever UI indicating that the invite was sent.
    1. *This note will appear on the Lever candidate record — expand below for example image
      Notion image
  1. Your Byteboard representative will verify once the test candidate was processed correctly.
      • This includes “taking the test interview” and “grading the test interview”
  1. Verify that there is a note in the Byteboard stage in the Lever UI with the candidate’s finalization information.
    1. *This note will appear on the Lever candidate record — expand below for example image
      Example note on candidate record in Lever — the URL leads to the candidate’s graded Byteboard Interview and Skills Report
      Example note on candidate record in Lever — the URL leads to the candidate’s graded Byteboard Interview and Skills Report
  1. Move the test candidate to the onsite stage in Lever.
      • This should be the stage that was mapped to correspond with Byteboard’s Onsite option for candidate Next Steps
  1. Reject the test candidate in Lever.
      • Select an Archive Reason that was mapped to a corresponding Offer Status option in your Byteboard portal.
  1. Your Byteboard representative will verify that the candidate’s next steps and offer status were updated and set correctly according to the integration configuration.
  1. Once the integration test is verified, reach out to your Byteboard representative if you’d like the test candidate record to be removed from your Byteboard portal.

Cleanup [optional]

  1. Delete the Setup API Key [recommended, but optional]
      • Once your Lever integration setup is complete and your Byteboard representative has verified that everything is working as expected, you can delete the Setup API key in your Lever instance (the key with the setup permissions)
        • 💡
          If the stages in your Lever instance change in the future, click back into the the ‘Configure Stages’ button on the team settings page. If you deleted your original Setup API Key, create a new one following Step 1a above, and submit it to access the View Lever Stages page. Then click Edit at the bottom of the screen to re-map the stages to Byteboard as needed. Once the changes are applied, click Map Stages again to save the new mappings.
      Notion image

How to send a Byteboard Interview invite from Lever

  1. Add the tag for the Byteboard Interview Type that you would like the candidate to receive to the candidate record in Lever.
      • Byteboard Admins can find and identify the correct tag by going to the Lever Integration section of your Team Settings page, step #4, and copying the related tag name.
      🛑
      The tag MUST be applied to the candidate before moving on to step 2 below
  1. Move the candidate into the Lever Stage configured for Byteboard.
      • This is the action that sends the invite
        • ℹ️
          *Note that if you have not yet added a tag, no invite will be sent.
  1. Confirm that a Note has been added to the candidate in Lever indicating that the invite has been sent .
      • You can also confirm directly from client.byteboard.dev/ by checking for the candidate in the Candidates tab —> Invited candidates.
 
📤
If at any point in the integration setup process you would find it helpful to meet over video chat, let us know and we’d be happy to set up a meeting to walk through any set up together!
🆘
Please contact cs@byteboard.dev or use your shared Slack channel for troubleshooting assistance regarding the integration

Did this answer your question?
😞
😐
🤩