Resource model & identifiers

Every Symmetry I-9 endpoint is scoped to a fixed place in a resource hierarchy. Knowing where a resource sits tells you which path to call and which identifiers you need to have on hand.

The hierarchy

Account                          (implicit — determined by your API key)
└── Employer                     /v1/employers/{employerId}
    ├── Employee                 …/employees/{employeeId}
    │   └── Submission           …/submissions/{submissionId}
    ├── Admin                    …/admins/{adminId}
    ├── E-Verify settings        …/everifySettings
    └── E-Verify cases           …/everifyCases/{id}

Account is the top of the tree, and it is never passed in a path. Your API key determines the account, and account-scoped endpoints act on every employer beneath it. /v1/applicationTheme, for example, sets a theme for the whole account, while /v1/employers/{employerId}/applicationTheme overrides it for one employer. Employer is the boundary that effectively all data hangs from. Employees, administrators, E-Verify configuration, and themes are all scoped to an employer, which is what makes employer-level isolation useful for testing your setup. Employee holds the person and their onboarding state. An employee can be promoted to an administrator while remaining an employee. Submission is a single Form I-9 belonging to an employee. An employee may have more than one submission over time, for example after a rehire.

Identifiers

Most identifiers are UUIDs. Treat them as opaque values: store them as strings, and don’t parse them or infer anything from their ordering.

Resource	Identifier	Type
Employer	`employerId`	string (UUID)
Employee	`employeeId`	string (UUID)
Administrator	`adminId`	string (UUID)
Submission	`submissionId`	integer
E-Verify case	`caseId`	string

Submission IDs are integers, not UUIDs. Unlike every other resource, a submission is identified by a small sequential integer such as 118. If your data model assumes a UUID for every Symmetry identifier, submissions will break it.

A submissionId reaches you in a few ways. Most often you already have it from a webhook, where it arrives as data.submission.id rather than as submissionId:

"data": {
  "employerId": "12345-3fe3-7146-8ea6-123456sdfg",
  "employeeId": "0987654-d7ee-702f-92f3-123456lkjhgf",
  "submission": {
    "id": 1334
  }
}

You can also list an employee’s submissions to find one, then request it directly:

GET /v1/employers/{employerId}/employees/{employeeId}/submissions
GET /v1/employers/{employerId}/employees/{employeeId}/submissions/{submissionId}

The E-Verify caseId is issued by E-Verify rather than by Symmetry, so it follows E-Verify’s own format instead of a UUID. See Manage E-Verify Cases for working with cases.

​The hierarchy

​Identifiers

The hierarchy

Identifiers