1. Configure Employers

Enable employers to register for I-9 processing

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.

ElementTypeDescription
namestringName for a given Employer
federalEINstringFederal Employer Identification Number for a given Employer
timezoneobjectTimezone for a given Employer
addressobjectAddress for a given Employer
address.streetAddress1stringStreet number and street name
address.streetAddress2stringAddress identifier (e.g., apartment number, suite number, etc.)
address.citystringCity name
address.statestringState name or abbreviation
address.zipCodestringPostal zip code (either 5 or 9 digits)
webhookobjectOptional configuration that allows Symmetry to send event notifications (such as when an I-9 is completed) back to your system
webhook.callbackUrlstringEndpoint in your system where Symmetry will send the webhook event. This should be a publicly accessible URL that can receive POST requests.
webhook.authenticationobjectSpecifies how Symmetry should authenticate when sending the webhook request to your system. See additional details on webhook authentication here.
postbackobject
postback.enabledbooleanRequired. Enables the postback to be sent. Defaults to false.
postback.timeoutintegerMaximum number second Symmetry will wait for a response when sending the postback. Must be between 0-60. Default is 15.
postback.failureNotificationEmailstringEmail address to notify if a postback request fails
postback.encryptionobjectConfiguration for encrypting the postback payload using Rijndael encryption algorithm
postback.encryption.encryptionCertificatestringEncryption certificate to be used for Rijndael encryption of the postback payload. Required if enabled is true.
postback.encryption.enabledbooleanRequired. Enables Symmetry to encrypt the postback payload using Rijndael encryption algorithm.
postback.targetobjectRequired. Defines where the postback should be sent.
postback.target.urlstringTarget URI
postback.target.hoststringTarget host IP address
postback.target.portintegerTarget proxy's port. This field is required if configuring this object for a proxy.
postback.target.authenticationobjectSpecifies the authentication scheme to use. Supported types include: NONE, BASIC, OAUTH2.
postback.proxyobjectOptional proxy configuration to route the postback request
postback.trustAllCertificatesbooleanWhen 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.

ElementTypeDescription
idstringUnique identifier for Employer
namestringName for a given Employer
federalEINstringFederal Employer Identification Number
timezoneobjectTime zone for a given Employer
addressobjectAddress for a given Employer
address.streetAddress1stringStreet number and street name
address.streetAddress2stringAddress identifier (for example, suite number)
address.citystringCity name
address.statestringState name or abbreviation
address.zipCodestringPostal zip code (either 5 or 9 digits)
webhookobjectWebhook configured for a given Employer
webhook.idstring
webhook.callbackUrlstring
webhook.authenticationobject
webhook.authentication.idstring
webhook.authentication.authTypestring
webhook.authentication.usernamestring

Additional endpoints are available to support management of employer data:


Jump to top