> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Paperwork (Early Access)

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

## 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

* How to set up Custom Paperwork Templates in the UI
* 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

## Setting up Custom Paperwork Templates

### Company Dashboard

The first step for using Custom Paperwork is to create "Paperwork Templates". Templates can currently only be created in the "Paperwork" tab in the company dashboard via the Zeal application UI:

<Frame caption="Custom Paperwork Templates can be created and managed in the “Paperwork” tab in the UI">
  <img src="https://mintcdn.com/zeal-9a4b7c2b/8iA6Z7TGBwM-qVOT/images/docs/284c4b23fcd8e08feceec3f123f33381a138af09daa32d3af0818fbffca402f3-1_Paperwork_Tab.png?fit=max&auto=format&n=8iA6Z7TGBwM-qVOT&q=85&s=fcc8f483392c505e8308680005e898fb" width="1256" height="597" data-path="images/docs/284c4b23fcd8e08feceec3f123f33381a138af09daa32d3af0818fbffca402f3-1_Paperwork_Tab.png" />
</Frame>

When you add Paperwork, you will be directed to:

1. Upload the file and paperwork metadata in the **Paperwork Details** page
2. Set the intended **Recipients**. Only these workers will be prompted to complete this paperwork by default in onboarding
3. Upload a file in the **Template Editor**. You may remove/add fields, set required/optional fields, and add signature requirements
4. **Review and Finish**

<Frame caption="Upload the file and effective start date in Paperwork Details">
  <img src="https://mintcdn.com/zeal-9a4b7c2b/8iA6Z7TGBwM-qVOT/images/docs/b05f1c31446b9071ea1ea7677142fe22c1e0bc47cedb05c9c1f8f511083dede8-2_Paperwork_Details.png?fit=max&auto=format&n=8iA6Z7TGBwM-qVOT&q=85&s=706298c1df56775c7ae1f97de5cdf3ed" width="1251" height="608" data-path="images/docs/b05f1c31446b9071ea1ea7677142fe22c1e0bc47cedb05c9c1f8f511083dede8-2_Paperwork_Details.png" />
</Frame>

<Frame caption="Set the rules for which workers should receive this paperwork in Recipients">
  <img src="https://mintcdn.com/zeal-9a4b7c2b/8iA6Z7TGBwM-qVOT/images/docs/22be1aca3c7b89f8b9e443844a1ed3b980f0d0994f868f5f4802ef38eadc8e66-3_Recipients.png?fit=max&auto=format&n=8iA6Z7TGBwM-qVOT&q=85&s=9b806132d55f32009206b6e64e844b5d" width="1251" height="606" data-path="images/docs/22be1aca3c7b89f8b9e443844a1ed3b980f0d0994f868f5f4802ef38eadc8e66-3_Recipients.png" />
</Frame>

<Frame caption="Manipulate the file in the Template Editor">
  <img src="https://mintcdn.com/zeal-9a4b7c2b/8iA6Z7TGBwM-qVOT/images/docs/7ab8a20be0a3c9f959270a3539cd5bb62ebbb65acf95a728dc9c76274fce42ea-4_Template_Editor_1.png?fit=max&auto=format&n=8iA6Z7TGBwM-qVOT&q=85&s=a09833fc8efbc8da7c6d347cb957e810" width="1255" height="796" data-path="images/docs/7ab8a20be0a3c9f959270a3539cd5bb62ebbb65acf95a728dc9c76274fce42ea-4_Template_Editor_1.png" />
</Frame>

<Frame caption="Review and Finish">
  <img src="https://mintcdn.com/zeal-9a4b7c2b/8iA6Z7TGBwM-qVOT/images/docs/c9b0234f615f40e51098a85d5ce41aa1c90f846b78ef5399e8cfc5393c21acab-6_Review_and_Finish.png?fit=max&auto=format&n=8iA6Z7TGBwM-qVOT&q=85&s=fcced2bbacaa8cc8a1ebbbdce816c12a" width="1248" height="512" data-path="images/docs/c9b0234f615f40e51098a85d5ce41aa1c90f846b78ef5399e8cfc5393c21acab-6_Review_and_Finish.png" />
</Frame>

### API

Once the template is created in the UI, the template can be fetched via the API.

The [Paperwork Template object](/reference/paperwork-api/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:

<CodeGroup>
  ```bash bash theme={null}
  {
    "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
      }
    ]
  }
  ```
</CodeGroup>

#### Fetching Paperwork Templates

Paperwork templates can be fetched using the [Get Paperwork Templates](/reference/paperwork-api/get-paperwork-templates) endpoint or the [Get Paperwork Template](/reference/paperwork-api/get-paperwork-template-by-id) (GET `/paperwork/templates/{templateID}`) endpoint to fetch a specific template by passing the `templateID`.

## Submitting Paperwork

### Company Dashboard

Workers that fall under a custom paperwork's rulesets will be prompted to complete and submit the paperwork in a new step in onboarding:

<Frame caption="In this example, this worker is prompted to complete fields and sign a given Cell Phone Policy">
  <img src="https://mintcdn.com/zeal-9a4b7c2b/8iA6Z7TGBwM-qVOT/images/docs/87dc71174048b3de928235f89f183503c09f5ed6320bd4135af76b410395da69-image.png?fit=max&auto=format&n=8iA6Z7TGBwM-qVOT&q=85&s=ca5418035514382e8494d492bd2f48d5" width="1502" height="1588" data-path="images/docs/87dc71174048b3de928235f89f183503c09f5ed6320bd4135af76b410395da69-image.png" />
</Frame>

### API

Paperwork can also be submitted through the API. To submit a completed paperwork form, use the [Create Paperwork Submission](/reference/paperwork-api/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:

<CodeGroup>
  ```bash bash theme={null}
  {
    "templateID": "123e4567-e89b-12d3-a456-426614174000",
    "worker_type": "employee",
    "companyID": "603d0f8f1c4b2a4e28c8f0b4",
    "employeeID": "603d0f8f1c4b2a4e28c8f0b4",
    "fields": {
      "field1": "value1",
      "field2": "value2"
    }
  } 
  ```
</CodeGroup>

## Seeing Paperwork Submissions

### Company Dashboard

All submitted custom paperwork can be viewed along with other onboarding paperwork (such as Form W-4s) under the worker's profile page:

<img src="https://mintcdn.com/zeal-9a4b7c2b/vBKrJf75YCNoIQu3/images/docs/ff121fc02c99a2f128689a2519a29c5bdd0c993b6e81d20eb67ee2af7d3179a8-13_People_-_Paperwork_Tab_-_Custom_Paperwork_View_Post_Onboarding.png?fit=max&auto=format&n=vBKrJf75YCNoIQu3&q=85&s=272a0a943bfcd6936277347b143e5927" alt="" width="1242" height="669" data-path="images/docs/ff121fc02c99a2f128689a2519a29c5bdd0c993b6e81d20eb67ee2af7d3179a8-13_People_-_Paperwork_Tab_-_Custom_Paperwork_View_Post_Onboarding.png" />

### API

To fetch completed paperwork submissions through the API, use the [Get Paperwork Submissions](/reference/paperwork-api/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:

<CodeGroup>
  ```bash bash theme={null}
  {
    "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"
      }
    ]
  }
  ```
</CodeGroup>

## Recap

* Custom Paperwork Templates can only be created in the Zeal UI.
* Custom Paperwork Templates can be viewed using the Zeal UI or Zeal's Paperwork API.
* Paperwork submissions can be completed by the worker in Zeal's onboarding flow, or can be submitted through the API.
* Completed paperwork forms can be viewed in the worker's profile page or fetched using the Submissions API endpoints, associating them with the specific worker and template.