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"
        }
    },
    "postback": {
        "enabled": true,
        "target": {
            "url": "https://api.yourdomain.com/webhooks/postback",
            "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.
`postback`	object
`postback.enabled`	boolean	Required. Enables the postback to be sent. Defaults to false.
`postback.timeout`	integer	Maximum number second Symmetry will wait for a response when sending the postback. Must be between 0-60. Default is 15.
`postback.failureNotificationEmail`	string	Email address to notify if a postback request fails
`postback.encryption`	object	Configuration for encrypting the postback payload using Rijndael encryption algorithm
`postback.encryption.encryptionCertificate`	string	Encryption certificate to be used for Rijndael encryption of the postback payload. Required if enabled is `true`.
`postback.encryption.enabled`	boolean	Required. Enables Symmetry to encrypt the postback payload using Rijndael encryption algorithm.
`postback.target`	object	Required. Defines where the postback should be sent.
`postback.target.url`	string	Target URI
`postback.target.host`	string	Target host IP address
`postback.target.port`	integer	Target proxy's port. This field is required if configuring this object for a proxy.
`postback.target.authentication`	object	Specifies the authentication scheme to use. Supported types include: `NONE`, `BASIC`, `OAUTH2`.
`postback.proxy`	object	Optional proxy configuration to route the postback request
`postback.trustAllCertificates`	boolean	When true, the system will trust all HTTPS/TLS certificates, including self-signed certificates. This is useful for testing or internal networks

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: