Tracker I-9 File Integration Guide 03-2026

Change Log

Date	Notes
12/9/2019	Changed file name for ‘Create Employee Profile and I-9’, ‘Termination date’, ‘Create/Update User Account’ and ‘Create/Update worksite’.
01/27/2020	For ‘Create/Update worksite’: Replaced column header ‘Business Name’ by ‘BusinessName’ and column header ‘ExternalWorksiteId’ by ‘ExternalID’.
03/06/2020	Cosmetic changes: Create/Update Worksite file layout where Street Line 2 falls after Street Line 1, examples of how an error could be triggered.
03/12/2020	Added field separator vertical bar supported in all 4 use cases. The field separator will be a single character that can be either a comma, horizontal/vertical bar or tab.
04/03/2020	Added clarifications file format in all 4 use cases. Also added PGP format should be ASCII and not binary for all files.
04/15/2020	‘Create/Update User Account’ added clarifications for Security Role, Title and Time Zone. ‘Termination date’ had a sentence removed from I-9 ID notes that was incorrect.
04/27/2020	Inserted comment about Tracker uses TLS version 1.2.
05/15/2020	Updated FTP URLs.
05/15/2020	Added field separator quotation mark supported in all 4 use cases.
06/03/2020	Added note that for all 4 use cases, each header name must match as specified, including matching capitalization; headers are treated case sensitive.
06/18/2020	Applicable to all 4 uses cases, added note on additional file formats now supported; Added a reference to the use of ASCII armor when creating PGP encrypted files. Added also reference to Tracker API guide for error responses and updated text for notifications.
06/19/2020	Added support for Employee Appoint I-9 using RemoteAccessType ID 2810 and Virtual I-9 Pro using RemoteAccessType ID 2811
06/29/2020	Add new notification: File in Process Notification.
08/17/2020	Added UI Direct File Upload. Added additional options to update termination dates.
04/09/2021	Clarified requirements and added a description of expected outcomes and new error handling for Termination Date procession.
09/29/2021	Updated the “I-9 Manager ID” description in the Create Employee Profile and I-9 File Layout section to include additional parameters that can be used to define this value; updated the “External Id” description in the Termination Date File Layout section for clarify; removed “CandidateID” as a possible identifier for Termination Date file updates; plus other minor corrections and clarifications.
05/01/2022	Updated the “Direct File” section to reflect that as of the June 2022 release, pgp encryption is now optional for files directly uploaded by a Client Admin via the UI. Client Admins can continue to upload encrypted files. Unencrypted files uploaded by the Client Admin will be encrypted by the Tracker system automatically.
08/19/2022	Updated the File solution to support the ability to send SMS text messaging to the employee instead of email.
12/02/2022	Added support for SFTP protocol (in addition to FTPS)  Added support for two new direct file workflows:   Delete Employee/I-9   Delete Users  See the corresponding section of the guide for details.  Added support for SecurityRoleText (a string value for a Security Role) as an alternative to SecurityRole (an integer value for a Security Role).
11/13/2023	Added RemoteDocInspect field to Create Employee Profile and I-9 File Upload specs.  Added WKRemoteDocInspect field to Create/Update Worksite File specs.  Added Appendix 2 for SecurityRoleText values associated with our standard System Roles.
02/13/2023	Updated the Notes associated with RemoteAccessType value 2811 of the Create Employee Profile and I-9 File Upload specs.  Added a Note regarding Custom Security Roles under Appendix 2 Security Role Text Values.
05/15/2024	Removed tab as an acceptable delimiter. The File solution supports ampersand (&), asterisk (*), comma (,), hyphen (-) and pipe (|) delimiters.  Comma or pipe delimiter is recommended.  Added support for new direct file workflow:  Update Employee Profile  See the corresponding section of the guide for details.  Added information on the file processing logic associated with the Termination Date File Upload layout.
02/10/2025	Create Employee Profile and I-9 File Upload:    Updated the Notes of the IntegrationID field.  Updated the Attributes and Notes of the Mobile field.  Create/Update Worksite File:  Updated the Notes of the External Employer Id and External Worksite Id fields.  Update Employee Profile:  Updated the Attributes and Notes of the Mobile field.
05/02/2025	Added content to the following sections of the guide indicating that files containing more than 12,000 rows, excluding the header row, will be rejected:  Summary of this Guide  Error Handling  Notifications  Direct File Upload
09/08/2025	Updated the Notes column associated with the Time Zone field in the Create/Update User Account File  Updated the State Name in Appendix 1 from America Samoa to American Samoa  Updated the Notes column associated with the State field in the Create/Update Worksite File
11/19/2025	Removed American Samoa from Appendix 1 Valid State Codes.

 

Summary of this Guide

This guide provides the specifications for clients to supply data in files to add or update data in Tracker. For File Transfer Protocol (FTP), Tracker supports both the SFTP and FTPs protocols to enhance security; FTP authenticates client’s connection using a user ID, password and a Transport Layer Security (TLS) certificate. The following steps provide an overview of the file integration process: 

• Files are created following the Tracker file specifications (# of Fields, field names, etc.). They are named following the Tracker naming convention specified in this guide. 
• Ensure at least 5 seconds elapse between sending files of the same type to ensure proper processing.  
• Each file sent by a client will be encrypted with Tracker’s encryption keys to protect personally identifiable information. Tracker will provide the encryption keys. 
• Clients connect to a Tracker server and accept Tracker’s TLS certificate. Tracker will provide access (user/password) to the server.  
• Clients choose to use either the Secure File Transfer Protocol (sFTP) or File Transfer Protocol Secure (FTPs) to transmit the file to the home directory associated with the client’s account. The file is saved in the ‘new’ sub-folder. 
• A timed process, once every 5 minutes, wakes up to retrieve all new files put in the ‘new’ sub-folder.  
• Tracker analyzes the file for pre-processing. If there are errors associated with the file uploaded, Tracker sends an email with an error report to client designated recipients and Tracker Support.  
• The file is moved to the ‘In process’ sub-folder so the data in the file can be parsed/mapped into JSON and submitted to the Tracker API which updates Tracker. 
• All rows successfully processed are reported back in an email to client designated recipients. If the Tracker API returns an error for any row in the file, the error is reported back as well in an email to client designated recipients and Tracker Support.   
• Once the file has been processed, it is saved in the ‘completed’ sub-folder.  
• Files are kept in the ‘completed’ sub-folder for 90 days and are then permanently deleted.

IMPORTANT: Please note that files containing more than 12,000 rows, excluding the header row, will be rejected. 

Workflows

The following simplified diagram shows the workflow for processing file upload to create an I-9. 

 

The Tracker I-9 system supports the following record layouts: 

1. Create Employee Profile and I-9 
2. Update Termination Date 
3. Create/Update User Account 
4. Create Update Worksite  
5. Delete I-9 
6. Delete User Account 
7. Update Employee Profile 

System Setup

Client Supplied Setup Information 

• Client provides one or multiple public IP address/es of the system that will be sending files to Tracker so that the IP address/es can be added to a whitelist for security reasons.  
• Client provides an email group or list of email addresses for those persons who should receive file processing success email. Clients provide an email group or list of email addresses for those persons who should receive file processing error email and a separate email group or list of email addresses for those persons who should receive error report emails associated with data rows in the upload file. Tracker recommends using email groups. 
• Client provides the field separation they plan to use in their files. The field separator will be a single character that can be either a comma or pipe character. 

Tracker Supplied Setup Information

Upon set up, Tracker will send the following information via email to the designated client success email address: 

• The URL of the Tracker FTP server.
• The FTP Username Password.
• The Client Id that is used in the file naming convention requirements.
• Tracker’s Pretty Good Privacy (PGP) public key, which must be used to encrypt all files sent to the FTP site. This key will be attached to the e-mail. Note: Tracker will configure each client’s FTP account to use a Transport Layer Security (TLS) certificate to authenticate to Tracker’s FTPS server. TLS is the successor to the Secure Socket Layer (SSL) protocol which is no longer in general use. Tracker will not send the TLS certificate to the client. A TLS certificate will be configured in Tracker’s FTPS server, so when the client connects to the server, they will be able to see and accept the certificate. Tracker uses TLS version 1.2. 

*Note that you will be provided one FTP account and set of credentials to be used for testing purposes and a second FTP account for production. 

If configured, a Client Admin user can also manually upload files to the Tracker system. 

*Note that an API Key must be configured as part of the client’s setup if using Direct File Upload. 

File Format 

• Files must be in Comma Separated Value (CSV) format. 
• ASCII PGP encryption is required unless files are being manually uploaded by a Client Admin user.  
• The separator character is used to separate each header and row value. The field separator will be a single character that can be either a comma or pipe character. 
• Each header name must match the header value associated with tie integration type, including matching capitalization case, as specified below.
• The value of each field in each data row must match the requirements of the integration type as specified below. 
• Each file will be named according to the naming convention associated with the integration type.
• Fields/data rows must be provided according to the corresponding API specifications (see Use Cases chapter below).

Error Handling

File Processing Errors 

Tracker will analyze the uploaded file and reject the entire file if: 

• The file name does not match the file naming convention associated with the integration type 
• The file can’t be decrypted (client didn’t use the Tracker PGP key or file was corrupted during transit). Only applicable to files that are sent via sFTP or FTPs. 
• The file is incomplete in that it does not contain a header row followed by full sets of data rows, in other words, at least 2 rows, 1 header and 1 data row, are not present in the file. 
• The file contains more than 12,000 rows, excluding the header row. 

File Data API Errors

After a file has been accepted, Tracker will analyze the data in the file and reject the row of data if errors occur while processing the data. Potential data errors are described below for each integration type and in the Tracker API Guide. When errors are detected, a report will be generated and sent to the client’s email group or email addresses provided. 

Notifications

Success Notification 

Once the file has been uploaded and successfully processed, clients will receive the following e-mail: 

Subject: Tracker File Processing Status Update [File Name] – Success 
Dear Client, 
[Client Name] ([Client ID]) Tracker Data Status Update for file [File Name]. 
The file [File Name] was successfully processed. 

Failure Notification 

A file is uploaded in the FTPS server. A file upload processing error does not occur. The data is transformed and submitted to the Tracker system via the Tracker API. The Tracker API returns an error for one or more rows of data in the file. See Tracker’s API Integration guide, section Error Responses, for detailed messages. Examples of this error are when i.e. 1 or more required field values are missing in a row or i.e. the file has headers and no required values or i.e. when a worksite does not exist in Tracker, etc. The client will ultimately receive an explanation of the error.  The client will receive the following e-mail (this just an example): 

Subject: Tracker File Processing Status Update [File Name] – Error 
Dear Client, 
[Client Name] ([Client ID]) Tracker Data Status Update for file [File Name]. 
The file [File Name] was processed. 

Successfully processed records: 1, 2, 5 

The following errors were found: 

Record #	Error	Error Message
3		Invalid data in row
4	EmployerId	The Employer field is required
4	WorkSiteId	The Worksite field is required
4	FirstName	The First Name field has a maximum length of 50 characters
6	DOB	DOB is not a valid date
6	DOB	Date of Birth cannot be more than 120 years in the past

 

Service Unavailable Notification 

The service is not available. Clients will receive the following e-mail: 

Subject: Tracker File Processing Status Update [File Name] – Error 
Dear Client, 
Tracker File Processing Service is temporarily offline. 
You don’t need to resend the file. We will hold it and process it when the service becomes available. We will send you a confirmation once the file has been processed. 

File in Process Notification 

If a file with same name is still in process, clients will receive the following e-mail: 

Subject: Tracker File Processing Status Update [File Name] – Error 
Dear Client, 
The [File Name] with same name is still in process. 
You don’t need to resend the file. We will send you a confirmation once the file has been processed. 

Decryption Failed / File Corrupted Notification 

The file cannot be decrypted, or it is corrupted. Clients will receive the following e-mail: 

Subject: Tracker File Processing Status Update [File Name] – Error 
Dear Client, 
[Client Name] ([Client ID]) Tracker File Status Update for file [File Name]. 
The file [File Name] was not processed. 
We encountered the following error when attempting to process the file: 
The file could not be decrypted (client did not use our PGP key or file was corrupted during transit). 

Please make any necessary changes and resubmit the file to the FTP server. If the error persists, please contact Tracker support. 

Invalid File Name Notification 

Client’s file does not meet format name requirements. Clients will receive the following e-mail: 

Subject: Tracker File Processing Status Update [File Name] – Error 
Dear Client, 
[Client Name] ([Client ID]) Tracker File Status Update for file [File Name]. 
The file [File Name] was not processed. 
We encountered the following error when attempting to process the file: 
The file name does not match the file naming convention associated with the integration type 
Please make any necessary changes and resubmit the file to the FTP server. If the error persists, please contact Tracker support.  

Maximum Record Limit Exceeded 

Client’s file contains more than 12,000 rows, excluding the header row. 

Subject: Tracker File Processing Status Update [File Name] – Error 
Dear Client, 
[Client Name] ([Client ID]) Tracker File Status Update for file [File Name]. 
The file [File Name] was not processed. 
We encountered the following error when attempting to process the file: 
Maximum record limit exceeded. The file contains more than the allowed maximum of 12,000 records. 

Create Employee Profile and I-9 File Upload 

File Layout 

The following layout is used to create new employees and I-9s. 

Field Description	Requirement	Attributes	Column Header*	Notes
First Name	Required	string (50)	FirstName	No numeric characters allowed
Last Name	Required	string (50)	LastName	No numeric characters allowed
Employer	Required	String (50) agreed code configured on Tracker	ExternalEmployerId
Worksite	Required	String (50) agreed code configured on Tracker	ExternalWorksiteId
Start Date	Required	Date, format YYYY-MM-DD	StartDate
Email Address	Cond. Required	String (100)	Email	Not required for I-9 Workflow type 0 below, but required for all other workflows.
Mobile	Cond. Required	String (10),  format ##########	Mobile	Employee’s mobile phone number used to send SMS text messages. Must be a US phone number. Only numeric characters are accepted. Can be excluded from file if not using SMS. Not required for I-9 Workflow 0. Required to use SMS as the preferred communication method for this employee.
I-9 Workflow Type	Required	integer – Value set based on desired operational workflow	RemoteAccessType	Used to designate the I-9 workflow:  0 = Onsite: Completion of Section 1 and Section 2 is done in-person and is facilitated by the I-9 Manager.  2800 = Remote Section 1 Only:  Section 1 is delivered to the Employee and completed remotely. Section 2 is completed by the I-9 Manager directly in the Tracker application.  2801 = Employer Appoint: Section 1 is delivered to the Employee and completed remotely. Employer sets up the Authorized Representative. Section 2 is delivered to the Authorized Representative who meets in-person with the Employee and completes Section 2.  2808 = Network Alliance: Section 1 is delivered to the Employee and completed remotely. Employee schedules an appointment to meet in-person with a Network Alliance Representative who will complete Section 2.  2810 = Employee Appoint: Section 1 is delivered to the Employee and completed remotely. Employee sets up the Authorized Representative. Section 2 is delivered to the Authorized Representative who meets in-person with the Employee and completes Section 2.  2811 = I-9 Pro: Section 1 is delivered to the Employee and completed remotely. Employee schedules an appointment to meet with a Tracker I-9 Pro team member via a live interactive video meeting who will complete Section 2.
Remote Document Inspection	Cond. Required	Boolean	RemoteDocInspect	True if the I-9 should be subject to Remote Document Inspection.  Note that there is a dependency on the Remote Document Inspection feature being enabled for the client and the I-9 being subject to E-Verify.  False if the I-9 should not be subject to Remote Document Inspection. False is the default value if not included.
Flag to send section 1 email from Tracker	Required	Boolean – Value set based on desired operational workflow	SendEmployeeEmail	True when Tracker sends section 1 email and False when a section 1 email will not be sent.
Flag to send section 1 text message from Tracker	Cond. Required	Boolean – Value set based on desired operational workflow	SendEmployeeText	Must be True to send section 1 SMS message. Can be false or excluded from file when not sending SMS message.   If the SMS feature setting is disabled, sending both SendEmployeeEmail and SendEmployeeText as true will result in an email being sent.   If the SMS feature is enabled, sending both SendEmployeeEmail and SendEmployeeText will result in an error.
Internal Employee ID or Candidate ID	Recommended	String (255)	IntegrationID	An ID associated with an employee from hire to re-hire. This id is exposed on the Employee Profile record and can also be obtained by using I-9 Custom Reports. Value must be unique.  We use Integration ID to check for duplicated records; the Integration ID must be provided and be unique for an employee if the client wants us to check for duplications.  If this ID is not provided, we could create duplicates. Clients will be responsible to purge the duplicates.
External Employee ID	Recommended	String (100) must be unique, No PII	ExternalId	An ID associated with an employee that is externally exposed. Must be unique. (Strongly recommended to better identify the row which failed) External Employee ID can also be sued to check for duplications.
Date of Birth		Date, format YYYY-MM-DD	DOB
SSN		String (9 or 11) format ######### or ###-##-###	SSN
Street		String (255)	Street
Apt Number		String (100)	AptNum
City		String (100)	City
State		String (From list of set values in Appendix 1 below)	State	Must be in format shown in Appendix 1
Zip		String (5) format #####	Zip
Phone		String (100) format ###-###-####, (###) ###-#### or ##########	Phone
Middle Name		String (40)	MiddleName
I-9 Manager ID (assigned to Employee  Profile)		String (255)	ExternalUserId	Identifier set by client to identify a manager as defined by the ‘Employee ID’ value on the I-9 Manager User Account page.
			UserID	Identifier set by the Tracker system to identify a manager.
			UserName	Identifier of the manager used when logging into the Tracker System as defined by the ‘Username’ value on the I-9 Manager User Account page.
Remote Employer Rep Email	Required for Remote Section 2 assignment	String (70)	RemoteAccessEmployerRepEmail	Used with I-9 Workflow type 2801 only. Field is required when assigning an employer representative. If field is blank, an employer representative can be assigned manually in Tracker
Remote Employer Rep First Name	Optional for Remote Section 2	String (70)	RemoteAccessEmployerRepFirst	Used with I-9 Workflow type 2801 only
Remote Employer Rep Last Name	Optional for Remote Section 2	String (70)	RemoteAccessEmployerRepLast	Used with I-9 Workflow type 2801 only
Remote Employer Rep Phone	Optional for Remote Section 2	String (70)	RemoteAccessEmployerRepPhone	Used with I-9 Workflow type 2801 only
Remote Employer Rep Title	Optional for Remote Section 2	String (70)	RemoteAccessEmployerRepTitle	Used with I-9 Workflow type 2801 only

*Clients will designate the value of the file field separator. The field separator will be a single character that can be either a comma or pipe character. Separation format quotation marks “,“ is supported i.e. “FirstName”,”LastName”, etc. 

*Each header name must match as specified above, including matching capitalization; headers are treated case sensitive.

File Naming Convention 

Files will be named in a format of NEWEMPLOYEEANDI9_#####_YYMMDDHHMMSS.CSV or NEWEMPLOYEEANDI9_#####_YYYYMMDDHHMMSS.CSV where: 

• NEWEMPLOYEEANDI9 = Constant Value 
• ##### = Client ID number masked to #####, i.e. 123 to 00123 
• YYMMDDHHMMSS or YYYYMMDDHHMMSS = File Creation Date time stamp (Year can use 2 or 4 digits)  

File name extensions and encryption requirements: 

• The base data file will have a .csv extension 
• Since the base file is encrypted, the encrypted file will have a .pgp extension. 4 formats are supported: 
  NEWEMPLOYEEANDI9_#####_YYMMDDHHMMSS.pgp 
  NEWEMPLOYEEANDI9_#####_YYYYMMDDHHMMSS.pgp 
  NEWEMPLOYEEANDI9_#####_YYMMDDHHMMSS.csv.pgp 
  NEWEMPLOYEEANDI9_#####_YYYYMMDDHHMMSS.csv.pgp 
• The file needs to use ASCII PGP encryption and not binary PGP encryption. ASCII PGP encryption is an encryption with ASCII Armor https://en.wikipedia.org/wiki/Binary-to-text_encoding#ASCII_armor 

Note that the entire file is not treated as case sensitive. 

Data Record Errors

The following are potential errors associated with Create Employee Profile and I-9 records. A complete list of errors is available in the Tracker API guide. 

• The first or last name contains numeric characters. 
• ExternalEmployerId does not exist 
• ExternalWorksiteId does not exist 
• ExternalEmployeeId is not unique 
• IntegrationID is not unique 

Employee has an active I-9. The active I-9 must be terminated before creating a new I-9. If IntegrationIds are used, Tracker will automatically set the existing I-9 to a terminated status, but the termination date will not be updated. 

Update Termination Date File Upload 

File Layout 

The following layout is used to add or update a Termination Date to an I-9 record.  

IMPORTANT NOTE: you must select one of the following identifiers to use to map the Termination Date to the I-9 record.  

1. I-9 ID 
2. Employee ID 
3. External Employee ID 
4. Employee Profile Social Security Number 
5. Integration ID 

If you opt to use 2, 3, 4, or 5 as your identifier AND if multiple I-9 records are detected, AND if there is only one active I-9 associated with a given Employee Profile record then the system will attempt to apply the Termination Date reflected on the file to the record. This processing logic was put in place to support employee’s who have had multiple hiring events. 

Field Description	Requirement	Attributes	Column Header*	Notes
I-9 ID	Terminations can be performed using any of these field options. Only one of the options must be selected.	Integer	I9Id	ID generated in Tracker when the active I-9 was created that uniquely identifies the I-9.
OR			OR
Employee ID		integer	EmployeeId	Internal application employee identifier. This is also known as the Employee Profile Id.
OR			OR
External Id		string (100)	ExternalId	Identifier set by the client to identify the employee. Must be unique. This is displayed in the Employee Id field on the Employee Profile record in the application.
OR			OR
Social Security Number		string (9 or 11)	SSN	Employee’s Social Security Number.
OR			OR
Integration ID		string (255)	IntegrationID	Additional identifier set by client. For example, this is often used as an applicant identifier, as opposed to an employee identifier (ExternalId). Required for Duplicate/Rehire check.
Termination Date	Required	Date, format YYYY-MM-DD	TerminationDate	Termination date must be on or after the hire date associated with the I-9.   Note: For a given I-9 ID, if the I-9 has been already terminated, then it will update the termination date with the given date in this field.

*Clients will designate the value of the file field separator. The field separator will be a single character that can be either a comma or pipe character. Separation format quotation marks “,“ is supported i.e. “I9Id”, “TerminationDate”. 

*Each header name must match as specified above, including matching capitalization; headers are treated case sensitive. 

File Naming Convention 

Files will be named in a format of TERMINATIONS_#####_YYMMDDHHMMSS.CSV or TERMINATIONS_#####_YYYYMMDDHHMMSS.CSV where: 

• TERMINATIONS = Constant Value 
• ##### = Client ID number masked to #####, i.e. 123 to 00123 
• YYMMDDHHMMSS or YYYYMMDDHHMMSS = File Creation Date time stamp (Year can use 2 or 4 digits) 

File name extensions and encryption requirements: 

• The base data file will have a .csv extension 
• Since the base file is encrypted, the encrypted file will have a .pgp extension. 4 formats are supported:  
  TERMINATIONS_#####_YYMMDDHHMMSS.pgp 
  TERMINATIONS_#####_YYYYMMDDHHMMSS.pgp 
  TERMINATIONS_#####_YYMMDDHHMMSS.csv.pgp 
  TERMINATIONS_#####_YYYYMMDDHHMMSS.csv.pgp  

• The file needs to use ASCII PGP encryption and not binary PGP encryption. ASCII PGP encryption is an encryption with ASCII Armor https://en.wikipedia.org/wiki/Binary-to-text_encoding#ASCII_armor 

Note that the entire file is not treated as case sensitive. 

Termination Date Business Logic

The details below describe the expected outcomes for the list of use cases when using I9Id as the identifier. As noted above, a Termination Date is valid when it is in the YYYY-MM-DD format, after the Section 2 Start Date, and no later than 60 days from the current date or Section 2 Start Date, whichever is later.  

Termination Field in File	Pre-File Status	Post-File Process
Valid Termination Date	I-9 Record’s Termination Date is empty	Termination Date is applied to the I-9
Valid Termination Date	I-9 Record has a Termination Date	Termination Date is applied to the I-9
Empty Termination Date	I-9 Record’s Termination Date is empty	I-9 Record’s Termination Date is empty
Empty Termination Date	I-9 Record has a Termination Date	I-9 Record’s Termination Date is empty
Invalid Termination Date	I-9 Record’s Termination Date is empty	I-9 Record’s Termination Date is empty
Invalid Termination Date	I-9 Record has a Termination Date	I-9 Record’s Termination Date is unchanged

 

Data Record Errors 

The following are potential errors associate with Create Employee Profile and I-9 records. A complete list of errors is available in the Tracker API guide. 

• I-9ID does not exists 
• Termination date is before start date 
• Multiple I9s are associated to Employee Profile [EmployeeId]. The I-9 [termination date] haven’t been updated. 

Create/Update User Account File 

File Layout 

The following layout is used to create or update I-9 Manager user accounts. 

Field Description	Requirement	Attributes	Column Header*	Notes
First Name	Required	string (255) alpha only	FirstName	No numeric characters allowed
Last Name	Required	string (255) alpha only	LastName	No numeric characters allowed
Email Address	Required	String (100)	Email	Not required for I-9 Workflow type 0 below
User Name	Required	String (101)	UserName	User Name provided when logging into the Tracker website. Must be unique across Tracker clients. Suggested format is ClientID_UserID (i.e. 1234_Jsmith)
Title	Required**	String (250)	Title	Title of the user. This value will appear on the Form I-9s this user signs.   **This argument can be left out if there is a Client default value set up in the application, otherwise, it is required.
Security Role	Required**	integer   Or   string     Value set based on client configuration	SecurityRole  Or  SecurityRoleText	Used to identify functions available to the user.  Please request your SecurityRole values from your Implementation Project Manager.   Please see Appendix 2 for the SecurityRoleText values associated with our standard System Roles.  **This argument can be left out if there is a Client default value set up in the application, otherwise, it is required.
Time Zone		Integer	TimeZoneID	Time zone where user is located. If it is not included and a Client default exists, that value will be used. If it is not sent and no client default exists, Eastern Time will be assigned. 1 – Atlantic Time (GMT-04:00)  2 – Eastern Time (GMT-05:00)  4 – Central Time (GMT-06:00)  5 – Mountain Time (GMT-07:00)  6 – Arizona (GMT-07:00)  7 – Pacific Time (GMT-08:00)  8 – Alaska (GMT-09:00)  9 – Hawaii (GMT-10:00)   User Account will still be created if an invalid Time Zone value is sent.
External Employee ID		String (100) must be unique, No PII	ExternalId	An ID associated with an employee that is externally exposed. Must be unique. (Strongly recommended to better identify the row which failed)
Active		Boolean	Active	When active, user can log in. True – active, False – inactive
Middle Name		String (255)	MiddleName
Phone	Required (if user will have E-Verify permissions and employers are configured so that E-Verify contacts I-9 Managers)	String (25) format ###-###-####, (###) ###-#### or ##########	Phone	E-Verify now requires a phone number and extension for the individual submitting E-Verify cases. This field is required if the I-9 Manager will have E-Verify permissions and the Manager will process cases for employers that are configured to send the I-9 Manager phone number and not configured to send a default phone number for the employer.
Ext	Optional	String (50)	Ext	E-Verify now requires a phone number and extension for the individual submitting E-Verify cases. This field is required if the I-9 Manager will have E-Verify permissions and the Manager’s phone information is sent to E-Verify.
External Worksite Ids		List of strings	ExternalWorksiteIds	List of codes configured in Tracker separated by commas. Used to assign access by Worksite.
External Security Group Ids		List of strings	ExternalSecurityGroupIds	List of codes configured in Tracker separated by commas. Used to assign access by Security Group.
External Employer Ids		List of strings	ExternalEmployerIds	List of codes configured in Tracker separated by commas. Used to assign access by Employer.
All Client Access		Boolean	AllClientAccess	Used to provide access to all employers and worksites. True – all access, False – not all access (default)
Send Login Email		Boolean	SendLoginEmail	Used to send user login information from Tracker. True- send login email, False – do not send login email. Highly recommended when using this upload to provision new I-9 Managers so they will receive their user name and password.

*Clients will designate the value of the file field separator. The field separator will be a single character that can be either a comma or pipe character. Separation format quotation marks “,“ is supported i.e. “FirstName”,”LastName”, etc. 

*Each header name must match as specified above, including matching capitalization; headers are treated case sensitive. 

File Naming Convention 

Files will be named in a format of USER_#####_YYMMDDHHMMSS.CSV or USER_#####_YYYYMMDDHHMMSS.CSV where: 

• USER = Constant Value 
• ##### = Client ID number masked to #####, i.e. 123 to 00123 
• YYMMDDHHMMSS or YYYYMMDDHHMMSS = File Creation Date time stamp (Year can use 2 or 4 digits) 

File name extensions and encryption requirements: 

• The base data file will have a .csv extension 
• Since the base file is encrypted, the encrypted file will have a .pgp extension. 4 formats are supported:  
• USER_#####_YYMMDDHHMMSS.pgp 
• USER_#####_YYYYMMDDHHMMSS.pgp 
• USER_#####_YYMMDDHHMMSS.csv.pgp 
• USER_#####_YYYYMMDDHHMMSS.csv.pgp 
• The file needs to use ASCII PGP encryption and not binary PGP encryption. ASCII PGP encryption is an encryption with ASCII Armor https://en.wikipedia.org/wiki/Binary-to-text_encoding#ASCII_armor 

Note that the entire file is not treated as case sensitive. 

Data Record Errors 

The following are potential errors associate with Create Employee Profile and I-9 records. A complete list of errors is available in the Tracker API guide. 

• The first or last name contains numeric characters 
• Security Role missing 
• Title missing 
• ExternalEmployeeId is not unique 
• UserName is not unique 

Create/Update Worksite File 

File Layout 

The following layout is used to create or update Worksites. 

Field Description	Requirement	Attributes	Column Header*	Notes
External Employer ID	Required	string (50)	ExternalEmployerId	Must be unique
External Worksite ID	Required	string (50)	ExternalID	Must be unique across all Employers
Worksite Name	Required	String (100)	Name
Street Line 1	Required	String (100)	Street1	Line one of the worksite address
Street Line 2		String (100)	Street2	Line two of the worksite address
City	Required	String (50)	City
State	Required	String (From list of set values in Appendix 1 below	State	Must be in format shown in Appendix 1.   American Samoa is not an acceptable State value for Worksites.
Zip	Required	String (5 or 10) format ##### or #####-####	Zip
Business Name	Optional	String (100)	BusinessName	Business name which should over-ride the business name of the worksite’s employer on the I-9
Remote Document Inspection		Boolean	WKRemoteDocInspect	True = Default Remote Document Inspection Setting is ON for this worksite.  Note that there is a dependency on the Remote Document Inspection feature being enabled for the client and E-Verify being enabled for this Worksite.  False = Default Remote Document Inspection Setting is OFF for this worksite. False is the default value if not included.
E-Verify		Boolean	EVerify	True = E-Verify on, False = E-Verify off. Default is off, but Employer setting over-rides Worksite
E-Verify Start Date		Date	EVerifyStartDate	First date E-Verify is used on the site. Prevents E-Verifying employees hired prior to start date
Is Enabled		Boolean	IsEnabled	True = active, False = inactive/closed

*Clients will designate the value of the file field separator. The field separator will be a single character that can be either a comma or pipe character. Separation format quotation marks “,“ is supported i.e. “ ExternalEmployerId “,” ExternalID”, etc. 

*Each header name must match as specified above, including matching capitalization; headers are treated as case sensitive. 

File Naming Convention 

Files will be named in a format of WORKSITE_#####_YYMMDDHHMMSS.CSV or WORKSITE_#####_YYYYMMDDHHMMSS.CSV where: 

• WORKSITE = Constant Value 
• ##### = Client ID number masked to #####, i.e. 123 to 00123 
• YYMMDDHHMMSS or YYYYMMDDHHMMSS = File Creation Date time stamp (Year can use 2 or 4 digits) 

File name extensions and encryption requirements: 

• The base data file will have a .csv extension 
• Since the base file is encrypted, the encrypted file will have a .pgp extension. 4 formats are supported:  
  WORKSITE_#####_YYMMDDHHMMSS.pgp 
  WORKSITE_#####_YYYYMMDDHHMMSS.pgp 
  WORKSITE_#####_YYMMDDHHMMSS.csv.pgp 
  WORKSITE_#####_YYYYMMDDHHMMSS.csv.pgp 
• The file needs to use ASCII PGP encryption and not binary PGP encryption. ASCII PGP encryption is an encryption with ASCII Armor https://en.wikipedia.org/wiki/Binary-to-text_encoding#ASCII_armor 

Note that the entire file is not treated as case sensitive. 

Data Record Errors 

The following are potential errors associated with Create Employee Profile and I-9 records. A complete list of errors is available in the Tracker API guide. 

• ExternalEmployerId does not exist 
• ExternalWorksiteId is not unique 
• State code not valid 
• Zip code not valid 

Delete I-9

File Layout 

The following file layout is used to delete I-9 and Employee Profile records.  

IMPORTANT NOTE: you must select one of the following identifiers to delete an I-9 record.  

1. I-9 ID 
2. Employee ID 
3. External Employee ID 
4. Employee Profile Social Security Number 
5. Integration ID 

If you opt to use 2, 3, 4, or 5 as your identifier and the Tracker I-9 system finds multiple I-9s for an Employee Profile matching the identifier, then the Tracker I-9 system will not delete any I-9s or Employee Profiles. 

Field Description	Requirement	Attributes	Column Header*	Notes
I-9 ID	Deletions can be performed using any of these field options. Only one of the options must be selected.	Integer	I9Id	ID generated in Tracker when the active I-9 was created that uniquely identifies the I-9.
OR			OR
Employee ID		integer	EmployeeId	Internal application employee identifier. This is also known as the Employee Profile Id.
OR			OR
External Id		string (100)	ExternalId	Identifier set by the client to identify the employee. Must be unique. This is displayed in the Employee Id field on the Employee Profile record in the application.
OR			OR
Social Security Number		string (9 or 11)	SSN	Employee’s Social Security Number.
OR			OR
Integration ID		string (255)	IntegrationID	Additional identifier set by client. For example, this is often used as an applicant identifier, as opposed to an employee identifier (ExternalId).

*Clients will designate the value of the file field separator. The field separator will be a single character that can be either a comma or pipe character. Separation format quotation marks “,“ is supported i.e. “I9Id“,”IntegrationID”, etc. 

*Each header name must match as specified above, including matching capitalization; headers are treated as case sensitive. 

Employee Profile Deletion  

After deleting the I-9, the File solution will attempt to delete the associated Employee Profile automatically. The Employee Profile will not be deleted if there are any I-9 records associated to the Employee Profile after the I-9 identified in the file layout is deleted.  

File Naming Convention 

Files will be named in a format of DELETEI9_#####_YYMMDDHHMMSS.CSV or DELETEI9_#####_YYYYMMDDHHMMSS.CSV where:   

• DELETEI9 = Constant Value   
• ##### = Client ID number masked to #####, i.e. 123 to 00123   
• YYMMDDHHMMSS or YYYYMMDDHHMMSS = File Creation Date time stamp (Year can use 2 or 4 digits)   

File name extensions and encryption requirements: 

• The base data file will have a .csv extension 
• Since the base file is encrypted, the encrypted file will have a .pgp extension. 4 formats are supported:  
  DELETEI9_#####_YYMMDDHHMMSS.pgp 
  DELETEI9_#####_YYYYMMDDHHMMSS.pgp   
  DELETEI9_#####_YYMMDDHHMMSS.csv.pgp   
  DELETEI9_#####_YYYYMMDDHHMMSS.csv.pgp 
• The file needs to use ASCII PGP encryption and not binary PGP encryption. ASCII PGP encryption is an encryption with ASCII Armor https://en.wikipedia.org/wiki/Binary-to-text_encoding#ASCII_armor 

Note that the entire file is not treated as case sensitive.   

Delete User Account

File Layout  

The following file layout is used to delete I-9 Manager user accounts.  

Field Description	Requirement	Attributes	Column Header*	Notes
User ID	Deletions can be performed using any of these field options. Only one of the options must be selected.	Integer	UserId	ID generated in Tracker when the User Account was created that uniquely identifies the user.
OR			OR
External User ID		string (100)	ExternalUserId	Identifier set by the client to identify the user. Must be unique. This is displayed in the User Account Id field on in the application.

*Clients will designate the value of the file field separator. The field separator will be a single character that can be either a comma or pipe character. Separation format quotation marks “,“ is supported i.e. “UserId“,”ExternalUserId”, etc. 

*Each header name must match as specified above, including matching capitalization; headers are treated as case sensitive. 

File Naming Convention

Files will be named in a format of DELETEUSERS_#####_YYMMDDHHMMSS.CSV or DELETEI9_#####_YYYYMMDDHHMMSS.CSV where: 

• DELETEUSERS_ = Constant Value 
• ##### = Client ID number masked to #####, i.e. 123 to 00123   
• YYMMDDHHMMSS or YYYYMMDDHHMMSS = File Creation Date time stamp (Year can use 2 or 4 digits) 

File name extensions and encryption requirements:   

• The base data file will have a .csv extension   
• Since the base file is encrypted, the encrypted file will have a .pgp extension. 4 formats are supported:  
  DELETEUSERS_#####_YYMMDDHHMMSS.pgp   
  DELETEUSERS_#####_YYYYMMDDHHMMSS.pgp   
  DELETEUSERS_#####_YYMMDDHHMMSS.csv.pgp   
  DELETEUSERS_#####_YYYYMMDDHHMMSS.csv.pgp   
• The file needs to use ASCII PGP encryption and not binary PGP encryption. ASCII PGP encryption is an encryption with ASCII Armor https://en.wikipedia.org/wiki/Binary-to-text_encoding#ASCII_armor 

Note that the entire file is not treated as case sensitive.

Update Employee Profile

File Layout 

The following file layout is used to update Employee Profile records.  

Field Description	Requirement	Attributes	Column Header*	Notes
Employee Profile Id	Required	Integer	EmployeeId	Internal application employee identifier.  Must be included in order to update one or more fields an Employee Profile record.
First Name		string (50)	FirstName	No numeric characters allowed.
Last Name		string (50)	LastName	No numeric characters allowed.
Middle Name		String (40)	MiddleName	Employee’s middle name.
Other Last Names		String (50)	OtherNames	Employee’s maiden name or other legal last name.
SSN		String (9 or 11) format ######### or ###-##-###	SSN	Employee’s U.S. Social Security Number.
Date of Birth		Date, format YYYY-MM-DD	DOB	Employee’s birthdate.
Employee Id		String (100) must be unique, No PII	ExternalId	An external Id assigned to the employee by the employer and exposed on the Employee Profile record in the Employee Id field. Must be unique. (Strongly recommended to better identify a row on the file which may have failed).
Integration Id		String (255) must be unique, No PII	IntegrationID	An internal Id assigned to an employee that stays with them from hire to re-hire. This id is exposed on the Employee Profile record and can also be obtained by using I-9 Custom Reports. Value must be unique.
Email Address		String (100)	Email	Employee’s email address.
Mobile		String (10) , format ##########	Mobile	Employee’s mobile phone number used to send SMS text messages. Must be a US phone number. Only numeric characters are accepted. Only needed/used if client has the SMS feature enabled and  SMS is the preferred communication method for the employee.
Internal Employer Id	To update the Employer, only include one of these 2 Id’s	Integer	EmployerId	Identifier set by the Tracker application that represents the employee’s employer.
External Employer Id		String (50)	ExternalEmployerId	Identifier set by the client that represents the employee’s employer.
Internal Worksite Id	To update the Worksite, only include one of these 2 Id’s	Integer	WorksiteId	Identifier set by the Tracker application that represents the employee’s worksite.
External Worksite Id		String (50)	ExternalWorksiteId	Identifier set by the client that represents the employee’s worksite.
I-9 Manager Id (assigned to Employee  Profile)	To update the I-9 Manager, only include one of these 3 Id’s	String (255)        Integer    String (101)	ExternalUserId	Identifier set by client that represents the I-9 Manager. Defined by the ‘Employee ID’ value as part of the I-9 Manager’s user account setup.
			UserID	Identifier set by the Tracker application that represents the I-9 Manager
			UserName	Identifier set by client that represents the I-9 Manager. Defined by the ‘Username’ value as part of the I-9 Manager’s user account setup.

*Clients will designate the value of the file field separator. The field separator will be a single character that can be either a comma or pipe character. Separation format quotation marks “,“ is supported i.e. “IntegrationID“,” ExternalId”, etc. 

*Each header name must match as specified above, including matching capitalization; headers are treated as case sensitive. 

*If a column header is included on the file and if no value is included under that column header for one or more records, then when the record is processed the corresponding field on the Employee Profile record will be removed. As an example:  

EmployeeId,Email 

12345, 

56789,trackertest@trackercorp.com 

The Email Address will be removed from the Employee Profile record associated with EmployeeId (Tracker Internal Profile Id) 12345 and will be updated for EmployeeId 56789. 

*Note that the First Name, Last Name, Employer and Worksite fields are required on the Employee Profile record. You will only be able to update them and not remove them. If one or more of these required fields are included as Column Headers on the file and if the value is blank for one or more records then the blank values will be ignored. 

File Naming Convention   

Files will be named in a format of UPDATEEMPLOYEEPROFILE_#####_YYMMDDHHMMSS.CSV or UPDATEEMPLOYEEPROFILE_#####_YYYYMMDDHHMMSS.CSV where: 

• UPDATEEMPLOYEEPROFILE_ = Constant Value   
• ##### = Client ID number masked to #####, i.e. 123 to 00123   
• YYMMDDHHMMSS or YYYYMMDDHHMMSS = File Creation Date time stamp (Year can use 2 or 4 digits)   

File name extensions and encryption requirements:   

• The base data file will have a .csv extension   
• Since the base file is encrypted, the encrypted file will have a .pgp extension. 4 formats are supported:  
  UPDATEEMPLOYEEPROFILE _#####_YYMMDDHHMMSS.pgp   
  UPDATEEMPLOYEEPROFILE _#####_YYYYMMDDHHMMSS.pgp   
  UPDATEEMPLOYEEPROFILE _#####_YYMMDDHHMMSS.csv.pgp   
  UPDATEEMPLOYEEPROFILE _#####_YYYYMMDDHHMMSS.csv.pgp   
• The file needs to use ASCII PGP encryption and not binary PGP encryption. ASCII PGP encryption is an encryption with ASCII Armor https://en.wikipedia.org/wiki/Binary-to-text_encoding#ASCII_armor 

Note that the entire file is not treated as case sensitive.   

Data Record Errors 

The following are potential errors associated with Create Employee Profile and I-9 records. A complete list of errors is available in the Tracker API guide. 

• Last Name cannot contain numbers 
• First Name cannot contain numbers 
• Employer Id 222222 does not belong to Client Id 1160 
• Worksite Id 444444 does not belong to Client Id 1160 
• Worksite Id 444444 does not belong to Employer Id 222222 
• UserId does not belong to WorksiteId 444444 
• The SSN number is not valid or is not entered correctly. The SSN must be entered as nine digits 
• (#########) or nine digits with two hyphens (###-##-####). 
• Email is not a valid email 

Direct File Upload 

Clients who have direct file upload enabled will be able to manually upload the files in the client admin UI. Just client admins will be able to upload the files. Clients need to follow the file format described in this guide. 

IMPORTANT: Please note that files containing more than 12,000 rows, excluding the header row, will be rejected. 

Optional Direct File Upload and Encryption 

File encryption is optional for files directly uploaded by a Client Admin via the UI. Unencrypted files uploaded by the Client Admin will be encrypted by the Tracker system automatically. 

Take the following steps to upload a file: 

1. As a Client Admin login and navigate to the File Processing tab (Admin Control Panel/System Configuration/File Processing). The number of options on this screen may vary depending upon your account set-up. 

 

2. Click the Choose file button next to the file type that you want to upload. 

 

3. Select the correctly formatted and named .csv or .pgp file 

 

4. The Tracker I-9 system will display a confirmation message letting you know that the file uploaded successfully. If you receive a file formatting error, resolve the error and repeat steps 2 and 3. 
    

Appendix 1 Valid State Codes 

The following are valid for codes State names 

Appendix 1 (State Names)
Alabama
Alaska
Arizona
Arkansas
California
Colorado
Connecticut
Delaware
District of Columbia
Federated States Of Micronesia
Florida
Georgia
Guam
Hawaii
Idaho
Illinois
Indiana
Iowa
Kansas
Kentucky
Louisiana
Maine
Marshall Islands
Maryland
Massachusetts
Michigan
Minnesota
Mississippi
Missouri
Montana
Nebraska
Nevada
New Hampshire
New Jersey
New Mexico
New York
North Carolina
North Dakota
Northern Mariana Islands
Ohio
Oklahoma
Oregon
Palau
Pennsylvania
Puerto Rico
Rhode Island
South Carolina
South Dakota
Tennessee
Texas
Utah
Vermont
Virgin Islands Of The U.S.
Virginia
Washington
West Virginia
Wisconsin
Wyoming
Canada
Mexico

 

Appendix 2 Security Role Text Values 

Standard System Security Roles	SecurityRoleText Value
Basic User With E-Verify	BASIC_USER_EVERIFY
Basic User Without E-Verify	BASIC_USER
Intermediate User With E-Verify	INTERMEDIATE_USER_EVERIFY
Intermediate User Without E-Verify	INTERMEDIATE_USER
Advanced User With E-Verify	ADVANCED_USER_EVERIFY
Advanced User Without E-Verify	ADVANCED_USER

Note: If using Custom Security Roles, the SecurityRoleText value is the Role Name without spaces. As an example, if the Role Name is Custom Advanced User With E-Verify then the SecurityRoleText value is CustomAdvancedUserWithE-Verify.