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:
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., W4, 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 |
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 templateworker_type
: Type of worker (Employee or Contractor)companyID
: Unique identifier for the companyemployeeID
: 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.
Updated about 1 month ago