Importer: Getting Started + Running Your First File

Liz Gehret -

What is the Importer?

The Importer is used both internally at Handshake, and externally by our partners to analyze and import data into Handshake.

How does the Importer work?

You can think of the Importer as a translator between a CSV file and Handshake. It translates a CSV file into JSON that's fed into our API and into Handshake.

How do I access the Importer?

The Importer is an awesome tool, but it is a bit complex and handles a lot of sensitive data, so we ask that you first watch this video in our Help Center and follow the instructions in the video. After finishing, contact our Tech Support team here to get access to the Importer. 

After you've received access to the Importer, you will be able to import data from an external CSV file into Handshake! This article will provide you with an overview for how to upload your first file.



Running a File on the Importer: 

  1. Visit
  2. Click "Upload New CSV" in the top right hand corner of the purple band:

  3. Complete the steps below to upload your file:
    1. Choose the file to upload after correctly formatting and saving as a UTF-8 encoded CSV file (more information below).
    2. Choose the correct job type for the data you are uploading (more information below).
    3. Add a description of the data you are importing.
    4. Click "Save Job".


4. You will be taken to a page while the importer completes analysis on your file.

5. Continue to refresh the page until the status reads "Ready for Submission":

6. Scroll to the bottom of the page to read the agreement prior to running the file. After reading, click the box next to "I agree that this data looks appropriate and understand this import cannot be deleted". Click "Run Job".

7. You will now be taken to the progress page as the importer runs your file into Handshake:

8. After the file has completed running, click "View Download Results" in the upper right hand corner.

9. Next, click "Download Failed Rows CSV" to see the records that failed to process and their associated error messages. More information on resolving Importer errors can be found here

Requesting for a Job to be Processed on the Importer

For some importer job types, the Handshake importer team will need to review the file upload prior to running the data into the system to preserve data integrity and prevent any unforeseen challenges. Some examples include a user file where you are updating sensitive fields or if you are trying to import appointment types.

In these situations, you will not be able to "Run Job" immediately (as outlined in the steps above). Instead, follow steps 1-5 exactly the same. After the importer has completed analysis on your data (step 6), instead of clicking "Run Job", you will check the agreement box and click the blue bottom that says "Submit and Request Run":

Your importer job will go into a queue for the Handshake team to review prior to running the file. You can expect a 24 hour turnaround for your file to be run or to receive feedback from the Handshake team.

Importer Job Types

  • Students
  • Contacts
    • How to format and upload contacts
    • All contacts that have an invalid email and/or email domain will be pushed back to your team. Feel free to update the contacts' information and send us a new file.
    • Contacts are generally employer or alumni contacts, pulled from your previous system.
    • Prior to the employer launch, you'll want to upload a list of employer contacts into Handshake - This will allow you to mass email, inviting them to join the Handshake platform. 
    • Contacts are verified prior to import.
  • Appointments
  • Appointment Types
  • Events
  • Notes
    • How to format and upload Notes
    • Note imports often take place when a school is going through implementation, to pull over historical information. Other times, a staff member may be tracking their notes by some external source and need a way to mass upload those into the system.
    • Notes can be applied to Users (students or career services), Appointments, Events, or Career Fairs.
  • Labels (normal)
    • Labels are generally used to help classify and filter subsets of users (Students, Staff, or Contacts)
    • They may also be used on appointments and events, if the Identifiable ID is provided

Outside of manually importing your data through CSV uploads on the Importer, you can also transfer your student data using AWS S3. The section below will go through this workflow in depth.

Data Transfer w/s3

There are many ways of interacting with s3 to upload data on a regular basis, AWS s3 is very flexible and there are many clients, tools, and services written to interact with its many features.   

In order of popularity, here are the methods we see for uploading data to AWS S3:

  1. AWS Cli - A simple python based client for uploading data (easiest to use)
  2. S3 Bash - A simple upload cli based using only local unix tools such as curl / openssl for upload (easiest to install)
  3. REST API - The underlying API for AWS S3 (most flexible)


Some common AWS issues

  • If your file looks like it's uploading to AWS but NOT to the Importer, then check what characters you are using
    • The following character sets are generally safe for use in key names: Alphanumeric characters: 0-9 a-z A-Z Special characters: ! - _ . * ' ( )
    • See here for more information
Was this article helpful?
1 out of 3 found this helpful
Have more questions? Submit a request