Build Form I-9 and E-Verify into your own system

Overview

Your system tells us about the people it hires, changes, and lets go. We run the Form I-9 and E-Verify work for each of them, and you read the result back whenever you need it.

Quickstart

You'll authenticate, start an I-9 for a test hire, read its status, and clean up, which takes about 30 minutes.

1. Get your credentials

   To get started, email support@i-9intelligence.com or open a ticket for a Client ID and Client Secret, and ask for your location codes (unitNumber). Treat the secret like a password and keep it out of your code repository.

2. Get a token

   Exchange your credentials for a bearer token that lasts 60 minutes.

   curlJavaScriptPython

   curl -X POST https://api.i-9intelligence.com/api/Auth/api-login \
     -H "Content-Type: application/json" \
     -d '{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET"}'

   Send it on every other call as Authorization: Bearer YOUR_TOKEN, and keep the word Bearer and the space after it, because the API requires both.

3. Start an I-9 for a test hire

   Use your own email address, and set a hire date of today or later.

   curlJavaScriptPython

   curl -X POST https://api.i-9intelligence.com/api/NewHire/create \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "firstName": "Test",
       "lastName": "Hire",
       "email": "you@yourcompany.com",
       "dateOfHire": "2026-11-02",
       "applicationId": "TEST-0001",
       "unitNumber": "YOUR_UNIT",
       "employeeSSN": "Pending"
     }'

   200 response

   {
     "status": "Success",
     "employeeId": null,
     "applicationId": "TEST-0001",
     "message": "Information has been successfully saved, and an email has been sent to the new hire.",
     "errors": []
   }

   The Section 1 invite should be in your inbox within a minute or two.

4. Read the status

   bash

   curl "https://api.i-9intelligence.com/api/NewHire/status?applicationId=TEST-0001&unitNumber=YOUR_UNIT" \
     -H "Authorization: Bearer YOUR_TOKEN"

   You'll get "i9Status": 0 (Section 1 initiated) until the test hire signs Section 1. The statuses section covers every value and what to do with it.

5. Clean up

   bash

   curl -X DELETE "https://api.i-9intelligence.com/api/NewHire/delete?applicationId=TEST-0001&unitNumber=YOUR_UNIT" \
     -H "Authorization: Bearer YOUR_TOKEN"

   Delete is a soft delete. We keep the record for the audit trail, and the API returns 404 for that ID from then on. You're ready to wire up real events, and the best practices are the place to start.

I-9 deadlines to build around

Your integration decides when each I-9 starts, so it decides whether your company makes the three deadlines that come up in every build.

Six steps for any HR system integration

Whether you run Workday, SAP, Oracle, ADP, or something you built, every integration with us comes down to the same six decisions, and they're worth settling before you write code.

Locations, IDs, and hire types

Locations (unitNumber)

Every I-9 belongs to a location, identified by its unitNumber. The location decides which of your users can see and work that I-9, and its address fills in the employer address in Section 2. Locations roll up into a Level 2, usually a region, business unit, or legal entity, and your API key reaches every location under its Level 2.

Map unitNumber to the worker's physical work site in your HR system (Location in Workday and SAP SuccessFactors, Work Location in ADP), not to a department or cost center. We send the list of codes at setup, and most teams keep a small mapping table from their codes to ours.

Your IDs

Each record needs at least one of your identifiers, and you look it up by the same one later.

Both must be unique within your company among active records. Terminated records don't count, which is how rehires work.

Hire types

Fully in-person hires, where both sections happen at the worksite, aren't created through the API. Start those from the location's self-start link or in the i9 Intelligence web app.

Add "forceRemoteVerification": true to send the hire's Section 2 to our US-based compliance team by video.

Duplicate protection

Create fails with 400 if an active record already has the same SSN, employeeId, or applicationId. That stops double I-9s, and it's why a returning employee needs their old record terminated before you create a new one.

Statuses

GET /api/NewHire/status returns the I-9 status as a number in i9Status, a plain-English i9StatusDescription, and the E-Verify and reverification fields. GET /api/NewHire/get returns the form's progress as a code, such as SECTION_2_SIGNED. For separations, read status or terminationDate: a terminated hire's get still shows the last form step.

E-Verify and reverification fields

{
  "i9Status": 3,
  "i9StatusDescription": "The employer has completed and signed Section 2 of the I-9 form, verifying the employee's documentation and confirming eligibility.",
  "terminationDate": null,
  "deletedDate": null,
  "eVerifyStatusCode": "…",
  "eVerifyStatusText": "…",
  "eVerifyActionRequired": false,
  "eVerifyCaseClosureReason": null,
  "hasSupplementB": false,
  "supplementBSignatureStatus": null,
  "supplementBSignatureDate": null,
  "errors": []
}

Errors

Errors come back in one of two shapes. Field validation errors, like a missing email or a past hire date, list each failing field under errors. Business rule errors, like a duplicate ID or a record that isn't found, return one errorMessage with an errorMessageKey and the field in additionalInfo. A missing or expired token returns 401 with an empty body.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "DateOfHire": ["The date must be today or a future date."]
  },
  "traceId": "00-a165ec45e310d5776e06821cb4d2f2a4-80a9f1698161213b-01"
}

{
  "statusCode": 400,
  "errorMessage": "The Employee ID must be unique. An I9 record with this Employee Identifier already exists for this company.",
  "errorMessageKey": "VALIDATION_ERROR",
  "additionalInfo": { "AttributeName": "EmployeeId" }
}

Common validation errors

Endpoints

Every endpoint below except login needs a bearer token, and you can click any of them for its fields and an example.

{
  "status": "Success",
  "message": "All 2 new hire records created successfully.",
  "totalRecords": 2,
  "successfulRecords": 2,
  "results": [
    { "index": 0, "employeeId": null, "applicationId": "A-20417", "success": true, "message": "New hire record created successfully and email sent to employee.", "errorCode": null },
    { "index": 1, "employeeId": null, "applicationId": "A-20418", "success": true, "message": "New hire record created successfully and email sent to employee.", "errorCode": null }
  ],
  "errors": []
}

{
  "employeeId": "EMP-10042",
  "dateOfHire": "2026-11-09",
  "unitNumber": "AUS-02"
}

{
  "unitNumber": "DAL-01",
  "applicationId": "A-20417",
  "newEmployeeId": "EMP-10042"
}

{
  "employeeId": "EMP-10042",
  "unitNumber": "DAL-01",
  "terminationDate": "2027-06-30"
}

Embedding the I-9 Enterprise Package

Your portal asks for a link, opens it in a frame, and reads the status when the hire's done, so new hires never leave your site.

curl "https://api.i-9intelligence.com\
/api/UnitLink/get\
?unitNumber=DAL-01\
&applicationId=A-20417\
&usesIFRAME=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "status": "Success",
  "linkUrl": "https://app.i-9intelligence.com/…",
  "unitNumber": "DAL-01",
  "locationName": "Dallas Plant",
  "errors": []
}

<iframe
  src="LINK_URL_FROM_YOUR_SERVER"
  title="Form I-9, Section 1"
  style="width:100%;min-height:900px;border:0">
</iframe>

Section 2 for your own reviewers

Managers and HR reps who complete Section 2 get their own link from UnitLink/s2. Request it with their i9 Intelligence userName and the hire's ID, then add redirectURL if you'd like us to send them back to your tool after they sign.

Best practices

What we recommend after building and supporting integrations with Workday, SAP, and homegrown systems.

Go-live checklist

• Your HR system's automatic E-Verify submission is off
• Your HR system's own I-9 and reverification steps are off
• Credentials stored as secrets, not in code
• Your location codes mapped to our unitNumber values
• Create fires on offer accepted, with the right hire type
• Test hire created with your own email, and the invite arrived
• Status written to the worker's profile in your system
• Start date and location changes send an update
• Employee ID swapped in once your HR system assigns it
• Rescinded offers call delete, and separations call terminate
• Duplicate 400 handled without failing the job
• 401 and 429 retried correctly
• eVerifyActionRequired routed to HR
• Payroll, benefits, and IT steps don't wait on the I-9
• Failed calls retry, and someone gets alerted
• All test records deleted

Get help

Our support team answers API questions by email and phone, and our team can also work hands-on with your developers.