Custom Paperwork (Early Access)

Intro

Custom Paperwork allows companies to create and manage various paperwork templates tailored to their specific needs. The Paperwork can then be used in the worker onboarding as needed. Zeal offers a powerful API to view these paperwork templates and create paperwork submissions.

In this guide

Which endpoints are needed to manage Custom Paperwork templates.
Which endpoints are needed to create Paperwork submissions (coming soon)
A step-by-step explanation on utilizing these endpoints.

Paperwork APIs

The Paperwork Template Object

The Paperwork Template object outlines the fields that represent a Paperwork Template. Templates can only be created through the UI and are managed at the company level. Templates rely on several required attributes:

attribute	type	description
templateID	string	Unique identifier for the template
form_name	string	Name of the paperwork form
paperwork_type	string	Type of paperwork (e.g. CustomPaperwork)
worker_type	string	Type of worker for the template (Employee, Contractor, All)
jurisdictions_filter	object	Filter for jurisdictions to include or exclude
jurisdiction_type	string	Type of jurisdiction for the template (Worklocation, Residency, All)
effective_date	string	Date from which the template is effective
archive_date	string	Date when the template will be archived
form_fields	array	Array of form fields present on this template

Below is a JSON example of a Paperwork Template object:

{
  "templateID": "123e4567-e89b-12d3-a456-426614174000",
  "form_name": "Custom Agreement",
  "paperwork_type": "CustomPaperwork",
  "worker_type": "Employee",
  "jurisdictions_filter": {
    "type": "include",
    "jurisdictions": ["CA", "NY"]
  },
  "jurisdiction_type": "Worklocation",
  "effective_date": "2023-01-01",
  "archive_date": "2023-12-31",
  "form_fields": [
    {
      "field_name": "employee_name",
      "label": "Employee Name",
      "error_text": "This field is required.",
      "type": "string",
      "zeal_autofill": true,
      "required": true,
      "options": null,
      "constraint": null,
      "description": "Enter the employee's name.",
      "x": 10,
      "y": 20,
      "width": 200,
      "height": 50
    }
  ]
}

Creating Paperwork Templates

Paperwork Templates can currently only be created via the Zeal application UI. Once the template is created there, the template can be fetched via the API.

Fetching Paperwork Templates

Paperwork templates can be fetched using the Get Paperwork Templates endpoint or the Get Paperwork Template (GET /paperwork/templates/{templateID}) endpoint to fetch a specific template by passing the templateID.

Submitting Paperwork

To submit a completed paperwork form, use the Create Paperwork Submission (PUT /paperwork/submissions) endpoint. The endpoint accepts the following body parameters:

templateID: Unique identifier for the paperwork template
worker_type: Type of worker (Employee or Contractor)
companyID: Unique identifier for the company
employeeID: Unique identifier for the employee (nullable if the worker type is contractor)
contractorID: Unique identifier for the contractor (nullable if the worker type is employee)
fields: Additional fields for the paperwork submission. These fields are based on the form_fields array on the parent Paperwork Template.

Below is a JSON body example of a PUT /paperwork/submissions request:

{
  "templateID": "123e4567-e89b-12d3-a456-426614174000",
  "worker_type": "employee",
  "companyID": "603d0f8f1c4b2a4e28c8f0b4",
  "employeeID": "603d0f8f1c4b2a4e28c8f0b4",
  "fields": {
    "field1": "value1",
    "field2": "value2"
  }
}

Fetching Paperwork Submissions

To fetch completed paperwork submissions, use the Get Paperwork Submissions (POST /paperwork/submissions) endpoint. The endpoint allows filtering by companyID, jurisdiction_filter, and worker_filter.

Below is a JSON response of a successful POST /paperwork/submissions request:

{
  "success": true,
  "data": [
    {
      "templateID": "123e4567-e89b-12d3-a456-426614174000",
      "submissionID": "a1b2c3d4-e5f6-4a5b-8c7d-9e0f1a2b3c4d",
      "submission_date": "2023-06-01T12:00:00Z",
      "worker_type": "employee",
      "companyID": "603d0f8f1c4b2a4e28c8f0b4",
      "employeeID": "603d0f8f1c4b2a4e28c8f0b4",
      "fields": {
        "field1": "value1",
        "field2": "value2"
      },
      "paperwork_type": "CustomPaperwork",
      "url": "https://example.com/submission/12345"
    }
  ]
}

Recap

Custom Paperwork Templates can only be created in the Zeal UI.
Zeal's Paperwork API allows for viewing Custom Paperwork Templates.
Completed paperwork forms can be fetched using the Submissions endpoints, associating them with the specific worker and template.