Configure employers - Symmetry Docs

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

Sample Request

{
  "name": "Example Company",
  "federalEIN": "98-7654321",
  "timezone": "America/New_York",
  "address": {
    "streetAddress1": "14350 N 87 ST",
    "streetAddress2": "STE 310",
    "city": "Scottsdale",
    "state": "AZ",
    "zipCode": "85260"
  },
  "webhook": {
    "callbackUrl": "https://client-system.example.com/callbacks/i9",
    "failureNotificationEmail": "admin@example.com",
    "authentication": {
      "authType": "basic",
      "username": "webhook_user",
      "password": "webhook_password"
    }
  },
  "postback": {
    "enabled": true,
    "trustAllCertificates": false,
    "timeout": 15,
    "failureNotificationEmail": "admin@example.com",
    "encryption": {
      "enabled": true,
      "encryptionCertificate": "MIIBIjANBgkq"
    },
    "target": {
      "url": "https://client-system.example.com/postbacks/i9",
      "authentication": {
        "authType": "basic",
        "username": "postback_user",
        "password": "postback_password"
      }
    },
    "proxy": {
      "host": "192.168.1.1",
      "port": 8080,
      "authentication": {
        "authType": "basic",
        "username": "proxy_user",
        "password": "proxy_password"
      }
    }
  }
}

Request elements

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

Element	Type	Description
`name`	string	Required. Name for a given Employer
`federalEIN`	string	Required. Federal Employer Identification Number for a given Employer. Must be unique.
`timezone`	string	Required. Time zone for a given Employer. Refer to the full list of supported timezones.
`address`	object	Required. Address for a given Employer
`address.streetAddress1`	string	Required. Street number and street name. This field is required when configuring address object.
`address.streetAddress2`	string	Address identifier (e.g., apartment number, suite number, etc.)
`address.city`	string	Required. City name. This field is required when configuring address object.
`address.state`	string	Required. Two-digit state name or abbreviation. This field is required when configuring address object.
`address.zipCode`	string	Required. Postal zip code. Must be exactly 5 or exactly 9 digits. Non-numeric characters are removed before validation, so `85260-2662` is validated as `852602662`.
`address.country`	string	Country code enum.
`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.failureNotificationEmail`	string	Email address to notify if a webhook request fails
`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.trustAllCertificates`	boolean	When true, the system will trust all HTTPS/TLS certificates, including self-signed certificates. This is useful for testing or internal networks. Defaults to false.
`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. This field is required if configuring this object for a proxy.
`postback.target.port`	integer	Target proxy’s port. This field is required if configuring this object for a proxy.
`postback.target.authentication`	object	Required. Specifies the authentication scheme to use. Supported types include: `none`, `basic`, `oauth2`.
`postback.proxy`	object	Optional proxy configuration to route the postback request
`postback.proxy.host`	string	Required. Target proxy IP address. Required if configuring proxy.
`postback.proxy.port`	integer	Required. Target proxy’s port. Required if configuring proxy.
`postback.proxy.authentication`	object	Specifies the authentication scheme to use. Supported types include: `none`, `basic`.

Response

The response contains an employer object, which includes the employer’s unique identifier. Below is an example of a successful response.

Sample Response

{
  "employer": {
    "id": "0195c93d-3a0e-7eab-9eb6-bf430d150873",
    "name": "Example Company",
    "federalEIN": "98-7654321",
    "timezone": "America/New_York",
    "address": {
      "streetAddress1": "14350 N 87 ST",
      "streetAddress2": "STE 310",
      "city": "Scottsdale",
      "state": "AZ",
      "zipCode": "85260",
      "country": "US"
    },
    "postback": {
      "id": "01978348-0fca-7bf7-a2d8-a068fc757370",
      "enabled": true,
      "timeout": 15,
      "failureNotificationEmail": "admin@example.com",
      "encryption": {
        "encryptionCertificate": "MIIBIjANBgkq",
        "enabled": true
      },
      "target": {
        "id": "01978348-0fcb-72ff-96e9-460990e69871",
        "url": "https://client-system.example.com/postbacks/i9"
      },
      "proxy": {
        "id": "01978348-0fca-7bf7-a2d9-11ead3434a37",
        "host": "192.168.1.1",
        "port": 8080
      },
      "trustAllCertificates": false
    },
    "webhook": {
      "callbackUrl": "https://client-system.example.com/callbacks/i9",
      "authentication": {
        "authType": "basic",
        "username": "webhook_user",
        "password": "webhook_password"
      }
    }
  }
}

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. Refer to the full list of supported timezones.
`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, returned as the digits that passed validation
`webhook`	object	Webhook configured for a given Employer
`webhook.callbackUrl`	string	URL that will receive webhook callbacks for the employer
`webhook.authentication`	object	Webhook configuration
`webhook.authentication.authType`	string	Specifies the authentication scheme to use. Supported types include: `NONE`, `basic`, `OAUTH2`.
`webhook.authentication.username`	string	Username to be used for basic authentication and password grant oauth2 authentication
`webhook.authentication.password`	string	Password to be used for basic authentication and password grant oauth2 authentication

Additional endpoints are available to support management of employer data:

Action	Endpoint
Register employer	`POST /v1/employers`
Get all employers	`GET /v1/employers`
Get employer by ID	`GET /v1/employers/{employerId}`
Update employer information	`PATCH /v1/employers/{employerId}`
Delete an employer	`DELETE /v1/employers/{employerId}`

​Register employer

​Request

​Request elements

​Response

​Response elements

Register employer

Request

Request elements

Response

Response elements