Paperwork

Learn how to create Paperwork that can be used in worker onboarding.

Intro

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 manage and submit these paperwork templates.

Note: Paperwork is a feature currently only available through Zeal's API.

In this guide

  • Which endpoints are needed to create and manage Paperwork templates.
  • A step-by-step explanation on utilizing these endpoints.

Paperwork APIs

Paperwork functionalities are available for integration via API.

The Paperwork Template Object

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

attributetypedescription
templateIDstringUnique identifier for the template
form_namestringName of the paperwork form
paperwork_typestringType of paperwork (e.g., W4, CustomPaperwork)
worker_typestringType of worker for the template (Employee, Contractor, All)
jurisdictions_filterobjectFilter for jurisdictions to include or exclude
jurisdiction_typestringType of jurisdiction for the template (Worklocation, Residency, All)
effective_datestringDate from which the template is effective
archive_datestringDate when the template will be archived

Additional attributes can be passed to further configure the paperwork template, such as form_fields, which detail the specific fields required in the paperwork. 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 and then edited via the API.

Updating or Fetching Paperwork Templates

Paperwork templates can be updated or fetched using the corresponding Update Paperwork Template or PATCH /paperwork/templates/{templateID} endpoint to update, or the Get Paperwork Template or 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 or 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

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 or 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": "type1",
      "url": "https://example.com/submission/12345"
    }
  ]
}

Recap

  • Paperwork allows for creating and managing various paperwork templates via API.
  • Templates can be created via the UI, then updated and fetched using the respective API endpoints.
  • Completed paperwork forms can be submitted and fetched, associating them with the specific worker and template.