Configure E-Verify

Once you’ve registered your employer and administrator, the next step is to configure E-Verify for any employer that will be using the E-Verify program as part of the I-9 process. E-Verify configuration can be set up in two ways:

API Setup – use the API to pass E-Verify credentials directly for an employer. This avoids requiring the administrator to key them in manually through Embedded Mode.
Embedded Mode Setup – generate a secure, embeddable link that allows an administrator to sign in and configure E-Verify credentials through the UI. This remains the method for ongoing credential updates.

Option 1: Configure E-Verify using the API

Use the following endpoint to establish E-Verify credentials for an employer with an active E-Verify account: POST /v1/employers/{employerId}/everifySettings

Request

{
  "companyId": "123456",
  "programAdministratorId": "789012",
  "programAdministratorFirstName": "John",
  "programAdministratorLastName": "Doe",
  "programAdministratorEmail": "john.doe@example.com",
  "programAdministratorPhone": "234-567-8901",
  "webServiceUsername": "everify_user",
  "webServicePassword": "everify_pwd"
}

Request elements

Element	Description
`companyId`	The employer’s E-Verify company ID (from the E-Verify portal, company profile).
`programAdministratorId`	The E-Verify user profile ID (from the E-Verify portal, user profile).
`programAdministratorFirstName`	Program Administrator’s first name (from the E-Verify portal).
`programAdministratorLastName`	Program Administrator’s last name (from the E-Verify portal).
`programAdministratorEmail`	Program Administrator’s email (from the E-Verify portal).
`programAdministratorPhone`	Program Administrator’s phone number (from the E-Verify portal).
`webServiceUsername`	The E-Verify web service user ID (from the E-Verify portal, web service profile). Note: this is an ID, not an email.
`webServicePassword`	The E-Verify web service password (from the E-Verify portal, web service profile).

E-Verify mapping

Below you’ll find screenshots from the E-Verify portal where you can find the data needed for the request.

	E-Verify Portal
Company ID
User Credentials
Webservice Credentials: navigation to webservice user
Webservice Credentials: webservice username and password

Response

The API will return the saved E-Verify settings in the everifySettings object.

{
  "everifySettings": {
    "companyId": "123456",
    "programAdministratorId": "789012",
    "programAdministratorFirstName": "John",
    "programAdministratorLastName": "Doe",
    "programAdministratorEmail": "john.doe@example.com",
    "programAdministratorPhone": "234-567-8901",
    "webServiceUsername": "everify_user",
    "webServicePassword": "everify123",
    "everifyAuthenticated": false
  }
}

The response always returns everifyAuthenticated as false, because Symmetry attempts to authenticate the credentials after the request completes. To get the authentication result, check the E-Verify authentication status or subscribe to the employer.everifyAuthenticationResult webhook.

Option 2: Configure E-Verify via embedded mode

The embedded E-Verify settings page lets a company administrator enter the employer’s E-Verify credentials directly in your platform. It collects the same values as the API request above, so the administrator can complete setup without you handling credentials.

The embedded Configure E-Verify form, with fields for company ID, program administrator details, and web services credentials — Embedded E-Verify settings page

Implementing Embedded Mode configuration in your platform is a two-step process:

Authenticate the administrator using the authenticateUri
Navigate to the embeddedUri to complete the configuration

The administrator must be authenticated before accessing the E-Verify settings page. Both links are returned by the API and must be used in sequence to ensure a successful configuration.

Enabling E-Verify makes start date mandatory. E-Verify requires every Form I-9 to include the employee’s first day of employment, which Symmetry stores as startDate. Once E-Verify is enabled, a startDate is required for every employee under that employer and is sent to E-Verify with each Form I-9. See Configure Employees & Administrators for where that field is set.

Generate E-Verify configuration page

The /employers/{employerId}/admins/{adminId}/everifySettings/generateEverifySettingsUri GET endpoint generates a secure, embeddable link to the E-Verify configuration for a valid administrator. Once embedded in your platform, the administrator can complete the form to enable automatic E-Verify case creation for all completed Forms I-9 under the employer.

Request

curl --location 'https://api.symmetry.com/i9/v1/employers/01971d41-b29d-75cf-a308-12345678/admins/01972152-29ab-78f4-93ce-12345678/everifySettings/generateEverifySettingsUri' \
--header 'Authorization: Bearer ••••••'

Path parameters

Element	Type	Description
`employerId`	string	The unique identifier of the employer for whom E-Verify is being configured.
`adminId`	string	The ID of the administrator completing the E-Verify configuration.

Response

A successful response returns a token object with two URLs: one for authentication and one for accessing the configuration page.

{
  "token": {
    "authenticateUri": "https://symmetry.workbright.com/sign_in_with_token?token=12345670a239f8b5809c",
    "embeddedUri": "https://symmetry.workbright.com/admin/everify/accounts"
  }
}

Two-step implementation process

To integrate the E-Verify settings page into your platform:

Authenticate the administrator using the authenticateUri: this one-time-use token link signs the user in securely
Embed or redirect to the embeddedUri: this opens the E-Verify settings form for configuration
- The administrator must be signed in using the authenticateUri before accessing the embeddedUri, or the page will not load properly.

Response elements

Below are the fields returned in the token object.

Element	Type	Description
`authenticateUri`	string	A secure, one-time-use link that signs the administrator in directly using a token
`embeddedUri`	string	A direct link to the E-Verify configuration page where the authenticated administrator can complete or manage E-Verify setup for the employer. The administrator must be authenticated using the `authenticateUri` prior to accessing the `embeddedUri`.

Monitor E-Verify Credential AuthenticationSubscribe to the employer.everifyAuthenticationResult webhook event to receive updates on E-Verify credential authentication. Authentication occurs when credentials are added or updated and continues to run daily, so this event may be sent regularly.

Check E-Verify authentication status

Use the following endpoint to check whether an employer’s E-Verify Web Services credentials are currently valid: GET /v1/employers/{employerId}/everifySettings The response returns the employer’s saved E-Verify settings in the everifySettings object, including the read-only everifyAuthenticated field.

{
  "everifySettings": {
    "companyId": "123456",
    "programAdministratorId": "789012",
    "programAdministratorFirstName": "John",
    "programAdministratorLastName": "Doe",
    "programAdministratorEmail": "john.doe@example.com",
    "programAdministratorPhone": "234-567-8901",
    "webServiceUsername": "everify_user",
    "everifyAuthenticated": true
  }
}

Element	Type	Description
`everifyAuthenticated`	boolean	Whether the employer’s E-Verify Web Services credentials are valid as of the most recent credential check. Returns `false` until the first successful authentication. Credentials are re-checked daily, so this value can return to `false` if a later check fails.

everifyAuthenticated is read-only. If you send it in a POST or PATCH request, Symmetry ignores the value and the request still succeeds. POST and PATCH responses always return false, so call GET afterward to read the result. If the employer has no E-Verify account configured, GET and PATCH /v1/employers/{employerId}/everifySettings return 404.

Overview

Getting started

Core concepts

Webhooks

Embedded experiences

Remote I-9

Document verification

Manage E-Verify

Compliance & audit readiness

Option 1: Configure E-Verify using the API

Request

Request elements

E-Verify mapping

Response

Option 2: Configure E-Verify via embedded mode

Generate E-Verify configuration page

Request

Path parameters

Response

Two-step implementation process

Response elements

Check E-Verify authentication status

Overview

Getting started

Core concepts

Webhooks

Embedded experiences

Remote I-9

Document verification

Manage E-Verify

Compliance & audit readiness

​Option 1: Configure E-Verify using the API

​Request

​Request elements

E-Verify mapping

​Response

​Option 2: Configure E-Verify via embedded mode

​Generate E-Verify configuration page

​Request

​Path parameters

​Response

​Two-step implementation process

​Response elements

​Check E-Verify authentication status

Option 1: Configure E-Verify using the API

Request

Request elements

Response

Option 2: Configure E-Verify via embedded mode

Generate E-Verify configuration page

Request

Path parameters

Response

Two-step implementation process

Response elements

Check E-Verify authentication status