Configure Employers

The first step when using Symmetry I-9 is to set up the employer. The employer is a distinct business entity your platform supports (often called a business or company). All other API elements are associated with an employer.

When registering employers, you will also:

Specify the location where you will receive completed I-9 data (postback URL)
Specify the location where you will receive webhook events (webhook URL)

Register employer

To register an employer, you will call the /employers POST endpoint. A successful response will return the employer object, which contains the unique ID for the employer.

Request

{
    "name": "Company 1",
    "federalEIN": "999-888-7777",
    "timezone": "America/New_York",
    "address": {
        "streetAddress1": "14350 N 87th St",
        "streetAddress2": "STE 310",
        "city": "Scottsdale",
        "state": "AZ",
        "zipCode": "85260"
    },
    "webhook": {
        "callbackUrl": "https://client-system.example.com/callbacks/i9",
        "authentication": {
            "authType": "NONE"
        }
    }
}

Request Elements

Below is the data necessary to set up your employer within Symmetry.

Element	Type	Description
`name`	string	Name for a given Employer
`federalEIN`	string	Federal Employer Identification Number for a given Employer
`timezone`	object	Timezone for a given Employer
`address`	object	Address for a given Employer
`address.streetAddress1`	string	Street number and street name
`address.streetAddress2`	string	Address identifier (e.g., apartment number, suite number, etc.)
`address.city`	string	City name
`address.state`	string	State name or abbreviation
`address.zipCode`	string	Postal zip code (either 5 or 9 digits)
`webhook`	object	Optional configuration that allows Symmetry to send event notifications (such as when an I-9 is completed) back to your system
`webhook.callbackUrl`	string	Endpoint in your system where Symmetry will send the webhook event. This should be a publicly accessible URL that can receive POST requests.
`webhook.authentication`	object	Specifies how Symmetry should authenticate when sending the webhook request to your system. See additional details on webhook authentication here.

Response

The response contains an employer object, which includes the employer’s unique identifier.

Below is an example of a successful response.

{
  "employer": {
    "id": "0195c93d-3a0e-7eab-9eb6-bf430d150873",
    "name": "Company 1",
    "federalEIN": "999-888-7777",
    "timezone": "America/New_York",
    "address": {
      "streetAddress1": "14350 N 87 ST",
      "streetAddress2": "STE 310",
      "city": "Scottsdale",
      "state": "AZ",
      "zipCode": "85260"
    },
    "webhook": {
      "id": "0195c93d-4b2f-8c1d-a7e5-df560e278914",
      "callbackUrl": "https://client-system.example.com/callbacks/i9",
      "authentication": {
        "authType": "NONE"
      }
    }
  }
}

Response Elements

The descriptions below outline the key elements returned within the employer object in a successful response.

Element	Type	Description
`id`	string	Unique identifier for Employer
`name`	string	Name for a given Employer
`federalEIN`	string	Federal Employer Identification Number
`timezone`	object	Time zone for a given Employer
`address`	object	Address for a given Employer
`address.streetAddress1`	string	Street number and street name
`address.streetAddress2`	string	Address identifier (for example, suite number)
`address.city`	string	City name
`address.state`	string	State name or abbreviation
`address.zipCode`	string	Postal zip code (either 5 or 9 digits)
`webhook`	object	Webhook configured for a given Employer
`webhook.id`	string
`webhook.callbackUrl`	string
`webhook.authentication`	object
`webhook.authentication.id`	string
`webhook.authentication.authType`	string
`webhook.authentication.username`	string

Additional endpoints are available to support management of employer data: