Importing Data - Student Data Sync File Specification

Details on how to format the student data sync for the UK.

About the Student Sync

The student sync enables universities to pre-create accounts for all students. By having an account for every student at a university it enables key workflows for universities including:

Reporting on engagement
Tracking services delivered to all students
Marketing of key services and events to all students

What data is included in the sync is up to the university but a list of available fields is available below.

Supported Headers

The following values are supported. Required fields are indicated in bold and with an asterisk (*).

CSV Column Header	Description
email_address*	This is the basic identifier for each user in Handshake. This must be unique for each user - meaning that the same email cannot be tied to two student accounts. As a security measure, the .ac.uk domain must belong to your institution.
username*	This MUST be unique and should never change for each student. This serves as the “anchor” in imports so that other sensitive fields (such as email) can be updated around this value. Most institutions will use a student’s university ID number. This should NOT match any part of a student’s email_address, or their cardID, as both fields are subject to change (due to last name changes, lost ID cards, etc.)
first_name*	The student's first name
last_name*	The student's surname
middle_name	The student's middle name
preferred_name	The preferred name of the student. This is shown in the application to the student.
auth_identifier*	Required if using SSO. This will be used to check against the returned attribute from SSO systems to authenticate students. Students will not enter this value on login, this is a background identifier attribute. This value CAN match their email_address value, or part of it, if necessary.
primary_education:education_level_name	This field tells you the overall level of a student. It appears on student profiles to tell people what level of education they are currently pursuing. The different values you can include in this field are listed below this table. Please note the capitalisation and spelling - they have to match exactly!
primary_education:start_date	When a student first enrolled at the university. Please note that it has to be included in the format yyyy-mm-dd.
primary_education:end_date*	This is the date when a student is expected to graduate. Please note that it has to be included in the format yyyy-mm-dd, unless otherwise specified in the job. This is incredibly useful when it comes to searching students, qualifications for jobs, and knowing when to shift students to be alumni.
primary_education:college_name	This is the college that the student belongs to. Only 1 college can be supported in this field.
school_year_name*	This is the *level of the student. For a list of acceptable values please reference the table below.
primary_education:currently_attending	Boolean This is a field that simply denotes whether the student is currently enrolled or has graduated. It is used for reporting to differentiate students who are currently active and those who might be on some sort of official absence from university.
primary_education:major_names	This is the name of the course(s) that this student has declared, and will populate the "course" field on a student's profile (note: there is a limit of 255 characters per course). You can upload more than one course for a student by separating the course with semicolons. Here is an example of a History and Biology joint honours: History;Biology'
primary_education:minor_names	This field can be used to highlight additional studies that a student is taking on top of their primary course.
card_id	This string must be contained in a card swipe output. This field is where you can include student's ID numbers. If you want to use a card swipe to check students into events, career fairs, or other kiosks, make sure you include this field. Note: the Handshake application can be set to parse a value out of the card swipe output using regular expressions to generate this value.
mobile_number	This field is the mobile number of the user. We can accept any numerical string in this field without special characters such as () or - (but you can include an optional '+' at the beginning of the string).
ethnicity	The ethnicity of the student. This is a custom field that can include any text you wish to upload. This field is only visible to Career Services staff members and the individual student - used for reporting purposes. Employers will never see this information.
gender	This field indicates the gender of the students. The field is custom where you can include any text that you wish to upload.
disabled	Boolean This is a field that simply denotes whether or not a student's account is archived/active. By assigning TRUE, this will archive the user, while FALSE will unarchive the user. This is a boolean field, so it can only include these values (case sensitive)
system_label_names	This section can be used to import any outside information that you would like to sync from your SIS that might provide more nuanced information about your students in a semi-colon separated list of label names. IMPORTANT: Leaving this field blank in your import will clear all system labels in Handshake for that respective student. System labels are added or removed in every student sync that includes this column, based on exactly what you have in this field.
assigned_to_email_address	Email address of the staff member that the student is assigned to. This is useful if a student is assigned to a particular advisor as a part of the careers offering.
hometown_location_attributes:name	The address of the student's hometown, to be used for reporting purposes. For students in the UK, postcode can be used. For international students use the city name and country. You can test examples of the formatting here.
campus_name	This field is only used for institutions that have multiple campuses as part of their Handshake setup (i.e. 'Main'). If you have multiple campuses on your Handshake system, you can use these here.

System Labels as Custom Groups

System labels enable universities to tag students with data that isn't otherwise supported in the data file. These labels enable universities to run reports, define access permissions, and more. System labels are unique compared to other labels in the system in that they can only be added and removed through the data sync.

System labels are an important way for career centres to report on key groups of students. Examples of these groups might be:

Widening participation students
Students with a disability

There is no technical limit to the number of system labels that can be added to a student's profile. System labels are only visible to university career centre administrators with the proper permissions within Handshake. We do recommend that labels are limited to groupings of students and not used to represent numeric values. As a general rule of thumb, the more labels that are added to the system the harder they are to use from an administrative perspective.

Uploading All Records or Just the Changes

When you upload a file to Handshake we automatically scan the file for changes since the last file that was run. Handshake then only update records where values have changed.

That means you can upload a whole file (with all students) every time. This should simplify the logic that is required to create your file dramatically.

Example File

You can download an example CSV here.

Accepted Values

Some fields must map to values in the Handshake system. The supported values are listed below. Note these must match exactly or the Importer will throw an error.

Education Level Name Values

Secondary Education
Further Education
Certificate
Undergraduate
Postgraduate
Doctorate
Postdoctoral Researcher
Non-Degree Seeking

For Boolean Values please sync in either TRUE or FALSE (note all caps)

TRUE
FALSE

In the application school year* will appear as the level of the student. The following levels are accepted. Guidance on how to calculate these values can be found below. Note: This should show the current level of study*

School Year Values

Level 3
Level 4
Level 5
Level 6
Masters
Accelerated Masters
Masters of Business Administration
Doctorate
Postdoctoral Researcher
Alumni
Certificate Program

Calculating Level: Level can be helpful for university career teams to understand where a student is at in their degree progression.

Most universities can calculate this out on the basis of three fields:

Expected length of study (SPLENGTH - how long the course is anticipated to last)
Year of student (YEARSTU - how many years the student has been studying on the course)
Year of course (YEARPRG - which year of the course the student is on, i.e. their progression).

Generally speaking the year of course could be used to infer level of study: for example, a standard, three-year undergraduate would be studying at level 4 in the first year of their course, level 5 in the second, and level 6 in the third.

All articles in this series:

Handshake Help Center