Paperwork

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:

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.

Fetching Paperwork Templates

Paperwork templates can be fetched using 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.