{ "openapi": "3.1.0", "info": { "title": "zeal-api", "version": "1.0" }, "servers": [ { "url": "https://api.zeal.com" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "in": "header", "name": "Authorization", "x-bearer-format": "bearer" } }, "schemas": { "WithholdingSchedule": { "type": "array", "minItems": 1, "description": "Advanced withholding schedule (mutually exclusive with cap_amount / cap_percentage). Employee-only: contractors have no pay frequency, so a schedule on a contractor is rejected — use cap_amount / cap_percentage instead. Use for fixed amounts per pay frequency or disposable-earnings brackets. At least one of cap_amount, cap_percentage, or withholding_schedule is required. Money fields are in dollars. When present, every frequency branch must tile disposable earnings from $0.00 to infinity with no gaps or overlaps: the first bracket min must be 0, each next min must be exactly $0.01 after the previous max, and the last bracket max must be null. At least one bracket in the schedule must withhold (not all exempt).", "items": { "type": "object", "required": ["frequency", "brackets"], "properties": { "frequency": { "type": "string", "enum": [ "daily", "weekly", "biweekly", "semimonthly", "monthly", "quarterly" ], "description": "Pay frequency this branch applies to" }, "brackets": { "type": "array", "minItems": 1, "description": "Disposable-earnings brackets for this frequency. Must tile $0.00 to infinity with no gaps or overlaps (first min is 0; each next min is previous max + 0.01; last max is null).", "items": { "type": "object", "required": ["min", "max", "action"], "properties": { "min": { "type": "number", "minimum": 0, "description": "Inclusive lower bound of disposable earnings in dollars. The first bracket in a branch must start at 0." }, "max": { "type": "number", "minimum": 0, "nullable": true, "description": "Inclusive upper bound of disposable earnings in dollars. Only the last bracket may be null (open-ended); earlier brackets require a max." }, "action": { "oneOf": [ { "type": "object", "required": ["kind"], "properties": { "kind": { "type": "string", "enum": ["exempt"], "description": "Do not withhold in this band" } } }, { "type": "object", "required": ["kind", "amount"], "properties": { "kind": { "type": "string", "enum": ["amount"] }, "amount": { "type": "number", "minimum": 0, "description": "Fixed dollar amount to withhold" } } }, { "type": "object", "required": ["kind", "floor"], "properties": { "kind": { "type": "string", "enum": ["excess_over_floor"] }, "floor": { "type": "number", "minimum": 0, "description": "Withhold disposable earnings above this floor (dollars)" } } }, { "type": "object", "required": ["kind", "percentage"], "properties": { "kind": { "type": "string", "enum": ["percentage"] }, "percentage": { "type": "number", "minimum": 0, "maximum": 100, "description": "Percentage of disposable earnings to withhold (0-100)" } } } ], "description": "How to compute the withhold amount for this bracket" } } } } } } } } }, "security": [ { "sec0": [] } ], "paths": { "/authLinks/taxes": { "post": { "summary": "Generate Company Taxes Page link", "description": "Generates an authenticated link that can be hosted as a UI component for the Company Taxes Page.", "operationId": "get-employer-taxes-page-link", "x-fern-sdk-group-name": "authLinks", "x-fern-sdk-method-name": "getTaxesPage", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["partnerID", "companyID"], "properties": { "partnerID": { "type": "string", "description": "PartnerID of the Zeal Partner" }, "companyID": { "type": "string", "description": "CompanyID of the company" }, "showSidebar": { "type": "boolean", "description": "Indicate whether or not you would like the UI sidebar displayed" } } }, "examples": { "Request Example": { "value": { "partnerID": "c133ecdere9b3445a2f22Cc258b23445a", "companyID": "fc235f012bae46222ca3444cc2215bcfa", "showSidebar": true } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "url": "https://payroll.your-domain.com/token-auth?redirectUrl=%2Ftaxes%2Fhome&routeFilter=%2Ftaxes%2F%2A&token=good-token-string" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "url": { "type": "string", "example": "https://payroll.your-domain.com/token-auth?redirectUrl=%2Ftaxes%2Fhome&routeFilter=%2Ftaxes%2F%2A&token=good-token-string" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Object(s) is missing required fields or has improperly formatted data", "status": 400, "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Object(s) is missing required fields or has improperly formatted data" }, "status": { "type": "integer", "example": 400, "default": 0 }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/getAuthLink": { "post": { "summary": "Generate Company Login Link", "description": "Generates a link that automatically signs in an employer into their Zeal Company Dashboard.", "operationId": "retrieve-employer-login-link", "x-fern-sdk-group-name": "/authLinks", "x-fern-sdk-method-name": "company", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["partnerID", "companyID"], "properties": { "partnerID": { "type": "string", "description": "PartnerID of the Zeal Partner" }, "companyID": { "type": "string", "description": "CompanyID of the company" }, "embedded_page": { "type": "string", "description": "By specifying the particular page you want to embed, the embedded component will show just that page and no sidebar. Can take the values of `dashboard` (home page), `employees`, `contractors`, `custom-attributes`, `custom-paperwork`, `i9`, or `reports`.", "enum": [ "dashboard", "employees", "contractors", "custom-attributes", "custom-paperwork", "i9", "reports" ] } } }, "examples": { "Request Example": { "value": { "partnerID": "c133ecdere9b3445a2f22Cc258b23445a", "companyID": "fc235f012bae46222ca3444cc2215bcfa" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "url": "https://payroll.your-domain.com/auth?accessToken=" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "url": { "type": "string", "example": "https://payroll.your-domain.com/auth?accessToken=" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No Partner with this partnerID exists", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No Partner with this partnerID exists" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/authLinks/reports": { "post": { "summary": "Generate Reports Link", "description": "Generates a link that signs in an employer to their Zeal Reports Dashboard.", "operationId": "get-reports-link", "x-fern-sdk-group-name": "authLinks", "x-fern-sdk-method-name": "getReportsPage", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["partnerID", "companyID"], "properties": { "partnerID": { "type": "string", "description": "PartnerID of the Zeal Partner" }, "companyID": { "type": "string", "description": "ID of the Company" } } }, "examples": { "Request Example": { "value": { "companyID": "fc2ccf012b2342cc342ca082f357715bcfa", "partnerID": "c133eed233c9b8419ba4452cc059bd445a" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "url": "https://payroll.yourdomain.com/token-auth?redirectUrl=%2Freports&routeFilter=%2Freports&token=" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "url": { "type": "string", "example": "https://payroll.yourdomain.com/token-auth?redirectUrl=%2Freports&routeFilter=%2Freports&token=" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "success": false, "message": "No user with this company ID exists.", "code": 4 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "message": { "type": "string", "example": "No user with this company ID exists." }, "code": { "type": "integer", "example": 4, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/paystubLink": { "get": { "summary": "Get Paystub Link", "description": "Fetches an expirable link that displays an employee paystub.", "operationId": "get-paystub-link", "x-fern-sdk-group-name": "paystubLink", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of employer", "required": true, "schema": { "type": "string" } }, { "name": "employeeCheckID", "in": "query", "description": "ID of Employee Check", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "allow_retry", "schema": { "type": "boolean", "default": "false" }, "description": "Boolean flag to allow the worker to retry a returned transaction on this employee check" } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": "https://payroll.yourdomain.com/public/paystub/" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "string", "example": "https://payroll.yourdomain.com/public/paystub/" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee Check with this ID does not exist", "code": 17 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee Check with this ID does not exist" }, "code": { "type": "integer", "example": 17, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/companies": { "post": { "summary": "Create Company", "description": "Creates a company within Zeal.", "operationId": "create-company", "x-fern-sdk-group-name": "companies", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "partnerID", "first_name", "last_name", "email", "business_name", "business_ein", "business_address", "business_city", "business_state", "business_zip", "business_phone", "mail_address", "mail_city", "mail_state", "mail_zip", "ssn", "ownership_percentage", "legal_structure", "dob", "address", "city", "state", "zip" ], "properties": { "partnerID": { "type": "string", "description": "Your Partner ID (found in the API page of your Admin portal)" }, "first_name": { "type": "string", "description": "First name of business owner or administrator." }, "last_name": { "type": "string", "description": "Last name of business owner or administrator." }, "email": { "type": "string", "description": "Email address of business." }, "business_name": { "type": "string", "description": "Legal name of business." }, "business_ein": { "type": "string", "description": "Federal EIN of business." }, "business_address": { "type": "string", "description": "Street address component of business address" }, "business_city": { "type": "string", "description": "City component of business address" }, "business_state": { "type": "string", "description": "State component of business address" }, "business_zip": { "type": "string", "description": "Zip code component of business address" }, "business_phone": { "type": "string", "description": "Phone number of business" }, "mail_address": { "type": "string", "description": "Mailing address of company" }, "mail_city": { "type": "string", "description": "Mailing city of company" }, "mail_state": { "type": "string", "description": "Mailing state of company" }, "mail_zip": { "type": "string", "description": "Mailing ZIP code of company" }, "skip_migration": { "type": "boolean", "description": "If true, Zeal will skip migrating payroll information from the company's old payroll provider. **Note: please confirm with the company that migration is not necessary. Failure to migrate old records may impact tax reporting and filing.**", "default": false }, "ssn": { "type": "string", "description": "SSN of the primary business owner." }, "ownership_percentage": { "type": "integer", "description": "The ownership percentage held by the primary business owner.", "format": "int32" }, "legal_structure": { "type": "string", "description": "The legal structure of the business.", "enum": [ "ccorp", "corp", "estate", "foreign_entity", "llc", "llp", "lp", "nonprofit", "partnership", "scheme", "scorp", "soleprop", "trust" ] }, "job_title": { "type": "string", "description": "The job title of the primary business owner." }, "company_type": { "type": "string", "description": "Mark your company as \"all\" (employees and contractors) or \"contractor_only\" to limit company's scope to 1099 contractors.", "enum": ["all", "contractor_only"] }, "dob": { "type": "string", "description": "Date of birth of the primary business owner. This should be in the`MM/DD/YYYY` format" }, "address": { "type": "string", "description": "Address of the primary business owner." }, "address_line2": { "type": "string", "description": "Address line 2 of the primary business owner." }, "city": { "type": "string", "description": "City of the primary business owner." }, "state": { "type": "string", "description": "State of the primary business owner." }, "zip": { "type": "string", "description": "Zip code of the primary business owner." }, "payroll_schedule": { "type": "string", "description": "The default payroll schedule that the company follows", "enum": [ "daily", "weekly", "biweekly", "semimonthly", "monthly" ] }, "payroll_firstDate": { "type": "string", "description": "The ISO-8601 date of the first regular payroll" }, "payroll_firstPayPeriodID": { "type": "string", "description": "Reporting period ID of the first regular payroll" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "1ea89873acdae98734", "status": "initial_onboarding", "first_name": "richard", "last_name": "hendricks", "email": "richard@piedpiper.com", "business_name": "Pied Piper", "business_ein": "073647583", "business_address": "1 Market St.", "business_city": "San Francisco", "business_state": "CA", "business_zip": "94110", "skip_migration": false, "business_phone": "2025550151", "mail_address": "1 Market St.", "mail_city": "San Francisco", "mail_state": "CA", "mail_zip": "94110", "requirements": [], "account_number": null, "routing_number": null, "is_sandbox": true, "ssn": "22-333-4444", "ownership_percentage": 25, "dob": "01/01/1990", "legal_structure": "ccorp", "job_title": "CEO", "address": "1 Ferry Building", "city": "San francisco", "state": "CA", "zip": "94105", "company_type": "all", "onboarding_url": "/employeronboard/1ea89873acdae98734?companyID=1ea89873acdae98734&classification=TEST", "payroll_firstCheckDate": "2024-08-30", "payroll_schedule": "weekly", "payroll_firstPayPeriodID": "6580ce4a3808d60023b4e412" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "1ea89873acdae98734" }, "status": { "type": "string", "example": "initial_onboarding" }, "first_name": { "type": "string", "example": "richard" }, "last_name": { "type": "string", "example": "hendricks" }, "email": { "type": "string", "example": "richard@piedpiper.com" }, "business_name": { "type": "string", "example": "Pied Piper" }, "business_ein": { "type": "string", "example": "073647583" }, "business_address": { "type": "string", "example": "1 Market St." }, "business_city": { "type": "string", "example": "San Francisco" }, "business_state": { "type": "string", "example": "CA" }, "business_zip": { "type": "string", "example": "94110" }, "skip_migration": { "type": "boolean", "example": false, "default": true }, "business_phone": { "type": "string", "example": "2025550151" }, "mail_address": { "type": "string", "example": "1 Market St." }, "mail_city": { "type": "string", "example": "San Francisco" }, "mail_state": { "type": "string", "example": "CA" }, "mail_zip": { "type": "string", "example": "94110" }, "requirements": { "type": "array" }, "account_number": {}, "routing_number": {}, "is_sandbox": { "type": "boolean", "example": true, "default": true }, "ssn": { "type": "string", "example": "22-333-4444" }, "ownership_percentage": { "type": "integer", "example": 25, "default": 0 }, "dob": { "type": "string", "example": "01/01/1990" }, "legal_structure": { "type": "string", "example": "ccorp" }, "job_title": { "type": "string", "example": "CEO" }, "address": { "type": "string", "example": "1 Ferry Building" }, "city": { "type": "string", "example": "San francisco" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": "94105" }, "company_type": { "type": "string", "example": "all" }, "onboarding_url": { "type": "string", "example": "/employeronboard/1ea89873acdae98734?companyID=1ea89873acdae98734&classification=TEST" }, "payroll_firstCheckDate": { "type": "string", "example": "2024-08-30" }, "payroll_schedule": { "type": "string", "example": "weekly" }, "payroll_firstPayPeriodID": { "type": "string", "example": "6580ce4a3808d60023b4e412" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "The address provided is not a valid, mail-deliverable address", "code": 48 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "The address provided is not a valid, mail-deliverable address" }, "code": { "type": "integer", "example": 48, "default": 0 } } } } } } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "curl", "code": { "partnerID": "ab8734eacdcd7692a", "first_name": "Richard", "last_name": "Hendricks", "email": "richard@piedpiper.com", "business_name": "Pied Piper", "business_ein": "073647583", "business_address": "1 Market St.", "business_city": "San Francisco", "business_state": "CA", "business_zip": "94110", "business_phone": "3322232341", "mail_address": "1 Market St.", "mail_city": "San Francisco", "mail_state": "CA", "mail_zip": "94110", "skip_migration": false, "ssn": "22-333-4444", "ownership_percentage": 25, "dob": "01/01/1990", "legal_structure": "ccorp", "job_title": "CEO", "address": "1 Ferry Building", "city": "San francisco", "state": "CA", "zip": "94105", "company_type": "all", "payroll_firstCheckDate": "2024-08-30", "payroll_schedule": "weekly", "payroll_firstPayPeriodID": "6580ce4a3808d60023b4e412" }, "name": "EXAMPLE REQUEST" } ], "samples-languages": ["curl"] } }, "patch": { "summary": "Update Company Information", "description": "Update the Company Object", "operationId": "update-company-info", "x-fern-sdk-group-name": "companies", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID"], "properties": { "companyID": { "type": "string", "description": "Company ID of the employer (you can access companyID on the Zeal dashboard)" }, "first_name": { "type": "string", "description": "First name of business owner or administrator." }, "last_name": { "type": "string", "description": "Last name of business owner or administrator." }, "email": { "type": "string", "description": "Email address of business." }, "business_name": { "type": "string", "description": "Business Name of company" }, "business_phone": { "type": "string", "description": "Phone number of company" }, "business_address": { "type": "string", "description": "Street address of company's business address" }, "business_city": { "type": "string", "description": "City of company's business address" }, "business_state": { "type": "string", "description": "State of company's business address" }, "business_zip": { "type": "string", "description": "Zip code of company's business address" }, "mail_address": { "type": "string", "description": "Mailing address of company" }, "mail_city": { "type": "string", "description": "Mailing city of company" }, "mail_state": { "type": "string", "description": "Mailing state of company" }, "mail_zip": { "type": "string", "description": "Mailing zip code of company" }, "ssn": { "type": "string", "description": "SSN of the primary business owner." }, "ownership_percentage": { "type": "integer", "description": "The ownership percentage held by the primary business owner.", "format": "int32" }, "legal_structure": { "type": "string", "description": "The legal structure of the business.", "enum": [ "ccorp", "corp", "estate", "foreign_entity", "llc", "llp", "lp", "nonprofit", "partnership", "scheme", "scorp", "soleprop", "trust" ] }, "job_title": { "type": "string", "description": "The job title of the primary business owner." }, "dob": { "type": "string", "description": "Date of birth of the primary business owner. This should be in the`MM/DD/YYYY` format." }, "address": { "type": "string", "description": "Address of the primary business owner." }, "address_line2": { "type": "string", "description": "Address line 2 of the primary business owner." }, "city": { "type": "string", "description": "City of the primary business owner." }, "state": { "type": "string", "description": "State of the primary business owner." }, "zip": { "type": "string", "description": "Zip code of the primary business owner." }, "payroll_schedule": { "type": "string", "description": "The default payroll schedule that the company follows", "enum": [ "daily", "weekly", "biweekly", "semimonthly", "monthly" ] }, "payroll_firstDate": { "type": "string", "description": "The ISO-8601 date of the first regular payroll" }, "payroll_firstPayPeriodID": { "type": "string", "description": "Reporting period ID of the first regular payroll" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "1e2wu23273238c22ea2", "first_name": "Richard", "last_name": "Hendricks", "email": "richard@piedpiper.com", "business_name": "Pied Piper", "business_address": "1 Market St.", "business_city": "San Francisco", "business_state": "CA", "business_zip": "94110", "business_phone": "2025550151", "mail_address": "1 Market St.", "mail_city": "San Francisco", "mail_state": "CA", "mail_zip": "94110", "ssn": "22-333-4444", "ownership_percentage": 25, "dob": "01/01/1990", "legal_structure": "ccorp", "job_title": "CEO", "address": "1 Ferry Building", "city": "San francisco", "state": "CA", "zip": "94105", "payroll_firstCheckDate": "2024-08-30", "payroll_schedule": "weekly", "payroll_firstPayPeriodID": "6580ce4a3808d60023b4e412" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "1e2wu23273238c22ea2" }, "first_name": { "type": "string", "example": "Richard" }, "last_name": { "type": "string", "example": "Hendricks" }, "email": { "type": "string", "example": "richard@piedpiper.com" }, "business_name": { "type": "string", "example": "Pied Piper" }, "business_address": { "type": "string", "example": "1 Market St." }, "business_city": { "type": "string", "example": "San Francisco" }, "business_state": { "type": "string", "example": "CA" }, "business_zip": { "type": "string", "example": "94110" }, "business_phone": { "type": "string", "example": "2025550151" }, "mail_address": { "type": "string", "example": "1 Market St." }, "mail_city": { "type": "string", "example": "San Francisco" }, "mail_state": { "type": "string", "example": "CA" }, "mail_zip": { "type": "string", "example": "94110" }, "ssn": { "type": "string", "example": "22-333-4444" }, "ownership_percentage": { "type": "integer", "example": 25, "default": 0 }, "dob": { "type": "string", "example": "01/01/1990" }, "legal_structure": { "type": "string", "example": "ccorp" }, "job_title": { "type": "string", "example": "CEO" }, "address": { "type": "string", "example": "1 Ferry Building" }, "city": { "type": "string", "example": "San francisco" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": "94105" }, "payroll_firstCheckDate": { "type": "string", "example": "2024-08-30" }, "payroll_schedule": { "type": "string", "example": "weekly" }, "payroll_firstPayPeriodID": { "type": "string", "example": "6580ce4a3808d60023b4e412" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No user with this company ID exists", "code": 4 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No user with this company ID exists" }, "code": { "type": "integer", "example": 4, "default": 0 } } } } } } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "curl", "code": { "companyID": "1e2wu23273238c22ea2", "first_name": "Richard", "last_name": "Hendricks", "email": "richard@piedpiper.com", "business_name": "Pied Piper", "business_address": "1 Market St.", "business_city": "San Francisco", "business_state": "CA", "business_zip": "94110", "business_phone": "2025550151", "mail_address": "1 Market St.", "mail_city": "San Francisco", "mail_state": "CA", "mail_zip": "94110", "ssn": "22-333-4444", "ownership_percentage": 25, "dob": "01/01/1990", "legal_structure": "ccorp", "job_title": "CEO", "address": "1 Ferry Building", "city": "San francisco", "state": "CA", "zip": "94105" }, "name": "EXAMPLE REQUEST" } ], "samples-languages": ["curl"] } }, "get": { "summary": "Get All Company Information", "description": "Get information for all companies under a partner.", "operationId": "get-all-company-information", "x-fern-sdk-group-name": "companies", "x-fern-sdk-method-name": "list", "parameters": [ { "name": "partnerID", "in": "query", "description": "PartnerID of the Zeal Partner", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "business_name": "Coca-Cola", "companyID": "123456890", "status": "migration_pending", "business_ein": "1234567890" }, { "business_name": "Pepsi", "companyID": "0987654321", "status": "live", "business_ein": "1234567890" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "business_name": { "type": "string", "example": "Coca-Cola" }, "companyID": { "type": "string", "example": "123456890" }, "status": { "type": "string", "example": "migration_pending" }, "business_ein": { "type": "string", "example": "1234567890" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No Zeal Partner with this partnerID exists", "code": 7 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No Zeal Partner with this partnerID exists" }, "code": { "type": "integer", "example": 7, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/companies/onboard": { "get": { "summary": "Get Company Onboarding Link", "description": "Get a link to Zeal's web-based company onboarding.", "operationId": "get-company-onboarding-link", "x-fern-sdk-group-name": "companies", "x-fern-sdk-method-name": "getOnboardingLink", "parameters": [ { "name": "partnerID", "in": "query", "description": "PartnerID of the Zeal Partner", "required": true, "schema": { "type": "string" } }, { "name": "base_url", "in": "query", "description": "The Base URL is the URL Zeal will redirect the employer to after completion of the company onboarding flow. You may include a custom Base URL in this field. Otherwise, by default, Zeal will use the Base URL found in the admin dashboard.", "schema": { "type": "string" } }, { "name": "webhook_correlation_id", "in": "query", "description": "Provide your own ID, string, etc. to include in the webhook payload. Zeal will include this in the webhook we send you after the company onboards.", "schema": { "type": "string" } }, { "name": "companyID", "in": "query", "description": "The company ID can be optionally passed to generate a link that will take your company to the current step, and not the first step, of the onboarding process.", "schema": { "type": "string" } }, { "name": "company_type", "in": "query", "description": "Mark your company as \"all\" (employees and contractors) or \"contractor_only\" to limit company's scope to 1099 contractors.", "schema": { "type": "string", "enum": [ "all", "contractor_only" ], "default": "all" } }, { "name": "skip_migration", "in": "query", "description": "If true, Zeal will skip migrating payroll information from the company's old payroll provider. **Note: please confirm with the company that migration is not necessary. Failure to migrate old records may impact tax reporting and filing.**", "schema": { "type": "boolean", "default": false } }, { "name": "product_type", "in": "query", "description": "The Zeal product type for the onboarding link. Only used when `companyID` is not provided; defaults to the partner's configured product type, or `payroll`.", "schema": { "type": "string", "enum": [ "payroll", "onboarding_only" ] } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": "https://payroll.your-domain.com/employeronboard/10983755744920193854758300657020834" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "string", "example": "https://payroll.your-domain.com/employeronboard/10983755744920193854758300657020834" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No Zeal Partner with this partner ID exists.", "code": 7 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No Zeal Partner with this partner ID exists." }, "code": { "type": "integer", "example": 7, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/companies/bank": { "post": { "summary": "Create Company Bank Account", "description": "Creates a bank account for the specified company.", "operationId": "create-company-bank-account", "x-fern-sdk-group-name": "companies", "x-fern-sdk-method-name": "createBankAccount", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "account_number", "routing_number"], "properties": { "companyID": { "type": "string", "description": "ID of the company." }, "account_number": { "type": "string", "description": "Account number of the Company Bank Account." }, "routing_number": { "type": "string", "description": "Routing number of the Company Bank Account." } } }, "examples": { "Request Example": { "value": { "account_number": "12345678", "routing_number": "021000021", "companyID": "182bb035e9ad422238c5e2cb386e19dd" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "182bb035e9ad422238c5e2cb386e19dd", "account_number": "12345678", "routing_number": "021000021" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "182bb035e9ad422238c5e2cb386e19dd" }, "account_number": { "type": "string", "example": "12345678" }, "routing_number": { "type": "string", "example": "021000021" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Routing number is invalid", "status": 400, "code": 56 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Routing number is invalid" }, "status": { "type": "integer", "example": 400, "default": 0 }, "code": { "type": "integer", "example": 56, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/companies/microdeposits/trigger": { "post": { "summary": "Trigger Micro-Deposits", "description": "Trigger Micro-deposits in order to verify a company bank account.", "operationId": "trigger-microdeposits", "x-fern-sdk-group-name": "companies", "x-fern-sdk-method-name": "triggerMicrodeposits", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID"], "properties": { "companyID": { "type": "string", "description": "ID of the company." } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "data": [ { "message": "Microdeposits sent, expect to receive in 2-3 business days" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Microdeposits sent, expect to receive in 2-3 business days" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No user with this company ID exists", "code": 4 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No user with this company ID exists" }, "code": { "type": "integer", "example": 4, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/companies/microdeposits/verify": { "post": { "summary": "Verify Microdeposit Values", "description": "Submit Microdeposit values in order to verify a company bank account.", "operationId": "verify-microdeposit-values", "x-fern-sdk-group-name": "companies", "x-fern-sdk-method-name": "verifyMicrodeposits", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "deposits"], "properties": { "companyID": { "type": "string", "description": "companyID of the company" }, "deposits": { "type": "array", "description": "Array of microdeposit values", "items": { "type": "string" } } } }, "examples": { "Request Example": { "value": { "companyID": "182bb035e9ad41bea8c5e2cb386e19dd", "deposits": ["1", "1"] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "message": "Microdeposits successfully verified" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Microdeposits successfully verified" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Value 1 (or 2) not correct", "code": 47 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Value 1 (or 2) not correct" }, "code": { "type": "integer", "example": 47, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/companies/authorization_documents": { "get": { "summary": "Get Company Authorization Documents", "description": "Fetch and view Company Authorization Documents.", "operationId": "get-company-authorization-documents", "x-fern-sdk-group-name": "companies", "x-fern-sdk-method-name": "getAuthorizationDocuments", "parameters": [ { "name": "companyID", "in": "query", "description": "companyID of the company", "required": true, "schema": { "type": "string" } }, { "name": "document_key", "in": "query", "description": "type of the Authorization Document. Accepts 8655, 2848, or all for all document types.", "required": true, "schema": { "type": "string", "enum": ["8655", "2848", "all"] } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "companyID": "1b5n28nrideucd24", "type": "8655", "description": "2023 Wage and Tax Statement (Form W2)", "link": "https://example-documents.s3.amazonaws.com/1b5n28nrideucd24-201-345890-document" }, { "companyID": "1b5n28nrideucd24", "type": "2848", "description": "2023 Corrected Wage and Tax Statement (Form W2C)", "link": "https://example-documents.s3.amazonaws.com/1b5n28nrideucd24-2019-W2C-1234567890-document" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "companyID": { "type": "string", "example": "1b5n28nrideucd24" }, "type": { "type": "string", "example": "8655" }, "description": { "type": "string", "example": "2023 Wage and Tax Statement (Form W2)" }, "link": { "type": "string", "example": "https://example-documents.s3.amazonaws.com/1b5n28nrideucd24-201-345890-document" } } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Bad Request": { "value": { "success": false, "errors": [ { "message": "No user with this company ID exists", "code": 4 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No user with this company ID exists" }, "code": { "type": "integer", "example": 4, "default": 0 } } } } } } } } } }, "deprecated": false }, "post": { "summary": "Sign Company Authorization Documents", "description": "Sign Authorization Documents necessary to onboard a company.", "operationId": "create-company-authorization-documents", "x-fern-sdk-group-name": "companies", "x-fern-sdk-method-name": "createAuthorizationDocuments", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "document_key", "signature"], "properties": { "companyID": { "type": "string", "description": "companyID of the company" }, "document_key": { "type": "string", "description": "type of the Authorization Document. Accepts 8655, 2848, or all for all document types.", "enum": ["8655", "2848", "all"] }, "signature": { "type": "string", "description": "base64 signature to pass and sign authorization document(s)" } } }, "examples": { "Request Example": { "value": { "companyID": "238cc39eui4xc873kej94", "document_key": "8655", "signature": "WmVhbA==" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "message": "Document successfully signed" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Document successfully signed" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Invalid documentKey", "code": 17 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid documentKey" }, "code": { "type": "integer", "example": 17, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/companies/onboardCompany": { "post": { "summary": "Set Company Onboarded Status to True", "description": "Sets a Company to onboarded if all requirements are met.", "operationId": "set-company-status-to-onboarded", "x-fern-sdk-group-name": "companies", "x-fern-sdk-method-name": "setStatusToOnboarded", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID"], "properties": { "companyID": { "type": "string", "description": "companyID of the company" } } }, "examples": { "Request Example": { "value": { "companyID": "12349eee40588c3948e312ww" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "message": "company has been successfully onboarded" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "company has been successfully onboarded" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Company has already been onboarded", "code": 30 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Company has already been onboarded" }, "code": { "type": "integer", "example": 30, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/provider-accounts/balances": { "get": { "summary": "Get Reserve Balance", "description": "", "operationId": "get-provider-balance", "x-fern-sdk-group-name": "providerAccounts", "x-fern-sdk-method-name": "getBalance", "parameters": [ { "name": "companyID", "in": "query", "description": "Zeal company ID", "required": true, "schema": { "type": "string" } }, { "name": "account_type", "in": "query", "description": "Type of reserve account. Can be: `reserve` or `direct_pay_reserve`", "schema": { "type": "string" } }, { "name": "start_at", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 25 } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "companyID": "7b11e9d6275c429f2a8361c5b47a2b9", "providerAccountID": "5d08b21f63784290c58a2d06128f4d75", "account_type": "reserve", "available_balance": 100, "current_balance": 100, "status": "open" } ], "meta": { "next": null, "previous": null } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "companyID": { "type": "string", "example": "7b11e9d6275c429f2a8361c5b47a2b9" }, "providerAccountID": { "type": "string", "example": "5d08b21f63784290c58a2d06128f4d75" }, "account_type": { "type": "string", "example": "reserve" }, "available_balance": { "type": "integer", "example": 100, "default": 0 }, "current_balance": { "type": "integer", "example": 100, "default": 0 }, "status": { "type": "string", "example": "open" } } } }, "meta": { "type": "object", "properties": { "next": {}, "previous": {} } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Contractor Payment with this payment ID does not exist", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor Payment with this payment ID does not exist" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/customer-accounts": { "post": { "summary": "Create Customer Account", "description": "", "operationId": "create-customer-account", "x-fern-sdk-group-name": "customerAccounts", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "code", "business_name"], "properties": { "companyID": { "type": "string", "description": "ID of the Company." }, "code": { "type": "string", "description": "Custom code to be associated with the customer code." }, "business_name": { "type": "string", "description": "Business Name of the customer account." }, "ein": { "type": "string", "description": "EIN of the customer account" }, "legal_structure": { "type": "string", "description": "Federal tax classification of the customer account entity", "enum": [ "ccorp", "corp", "estate", "foreign_entity", "llc", "llp", "lp", "nonprofit", "partnership", "scheme", "scorp", "soleprop", "trust." ] }, "phone": { "type": "string", "description": "Phone number of the customer account" }, "email": { "type": "string", "description": "Business email of the customer account" }, "business_address": { "type": "string", "description": "Street address of the customer account" }, "business_city": { "type": "string", "description": "City of the customer account" }, "business_state": { "type": "string", "description": "State of the customer account" }, "business_zip": { "type": "string", "description": "Zip code of the customer account" }, "business_owner": { "type": "object", "description": "Business owner of the customer account", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "ssn": { "type": "string" }, "dob": { "type": "string" }, "email": { "type": "string" }, "title": { "type": "string" }, "ownership_percentage": { "type": "integer", "format": "int32" }, "owner_type": { "type": "string", "enum": ["authorized_signer", "beneficial_owner"] }, "address": { "type": "string" }, "address_line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" } } } } }, "examples": { "Request Example": { "value": { "code": "customer-code10", "companyID": "dzxzll3b45rtrtrtad41c98bbc2b4d566388a44", "business_name": "Hooli" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false }, "get": { "summary": "Get All Customer Accounts", "description": "", "operationId": "get-all-customer-accounts", "x-fern-sdk-group-name": "customerAccounts", "x-fern-sdk-method-name": "list", "parameters": [ { "name": "companyID", "in": "query", "description": "ID of the Company.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/customer-accounts/{id}": { "patch": { "summary": "Update Customer Account", "description": "", "operationId": "update-customer-account", "x-fern-sdk-group-name": "customerAccounts", "x-fern-sdk-method-name": "update", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID"], "properties": { "companyID": { "type": "string", "description": "ID of the Company." }, "ein": { "type": "string", "description": "EIN of the customer account" }, "legal_structure": { "type": "string", "description": "Federal tax classification of the customer account entity", "enum": [ "ccorp", "corp", "estate", "foreign_entity", "llc", "llp", "lp", "nonprofit", "partnership", "scheme", "scorp", "soleprop", "trust." ] }, "phone": { "type": "string", "description": "Phone number of the customer account" }, "email": { "type": "string", "description": "Business email of the customer account" }, "business_address": { "type": "string", "description": "Street address of the customer account" }, "business_city": { "type": "string", "description": "City of the customer account" }, "business_state": { "type": "string", "description": "State of the customer account" }, "business_zip": { "type": "string", "description": "Zip code of the customer account" }, "code": { "type": "string", "description": "Custom code to be associated with the customer code." }, "status": { "type": "string", "description": "Status of the customer account", "enum": ["live"] }, "business_owner": { "type": "object", "description": "Business owner of the customer account", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "ssn": { "type": "string" }, "dob": { "type": "string" }, "email": { "type": "string" }, "title": { "type": "string" }, "ownership_percentage": { "type": "integer", "format": "int32" }, "owner_type": { "type": "string", "enum": ["authorized_signer", "beneficial_owner"] }, "address": { "type": "string" }, "address_line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" } } } } }, "examples": { "Request Example": { "value": { "companyID": "dzxzll3b45rtrtrtad41c98bbc2b4d566388a44", "code": "customer-code-2" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/customer-accounts/onboard": { "post": { "summary": "Generate Customer Account Onboarding Link", "description": "", "operationId": "generate-customer-account-onboarding-link", "x-fern-sdk-group-name": "customerAccounts", "x-fern-sdk-method-name": "generateOnboardingLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "customerAccountID"], "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "customerAccountID": { "type": "string", "description": "ID of the customer account" }, "profileInfo": { "type": "boolean", "description": "Flag to include profile info step of the onboarding flow", "default": true }, "bankInfo": { "type": "boolean", "description": "Flag to include bank info (funding source) step of the onboarding flow", "default": true } } }, "examples": { "Request Example": { "value": { "companyID": "f8c887b155574458971236fef2149c9a", "customerAccountID": "3f686bf64c144a53bb6e622197546227" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": { "link": "https://app.zeal.com/customer-account-onboard?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ.eyJjb21wYW55SUQiOiIyNGI1YjI5ZjA3OTI0ODQwYjExOWMzNGMxMzU4OTQwYyIsInBhcnRuZXJJRCI6ImMxMzNlZWQyYzliODQxOWJhMmYyMmRjMDU5YmQ0NDVhIiwiY3VzdG9tZXJBY2NvdW50SUQiOiIzMTE4ZGE5ZmMxNTQ0NGUyOTZlYTFiZTgyNDJhZTg3ZCIsInRlc3RNb2RlIjp0cnVlLCJlbnYiOiJsb2NhbCIsInN0YWdlcyI6eyJwcm9maWxlX2luZm8iOnRydWUsImZ1bmRpbmdfc291cmNlIjp0cnVlfSwiZXhwIjoxNzI4NTg5MzQ5LCJpYXQiOjE3MjcyOTMzNDl9.sAM5tuBjPFmwgh46hkJe1zJD2DLJJMGoyqwertyuiop" }, "success": true } } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "link": { "type": "string", "example": "https://app.zeal.com/customer-account-onboard?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ.eyJjb21wYW55SUQiOiIyNGI1YjI5ZjA3OTI0ODQwYjExOWMzNGMxMzU4OTQwYyIsInBhcnRuZXJJRCI6ImMxMzNlZWQyYzliODQxOWJhMmYyMmRjMDU5YmQ0NDVhIiwiY3VzdG9tZXJBY2NvdW50SUQiOiIzMTE4ZGE5ZmMxNTQ0NGUyOTZlYTFiZTgyNDJhZTg3ZCIsInRlc3RNb2RlIjp0cnVlLCJlbnYiOiJsb2NhbCIsInN0YWdlcyI6eyJwcm9maWxlX2luZm8iOnRydWUsImZ1bmRpbmdfc291cmNlIjp0cnVlfSwiZXhwIjoxNzI4NTg5MzQ5LCJpYXQiOjE3MjcyOTMzNDl9.sAM5tuBjPFmwgh46hkJe1zJD2DLJJMGoyqwertyuiop" } } }, "success": { "type": "boolean", "example": true, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Customer account with this ID does not exist", "code": 17 } ], "success": false } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Customer account with this ID does not exist" }, "code": { "type": "integer", "example": 17, "default": 0 } } } }, "success": { "type": "boolean", "example": false, "default": true } } } } } } }, "deprecated": false } }, "/customer-accounts/{customerAccountID}/setOnboardedStatusToTrue": { "post": { "summary": "Set Customer Account Onboarded To true", "description": "", "operationId": "set-customer-account-onboarded-to-true", "x-fern-sdk-group-name": "customerAccounts", "x-fern-sdk-method-name": "setOnboardedToTrue", "parameters": [ { "name": "customerAccountID", "in": "path", "description": "Customer Account ID", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "Company ID" } } }, "examples": { "Request Example": { "value": { "companyID": "12349eee40588c3948e312bb" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": { "business_name": "Boboddy", "ein": "567877898", "legal_structure": "corp", "phone": "6789276673", "email": "boboddy@zeal.com", "business_address": "1 Ferry Building", "business_city": "San Francisco", "business_state": "CA", "business_zip": "94105", "code": "customer-code43", "company_id": "12349eee40588c3948e312ww", "customer_account_id": "43349ebe40588c3948e312ab", "partner_id": "12349eee40588c3948e312bb", "status": "initial_onboarding", "business_owner": { "first_name": "Bob", "last_name": "Hunt", "email": "boboddy@zeal.com", "ssn": "234567890", "dob": "1990-01-01", "title": "CEO", "ownership_percentage": 47, "owner_type": "authorized_signer", "address": "1 Ferry Building", "city": "San Francisco", "state": "CA", "zip": "94105" }, "onboarded": true }, "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "business_name": { "type": "string", "example": "Boboddy" }, "ein": { "type": "string", "example": "567877898" }, "legal_structure": { "type": "string", "example": "corp" }, "phone": { "type": "string", "example": "6789276673" }, "email": { "type": "string", "example": "boboddy@zeal.com" }, "business_address": { "type": "string", "example": "1 Ferry Building" }, "business_city": { "type": "string", "example": "San Francisco" }, "business_state": { "type": "string", "example": "CA" }, "business_zip": { "type": "string", "example": "94105" }, "code": { "type": "string", "example": "customer-code43" }, "company_id": { "type": "string", "example": "12349eee40588c3948e312ww" }, "customer_account_id": { "type": "string", "example": "43349ebe40588c3948e312ab" }, "partner_id": { "type": "string", "example": "12349eee40588c3948e312bb" }, "status": { "type": "string", "example": "initial_onboarding" }, "business_owner": { "type": "object", "properties": { "first_name": { "type": "string", "example": "Bob" }, "last_name": { "type": "string", "example": "Hunt" }, "email": { "type": "string", "example": "boboddy@zeal.com" }, "ssn": { "type": "string", "example": "234567890" }, "dob": { "type": "string", "example": "1990-01-01" }, "title": { "type": "string", "example": "CEO" }, "ownership_percentage": { "type": "integer", "example": 47, "default": 0 }, "owner_type": { "type": "string", "example": "authorized_signer" }, "address": { "type": "string", "example": "1 Ferry Building" }, "city": { "type": "string", "example": "San Francisco" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": "94105" } } }, "onboarded": { "type": "boolean", "example": true, "default": true } } }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Bank account not verified", "code": 13, "status": 400, "correlationId": "d78e712d-1ebe-4a9a-9537-b6abf1dc9853" } ], "success": false, "testMode": false } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Bank account not verified" }, "code": { "type": "integer", "example": 13, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "d78e712d-1ebe-4a9a-9537-b6abf1dc9853" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } } }, "deprecated": false } }, "/customer-accounts/{id}/funding-sources": { "post": { "summary": "Create Funding Source", "description": "", "operationId": "create-funding-source", "x-fern-sdk-group-name": "customerAccounts", "x-fern-sdk-method-name": "createFundingSource", "parameters": [ { "name": "id", "in": "path", "description": "ID of the customer account", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "account_number", "account_type", "routing_number", "companyID", "customerAccountID" ], "properties": { "account_number": { "type": "string", "description": "Account number of the bank accout." }, "account_type": { "type": "string", "description": "Type of the bank account (Accepts \"checking\" or \"savings\")", "enum": ["checking", "savings"] }, "routing_number": { "type": "string", "description": "Routing number of the bank account." }, "companyID": { "type": "string", "description": "ID of the Company" }, "customerAccountID": { "type": "string", "description": "ID of the Customer Account." } } }, "examples": { "Request Example": { "value": { "account_number": "849201923", "account_type": "checking", "companyID": "dzxzll3b45rtrtrtad41c98bbc2b4d566388a44", "customerAccountID": "23l9ada7ce49eb1496c1cb953e8c", "routing_number": "314074269" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/customer-accounts/{customerAccountID}/trigger-micro-deposits": { "post": { "summary": "Trigger Microdeposits", "description": "", "operationId": "trigger-ca-microdeposits", "x-fern-sdk-group-name": "customerAccounts", "x-fern-sdk-method-name": "triggerCaMicrodeposits", "parameters": [ { "name": "customerAccountID", "in": "path", "description": "ID of the Customer Account.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID"], "properties": { "companyID": { "type": "string", "description": "ID of the company" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/customer-accounts/{customerAccountID}/verify-micro-deposits": { "post": { "summary": "Verify Microdeposits", "description": "", "operationId": "verify-ca-microdeposits", "x-fern-sdk-group-name": "customerAccounts", "x-fern-sdk-method-name": "verifyMicrodeposits", "parameters": [ { "name": "customerAccountID", "in": "path", "description": "ID of the Customer Account.", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "deposits"], "properties": { "companyID": { "type": "string", "description": "ID of the Company." }, "deposits": { "type": "array", "description": "Array of microdeposit values.", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "companyID": "dzxzll3b45rtrtrtad41c98bbc2b4d566388a44", "deposits": ["1", "2"] } } }, "schema": { "type": "object", "properties": { "companyID": { "type": "string", "example": "dzxzll3b45rtrtrtad41c98bbc2b4d566388a44" }, "deposits": { "type": "array", "items": { "type": "string", "example": "1" } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/customer-accounts/{customerAccountID}": { "get": { "summary": "Get Customer Account", "description": "", "operationId": "get-customer-account", "x-fern-sdk-group-name": "customerAccounts", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "customerAccountID", "in": "path", "description": "ID of the Customer Account.", "schema": { "type": "string" }, "required": true }, { "name": "companyID", "in": "query", "description": "ID of the Company.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/taxableLocations": { "post": { "summary": "Resolve Taxable Location", "description": "Create or get a taxable location.", "operationId": "resolve-taxable-location", "x-fern-sdk-group-name": "taxableLocations", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["street1", "city"], "properties": { "street1": { "type": "string", "description": "Address Line 1 (Street Name)" }, "street2": { "type": "string", "description": "Address Line 2 (Apt/Suite). Empty string if not applicable" }, "city": { "type": "string", "description": "City/Subdivision" }, "state": { "type": "string", "description": "US State or Territory (2-letter abbreviation). Used when `country` is `US`. Optional for Canadian addresses." }, "zip": { "type": "string", "description": "ZIP code (5 digits). Used when `country` is `US`. Optional for Canadian addresses." }, "country": { "type": "string", "description": "Country for the address. One of `US` or `CA`. Defaults to `US` if omitted. **NOTE: `CA` is only applicable for Canadian Payroll (Early Access)**", "enum": ["US", "CA"] }, "province": { "type": "string", "description": "Canadian province/territory (2-letter abbreviation). Used when `country` is `CA`. **NOTE: Only applicable for Canadian Payroll (Early Access)**", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "NT", "NU", "ON", "PE", "QC", "SK", "YT" ] }, "postal_code": { "type": "string", "description": "Canadian postal code. Used when `country` is `CA`. **NOTE: Only applicable for Canadian Payroll (Early Access)**" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "taxableLocationID": "609ffdf81a5f9c4c10b0c443", "street1": "1 Ferry Building", "street2": "", "city": "San Francisco", "state": "CA", "zip": "94111", "is_suitable_for_taxation": true, "is_po_box": false, "is_state_mismatch": false, "is_armed_forces_address": false, "is_foreign_address": false, "is_deliverable": true } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "taxableLocationID": { "type": "string", "example": "609ffdf81a5f9c4c10b0c443" }, "street1": { "type": "string", "example": "1 Ferry Building" }, "street2": { "type": "string", "example": "" }, "city": { "type": "string", "example": "San Francisco" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": "94111" }, "is_suitable_for_taxation": { "type": "boolean", "example": true, "default": true }, "is_po_box": { "type": "boolean", "example": false, "default": true }, "is_state_mismatch": { "type": "boolean", "example": false, "default": true }, "is_armed_forces_address": { "type": "boolean", "example": false, "default": true }, "is_foreign_address": { "type": "boolean", "example": false, "default": true }, "is_deliverable": { "type": "boolean", "example": true, "default": true } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "The address provided is not suitable for taxation.", "code": 34 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "The address provided is not suitable for taxation." }, "code": { "type": "integer", "example": 34, "default": 0 } } } } } } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "curl", "code": { "street1": "1 Ferry Building", "street2": "", "city": "San Francisco", "state": "CA", "zip": "94111" } } ], "samples-languages": ["curl"] } }, "get": { "summary": "Get Taxable Location by ID", "description": "Get a taxable location by ID.", "operationId": "retrieve-taxable-location-by-id", "x-fern-sdk-group-name": "taxableLocations", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "taxableLocationID", "in": "query", "description": "The ID of an existing Taxable Location Object", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "taxableLocationID": "609ffdf81a5f9c4c10b0c443", "street1": "1 Ferry Building", "street2": "", "city": "San Francisco", "state": "CA", "zip": "94111", "is_suitable_for_taxation": true, "is_po_box": false, "is_state_mismatch": false, "is_armed_forces_address": false, "is_foreign_address": false, "is_deliverable": true } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "taxableLocationID": { "type": "string", "example": "609ffdf81a5f9c4c10b0c443" }, "street1": { "type": "string", "example": "1 Ferry Building" }, "street2": { "type": "string", "example": "" }, "city": { "type": "string", "example": "San Francisco" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": "94111" }, "is_suitable_for_taxation": { "type": "boolean", "example": true, "default": true }, "is_po_box": { "type": "boolean", "example": false, "default": true }, "is_state_mismatch": { "type": "boolean", "example": false, "default": true }, "is_armed_forces_address": { "type": "boolean", "example": false, "default": true }, "is_foreign_address": { "type": "boolean", "example": false, "default": true }, "is_deliverable": { "type": "boolean", "example": true, "default": true } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No Taxable Location with this taxableLocationID exists", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No Taxable Location with this taxableLocationID exists" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/workLocations": { "post": { "summary": "Create Work Location", "description": "Creates a Work Location for a company within Zeal.", "operationId": "create-work-location", "x-fern-sdk-group-name": "workLocations", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "taxableLocationID"], "properties": { "companyID": { "type": "string", "description": "The ID of an existing Company Object" }, "taxableLocationID": { "type": "string", "description": "The ID of an existing Taxable Locations Object" }, "name": { "type": "string", "description": "A name for the new Work Location" }, "work_site_id": { "type": "string", "description": "Optional custom Work Site ID for your own reporting purposes" } } }, "examples": { "Request Example": { "value": { "companyID": "1234567890", "taxableLocationID": "609ffdf81a5f9c4c10b0c443", "name": "SF Office", "zip": "94105", "work_site_id": "SF" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "1234567890", "workLocationID": "573hfjd39854fh32", "taxableLocationID": "609ffdf81a5f9c4c10b0c443", "name": "SF Office", "work_site_id": "SF" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "1234567890" }, "workLocationID": { "type": "string", "example": "573hfjd39854fh32" }, "taxableLocationID": { "type": "string", "example": "609ffdf81a5f9c4c10b0c443" }, "name": { "type": "string", "example": "SF Office" }, "work_site_id": { "type": "string", "example": "SF" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Failed to create Work Location: Error", "code": 60 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Failed to create Work Location: Error" }, "code": { "type": "integer", "example": 60, "default": 0 } } } } } } } } } }, "deprecated": false }, "get": { "summary": "Get Work Locations", "description": "Fetch Work Location(s) by company and/or specific parameters.", "operationId": "get-work-locations", "x-fern-sdk-group-name": "workLocations", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of the employer", "required": true, "schema": { "type": "string" } }, { "name": "workLocationID", "in": "query", "description": "Work Location ID of the object you're querying", "schema": { "type": "string" } }, { "name": "taxableLocationID", "in": "query", "description": "Taxable Location ID of the object(s) you are querying", "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "The array of US States (2 letter abbreviation) applicable to the objects that you are querying", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "work_site_id", "in": "query", "description": "ID assigned to the Work Location", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "workLocationID": "531fece70b6d0b5d29c9f352", "companyID": "1234567890", "taxableLocationID": "609ffdf81a5f9c4c10b0c443", "name": "Head Quarters", "work_site_id": "HQ" }, { "workLocationID": "54358gjhldf58094f", "companyID": "1234567890", "taxableLocationID": "789gfsd7892347c", "name": "Satellite Office Number 1", "work_site_id": "S1" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "workLocationID": { "type": "string", "example": "531fece70b6d0b5d29c9f352" }, "companyID": { "type": "string", "example": "1234567890" }, "taxableLocationID": { "type": "string", "example": "609ffdf81a5f9c4c10b0c443" }, "name": { "type": "string", "example": "Head Quarters" }, "work_site_id": { "type": "string", "example": "HQ" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Work Location(s) not found", "status": 400, "code": 58 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Work Location(s) not found" }, "status": { "type": "integer", "example": 400, "default": 0 }, "code": { "type": "integer", "example": 58, "default": 0 } } } } } } } } } }, "deprecated": false }, "patch": { "summary": "Update Work Location", "description": "Update's a Work Location in Zeal.", "operationId": "update-work-location", "x-fern-sdk-group-name": "workLocations", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "workLocationID"], "properties": { "companyID": { "type": "string", "description": "The ID of an existing Company Object" }, "workLocationID": { "type": "string", "description": "The ID of an existing Work Location Object" }, "name": { "type": "string", "description": "A name for the new Work Location" }, "work_site_id": { "type": "string", "description": "Optional Custom Work Site ID for your own reporting purposes" } } }, "examples": { "Request Example": { "value": { "companyID": "24b5b29f07924840b119c34d1351940c", "workLocationID": "624c898d94de2a0034869f8b", "name": "Miami Office", "work_site_id": "MIA" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "1234567890", "workLocationID": "531fece70b6d0b5d29c9f352", "taxableLocationID": "609ffdf81a5f9c4c10b0c443", "name": "Miami Office", "work_site_id": "MIA" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "1234567890" }, "workLocationID": { "type": "string", "example": "531fece70b6d0b5d29c9f352" }, "taxableLocationID": { "type": "string", "example": "609ffdf81a5f9c4c10b0c443" }, "name": { "type": "string", "example": "Miami Office" }, "work_site_id": { "type": "string", "example": "MIA" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Invalid WorkLocation ID", "status": 400, "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid WorkLocation ID" }, "status": { "type": "integer", "example": 400, "default": 0 }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/employees": { "post": { "summary": "Create Employee", "description": "Create a W-2 employee.", "operationId": "create-employee", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "new_employees"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer (you can access your companyID on the Zeal dashboard)" }, "new_employees": { "type": "array", "description": "List of [The Employee Object](ref:the-employee-object)", "items": { "properties": { "email": { "type": "string", "description": "Email of Employee" }, "first_name": { "type": "string", "description": "First Name of Employee" }, "last_name": { "type": "string", "description": "Last Name of Employee" }, "title": { "type": "string", "description": "Title of employee" }, "default_pay_schedule": { "type": "string", "description": "You will still be in charge of setting the reporting periods and check dates, but this field helps Zeal determine at what rate to tax the employee. You must choose one of the following pay schedules for this employee: `daily`, `weekly` (you want to send 1 check per week),`biweekly` (you want to send 1 check every other week), `semimonthly` (you want to send 2 checks per month), `monthly` (you want to send 1 check per month)" }, "default_wage": { "type": "number", "description": "Default wage of Employee", "format": "float" }, "workLocationID": { "type": "string", "description": "ID of Work Location Object - working_state is derived from workLocationID" }, "overtime_rate": { "type": "number", "description": "Rate for overtime pay. Default OT rate is 1.5 times base wage.", "default": 1.5, "format": "float" }, "doubletime_rate": { "type": "number", "description": "Rate for double time pay. Default DT rate is 2 times base wage.", "default": 2, "format": "float" }, "start_date": { "type": "string", "description": "Start Date of employee (also known as hire date). This is the first day that this employee works in return for wages and is formatted as a date. Zeal uses this date for new hire reporting. By default, the date is set to tomorrow's date.", "format": "date" }, "dob": { "type": "string", "description": "Date of birth of employee (formatted as YYYY-MM-DD)", "format": "date" }, "ssn": { "type": "string", "description": "Social Security Number of employee" }, "phone_number": { "type": "string", "description": "Phone Number of employee" }, "address": { "type": "string", "description": "Residential Street Address of employee" }, "address_line2": { "type": "string", "description": "Residential Street Address Line 2 of Employee" }, "city": { "type": "string", "description": "Residential City of employee" }, "state": { "type": "string", "description": "Residential State of employee" }, "zip": { "type": "string", "description": "Residential Zip of employee" }, "country": { "type": "string", "description": "Country of the employee residence. One of `US` or `CA`. Defaults to `US`. **NOTE: `CA` is only applicable for Canadian Payroll (Early Access)**", "enum": ["US", "CA"] }, "province": { "type": "string", "description": "Canadian province/territory of the employee residence (2-letter abbreviation). Used when `country` is `CA`. **NOTE: Only applicable for Canadian Payroll (Early Access)**", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "NT", "NU", "ON", "PE", "QC", "SK", "YT" ] }, "postal_code": { "type": "string", "description": "Canadian postal code of the employee residence. Used when `country` is `CA`. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "sin": { "type": "string", "description": "Canadian Social Insurance Number (SIN). Accepts `123456789` or `123-456-789`. Used when `country` is `CA`. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "is_943": { "type": "boolean", "description": "Set to true if the employee is a farmworker", "default": false }, "is_scheduleH": { "type": "boolean", "description": "Set to true if the employee falls under the Schedule H category as a household employee", "default": false }, "external_id": { "type": "string", "description": "External ID for an employee that comes from an employer's HR or other internal system" }, "metadata": { "type": "object" }, "work_week_start": { "type": "string", "description": "ISO-8601 date depicting the beginning of the work week when the employee begins work **NOTE: Only applicable for FLSA Overtime Policy**" }, "is_salary": { "type": "boolean", "description": "Set to true if the employee is salaried" }, "salary": { "type": "number", "description": "The annual salary amount of the employee", "format": "float" }, "is_regular": { "type": "boolean", "description": "Set to true if the employee should be included in 'on-cycle' payroll runs" }, "soc_code": { "type": "string", "description": "The Standard Occupational Classification (SOC) code for the employee, in NN-NNNN format" } }, "required": [ "email", "first_name", "last_name", "title", "default_pay_schedule", "default_wage", "workLocationID" ], "type": "object" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "employeeID": "1234567890", "companyID": "1b5n28nrideucd24", "onboarded": false, "email": "erlich@zeal.com", "first_name": "erlich", "last_name": "bachman", "default_pay_schedule": "daily", "title": "Brand Ambassador", "employment_status": "live", "term_date": null, "start_date": "2019-11-01", "working_state": "CA", "workLocationID": "531fece70b6d0b5d29c9f352", "default_wage": 20, "default_ot_wage": 32, "default_dt_wage": 42, "dob": null, "ssn": "182563748", "phone_number": "8716738956", "address": null, "address_line2": null, "city": null, "state": null, "zip": null, "is_943": false, "is_scheduleH": false, "is_salary": true, "salary": 100000, "paycard_requested": false, "paycard_enabled": false, "kyc_status": "approved", "ssn_verification_status": null, "soc_code": "41-3011" }, { "employeeID": "974675839", "companyID": "1b5n28nrideucd24", "onboarded": false, "email": "richard@zeal.com", "first_name": "richard", "last_name": "hendricks", "default_pay_schedule": "biweekly", "title": "Caterer", "employment_status": "live", "term_date": null, "start_date": "2019-11-01", "working_state": "AZ", "workLocationID": "531fece70b6d0b5d29c9f352", "default_wage": 25, "default_ot_wage": 37.5, "default_dt_wage": 50, "dob": null, "ssn": null, "phone_number": null, "address": null, "address_line2": null, "city": null, "state": null, "zip": null, "is_salary": false, "salary": null, "paycard_requested": false, "paycard_enabled": false, "kyc_status": null, "ssn_verification_status": null, "soc_code": "35-9011" }, { "employeeID": "0987654321", "companyID": "1b5n28nrideucd24", "onboarded": false, "email": "peter@zeal.com", "first_name": "peter", "last_name": "gregory", "default_pay_schedule": "weekly", "title": "Staffing Manager", "employment_status": "live", "term_date": null, "start_date": "2019-11-01", "working_state": "AL", "workLocationID": "531fece70b6d0b5d29c9f352", "default_wage": 23, "default_ot_wage": 34.5, "default_dt_wage": 46, "dob": null, "ssn": null, "phone_number": null, "address": null, "address_line2": null, "city": null, "state": null, "zip": null, "is_salary": true, "salary": 100000, "paycard_requested": false, "paycard_enabled": false, "kyc_status": null, "ssn_verification_status": null, "soc_code": "11-9199" } ] } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "error": true, "message": "No companyID in the request body", "code": 3 } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "error": { "type": "boolean", "example": true, "default": true }, "message": { "type": "string", "example": "No companyID in the request body" }, "code": { "type": "integer", "example": 3, "default": 0 } } } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "curl", "code": { "companyID": "1b5n28nrideucd24", "new_employees": [ { "email": "erlich@zeal.com", "first_name": "Erlich", "last_name": "Bachman", "default_pay_schedule": "daily", "title": "Brand Ambassador", "start_date": "2019-11-01", "default_wage": 20, "overtime_rate": 1.6, "double_time_rate": 2.1, "workLocationID": "531fece70b6d0b5d29c9f352", "ssn": "182563748", "phone_number": "8716738956", "is_943": false, "is_scheduleH": false }, { "email": "richard@zeal.com", "first_name": "Richard", "last_name": "Hendricks", "default_pay_schedule": "biweekly", "title": "Caterer", "workLocationID": "531fece70b6d0b5d29c8f352", "start_date": "2019-11-01", "default_wage": 25, "is_943": true, "is_scheduleH": false }, { "email": "peter@zeal.com", "first_name": "Peter", "last_name": "Gregory", "workLocationID": "531fece72b6d0b5d29c9f352", "default_pay_schedule": "weekly", "title": "Staffing Manager", "start_date": "2019-11-01", "default_wage": 23, "is_943": true, "is_scheduleH": false } ] } } ], "samples-languages": ["curl"] } }, "patch": { "summary": "Update Employee Information", "description": "Update a specific employee record.", "operationId": "update-employee-information", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employee"], "properties": { "companyID": { "type": "string", "description": "Company ID of the employer." }, "employee": { "type": "object", "description": "Refer to [Employee](ref:the-employee-object)", "required": ["employeeID"], "properties": { "employeeID": { "type": "string", "description": "The ID of the Employee" }, "first_name": { "type": "string", "description": "First name of the employee" }, "last_name": { "type": "string", "description": "Last name of the employee" }, "title": { "type": "string", "description": "Title of Employee" }, "dob": { "type": "string", "description": "Date of birth of employee (formatted as YYYY-MM-DD)", "format": "date" }, "employment_status": { "type": "string", "description": "The employment status of the employee. Accepts terminated, live, on leave" }, "benefits_class": { "type": "string", "description": "Class of employee used for Health Insurance eligibility. **NOTE: Only applicable if opted into Health Insurance (Early Access).** All benefit classes are available, only select and prompt benefit updates for classes you have confirmed with EVCO.", "enum": [ "Full-Time", "Part Time", "Executive", "VP", "IT Staff", "Eligible - No ER Contribution", "Ineligible" ] }, "email": { "type": "string", "description": "Email address of the Employee" }, "workLocationID": { "type": "string", "description": "The ID of the work location of the employee" }, "address": { "type": "string", "description": "Residential Street Address of employee" }, "address_line2": { "type": "string", "description": "Residential Street Address Line 2 of Employee" }, "city": { "type": "string", "description": "Residential City of employee" }, "state": { "type": "string", "description": "Residential State of employee" }, "zip": { "type": "string", "description": "Residential Zip of employee" }, "country": { "type": "string", "description": "Country of the employee residence. One of `US` or `CA`. Defaults to `US`. **NOTE: `CA` is only applicable for Canadian Payroll (Early Access)**", "enum": ["US", "CA"] }, "province": { "type": "string", "description": "Canadian province/territory of the employee residence (2-letter abbreviation). Used when `country` is `CA`. **NOTE: Only applicable for Canadian Payroll (Early Access)**", "enum": [ "AB", "BC", "MB", "NB", "NL", "NS", "NT", "NU", "ON", "PE", "QC", "SK", "YT" ] }, "postal_code": { "type": "string", "description": "Canadian postal code of the employee residence. Used when `country` is `CA`. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "sin": { "type": "string", "description": "Canadian Social Insurance Number (SIN). Accepts `123456789` or `123-456-789`. Used when `country` is `CA`. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "phone_number": { "type": "string", "description": "Phone Number of employee" }, "start_date": { "type": "string", "description": "The starting date of the employee", "format": "date" }, "default_pay_schedule": { "type": "string", "description": "The pay schedule of the employee (daily, weekly, biweekly, semimonthly, monthly)" }, "default_wage": { "type": "number", "description": "Default wage of Employee", "format": "float" }, "default_ot_wage": { "type": "number", "description": "The wage for overtime pay. NOT a rate but a whole number representing the overtime wage.", "format": "float" }, "default_dt_wage": { "type": "number", "description": "The wage for doubletime pay. NOT a rate but a whole number representing the doubletime wage.", "format": "float" }, "ssn": { "type": "string", "description": "Social Security Number of employee" }, "term_date": { "type": "string", "description": "Date of employee termination", "format": "date" }, "salary_firstDate": { "type": "string", "description": "Date of the first salaried autopilot check for employee", "format": "date" }, "salary": { "type": "integer", "description": "Salary amount for autopilot", "format": "int32" }, "autopilot_on": { "type": "boolean", "description": "Determine whether or not autopilot is on or off to make employee salaried" }, "external_id": { "type": "string", "description": "External ID for an employee that comes from an employer's HR or other internal system" }, "metadata": { "type": "object", "description": "Employee metadata", "properties": {} }, "soc_code": { "type": "string", "description": "The Standard Occupational Classification (SOC) code for the employee, in NN-NNNN format" } } } } }, "examples": { "Request Example": { "value": { "employeeID": "1234567890", "companyID": "0987654321", "onboarded": true, "employment_status": "live", "term_date": null, "first_name": "erlich", "last_name": "bachman", "email": "erlich@zeal.com", "dob": "1999-12-04", "start_date": "2019-06-04", "title": "Brand Ambassador", "working_state": "CA", "workLocationID": "6247402f38756100224f0a52", "address": "320 Pancake Hollow Road", "address_line2": null, "city": "Highland", "state": "NY", "zip": "12528", "phone_number": "+18214370987", "default_pay_schedule": "weekly", "default_wage": 20, "default_ot_wage": 30, "default_dt_wage": 40, "ssn": "123456789", "is_943": true, "is_scheduleH": false, "is_salary": true, "salary": 100000, "external_id": "123456789" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "employeeID": "6196c0afa360c70024268b26", "companyID": "123441526234234ertys", "onboarded": false, "employment_status": "live", "benefits_class": "Full-Time", "term_date": null, "first_name": "Elrich", "last_name": "Bachmann", "email": "elrichbachmann@zeal.com", "dob": "1999-12-04", "start_date": "2019-06-04", "title": "Brand Ambassador", "working_state": "CA", "workLocationID": "531fece70b6d0b5d29c9f352", "address": "320 Pancake Hollow Road", "city": "Highland", "state": "NY", "zip": "12528", "phone_number": "8716738956", "default_pay_schedule": "daily", "default_wage": 20, "default_ot_wage": 32, "default_dt_wage": 42, "ssn": "087473892", "is_943": false, "is_scheduleH": false, "is_salary": true, "salary": 100000, "paycard_requested": false, "paycard_enabled": false, "kyc_status": null, "ssn_verification_status": null, "soc_code": "41-3011" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "employeeID": { "type": "string", "example": "6196c0afa360c70024268b26" }, "companyID": { "type": "string", "example": "123441526234234ertys" }, "onboarded": { "type": "boolean", "example": false, "default": true }, "employment_status": { "type": "string", "example": "live" }, "benefits_class": { "type": "string", "description": "Class of employee used for Health Insurance eligibility. **NOTE: Only applicable if opted into Health Insurance (Early Access).** All benefit classes are available, only select and prompt benefit updates for classes you have confirmed with EVCO.", "example": "Full-Time", "enum": [ "Full-Time", "Part Time", "Executive", "VP", "IT Staff", "Eligible - No ER Contribution", "Ineligible" ] }, "term_date": {}, "first_name": { "type": "string", "example": "Elrich" }, "last_name": { "type": "string", "example": "Bachmann" }, "email": { "type": "string", "example": "elrichbachmann@zeal.com" }, "dob": { "type": "string", "example": "1999-12-04" }, "start_date": { "type": "string", "example": "2019-06-04" }, "title": { "type": "string", "example": "Brand Ambassador" }, "working_state": { "type": "string", "example": "CA" }, "workLocationID": { "type": "string", "example": "531fece70b6d0b5d29c9f352" }, "address": { "type": "string", "example": "320 Pancake Hollow Road" }, "city": { "type": "string", "example": "Highland" }, "state": { "type": "string", "example": "NY" }, "zip": { "type": "string", "example": "12528" }, "phone_number": { "type": "string", "example": "8716738956" }, "default_pay_schedule": { "type": "string", "example": "daily" }, "default_wage": { "type": "integer", "example": 20, "default": 0 }, "default_ot_wage": { "type": "integer", "example": 32, "default": 0 }, "default_dt_wage": { "type": "integer", "example": 42, "default": 0 }, "ssn": { "type": "string", "example": "087473892" }, "is_943": { "type": "boolean", "example": false, "default": true }, "is_scheduleH": { "type": "boolean", "example": false, "default": true }, "is_salary": { "type": "boolean", "example": true, "default": true }, "salary": { "type": "integer", "example": 100000, "default": 0 }, "paycard_requested": { "type": "boolean", "example": false, "default": true }, "paycard_enabled": { "type": "boolean", "example": false, "default": true }, "kyc_status": {}, "ssn_verification_status": {} } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Working State does not represent a state in the US", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Working State does not represent a state in the US" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false }, "get": { "summary": "Get Employee Information", "description": "Get a specific employee's information.", "operationId": "retrieve-employee-information", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of employer", "required": true, "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "description": "Employee ID", "required": false, "schema": { "type": "string" } }, { "name": "onboarded", "in": "query", "description": "Filter by Employee onboarded status", "required": false, "schema": { "type": "boolean" } }, { "name": "employment_status", "in": "query", "description": "Filter by Employee employment status", "required": false, "schema": { "type": "string" } }, { "name": "title", "in": "query", "description": "Filter by Employee title", "required": false, "schema": { "type": "string" } }, { "name": "dob", "in": "query", "description": "Filter by Employee date of birth", "required": false, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Filter by Employee start date", "required": false, "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Filter by Employee email", "required": false, "schema": { "type": "string" } }, { "name": "phone_number", "in": "query", "description": "Filter by Employee phone number", "required": false, "schema": { "type": "string" } }, { "name": "default_pay_schedule", "in": "query", "description": "Filter by Employee default pay schedule", "required": false, "schema": { "type": "string", "enum": [ "daily", "weekly", "biweekly", "semimonthly", "monthly", "quarterly" ] } }, { "name": "is_943", "in": "query", "description": "Filter by whether Employee is 943 status", "required": false, "schema": { "type": "boolean" } }, { "name": "is_scheduleH", "in": "query", "description": "Filter by whether Employee is scheduleH status", "required": false, "schema": { "type": "boolean" } }, { "name": "external_id", "in": "query", "description": "Filter by Employee external ID", "required": false, "schema": { "type": "string" } }, { "name": "workLocationID", "in": "query", "description": "Filter by Employee work location ID", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "employeeID": "1234567890", "companyID": "1b5n28nrideucd24", "onboarded": true, "employment_status": "live", "term_date": null, "first_name": "erlich", "last_name": "bachman", "email": "erlich@zeal.com", "dob": "1999-12-04", "start_date": "2019-06-04", "title": "Brand Ambassador", "working_state": "CA", "workLocationID": "531fece70b6d0b5d29c9f352", "address": "320 Pancake Hollow Road", "address_line2": null, "city": "Highland", "state": "NY", "zip": "12528", "phone_number": "+18214370987", "default_wage": 20, "default_pay_schedule": "weekly", "default_ot_wage": 30, "default_dt_wage": 40, "ssn": "123456789", "is_943": false, "is_salary": true, "salary": 100000, "is_scheduleH": false, "paycard_requested": false, "paycard_enabled": false, "kyc_status": "approved", "ssn_verification_status": null, "soc_code": "41-3011" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "employeeID": { "type": "string", "example": "1234567890" }, "companyID": { "type": "string", "example": "1b5n28nrideucd24" }, "onboarded": { "type": "boolean", "example": true, "default": true }, "employment_status": { "type": "string", "example": "live" }, "term_date": {}, "first_name": { "type": "string", "example": "erlich" }, "last_name": { "type": "string", "example": "bachman" }, "email": { "type": "string", "example": "erlich@zeal.com" }, "dob": { "type": "string", "example": "1999-12-04" }, "start_date": { "type": "string", "example": "2019-06-04" }, "title": { "type": "string", "example": "Brand Ambassador" }, "working_state": { "type": "string", "example": "CA" }, "workLocationID": { "type": "string", "example": "531fece70b6d0b5d29c9f352" }, "address": { "type": "string", "example": "320 Pancake Hollow Road" }, "address_line2": {}, "city": { "type": "string", "example": "Highland" }, "state": { "type": "string", "example": "NY" }, "zip": { "type": "string", "example": "12528" }, "phone_number": { "type": "string", "example": "+18214370987" }, "default_wage": { "type": "integer", "example": 20, "default": 0 }, "default_pay_schedule": { "type": "string", "example": "weekly" }, "default_ot_wage": { "type": "integer", "example": 30, "default": 0 }, "default_dt_wage": { "type": "integer", "example": 40, "default": 0 }, "ssn": { "type": "string", "example": "123456789" }, "is_943": { "type": "boolean", "example": false, "default": true }, "is_salary": { "type": "boolean", "example": true, "default": true }, "salary": { "type": "integer", "example": 100000, "default": 0 }, "is_scheduleH": { "type": "boolean", "example": false, "default": true }, "paycard_requested": { "type": "boolean", "example": false, "default": true }, "paycard_enabled": { "type": "boolean", "example": false, "default": true }, "kyc_status": { "type": "string", "example": "approved" }, "ssn_verification_status": {} } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee ID is not formatted correctly", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee ID is not formatted correctly" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/employees/id": { "post": { "summary": "Upload Employee Government ID", "description": "Uploads a government issued ID for a specified employee in Zeal.", "operationId": "upload-employee-government-id", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "uploadGovernmentId", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["employeeID", "companyID", "id_type", "id_base64"], "properties": { "employeeID": { "type": "string", "description": "the ID of the Employee" }, "companyID": { "type": "string", "description": "the ID of the Company" }, "id_type": { "type": "string", "description": "type of the ID to be uploaded, current options are drivers_license, social-security_card and passport", "enum": [ "drivers_license", "social_security_card", "passport" ] }, "id_base64": { "type": "string", "description": "base64 image of the ID to be uploaded" } } }, "examples": { "Request Example": { "value": { "employeeID": "z133222c924yba2f332dc059bd445a", "companyID": "fccc35f014446aa8a082f357715bcfa", "id_type": "passport", "id_base64": "iVBORw0KGgoAAAANSUhEUgAAAtsAAABdCAYAAAB0BqpEAAABRmlDQ1BJQ0MgUHJvZmlsZQAAKJFjYGASSSwoyGFhYGDIzSspCnJ3UoiIjFJgf8bAwiDLwMfAxSCYmFxc4BgQ4ANUwgCjUcG3awyMIPqyLsispF+Sj34tcJ7J2njX+JHp0/+Y6lEAV0pqcTKQ/gPE6ckFRSUMDIwpQLZyeUkBiN0BZIsUAR0FZM8BsdMh7A0gdhKEfQSsJiTIGci+AWQLJGckAs1gfAFk6yQhiacjsaH2ggCvi6uPj0KokbmhsYcvAfeSDEpSK0pAtHN+QWVRZnpGiYIjMJRSFTzzkvV0FIwMjIwYGEBhDlH9+QY4LBnFOBBiZUkMDDaOQEErhFhMCAPDzglAb7ggxFSANJcBA8PB9QWJRYlwBzB+YylOMzaCsLm3MzCwTvv//3M4AwO7JgPD3+v////e/v//32UMDMy3GBgOfAMAWoBf9ECkXQAAAABWZVhJZk1NACoAAAAIAAGHaQAEAAAAAQAAABoAAAAAAAOShgAHAAAAEgAAAESgAgAEAAAAAQAAAtugAwAEAAAAAQAAAF0AAAAAQVNDSUkAAABTY3JlZW5zaG9074pOMQAAAdVpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IlhNUCBDb3JlIDYuMC4wIj4KICAgPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICAgICAgPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIKICAgICAgICAgICAgeG1sbnM6ZXhpZj0iaHR0cDovL25zLmFkb2JlLmNvbS9leGlmLzEuMC8iPgogICAgICAgICA8ZXhpZjpQaXhlbFlEaW1lbnNpb24+OTM8L2V4aWY6UGl4ZWxZRGltZW5zaW9uPgogICAgICAgICA8ZXhpZjpQaXhlbFhEaW1lbnNpb24+NzMxPC9leGlmOlBpeGVsWERpbWVuc2lvbj4KICAgICAgICAgPGV4aWY6VXNlckNvbW1lbnQ+U2NyZWVuc2hvdDwvZXhpZjpVc2VyQ29tbWVudD4KICAgICAgPC9yZGY6RGVzY3JpcHRpb24+CiAgIDwvcmRmOlJERj4KPC94OnhtcG1ldGE+CsFE0QMAACl6SURBVHgB7Z0HfFTFFsZPCiQQBOktkFBD70jvSO8daQoKIjaUp/goiiI+LBQRBBQUQUXpTZHeQYoU6TVAgIQiHRJCkne/ibPc3Wx2NyGN5Dv8NnvvtDvznwn55uy5d92iDBMaCZAACZAACZAACZAACZBAghNwT/AW2SAJkAAJkAAJkAAJkIAiQLHNhUACJEACJEACJEACJEACiUSAYjuRwLJZEiABEiABEiABEiABEqDY5hogARIgARIgARIgARIggUQiQLGdSGDZLAmQAAmQAAmQAAmQAAlQbHMNkAAJkAAJkAAJkAAJkEAiEaDYTiSwbJYESIAESIAESIAESIAEKLa5BkiABEiABEiABEiABEggkQhQbCcSWDZLAiRAAiRAAiRAAiRAAhTbXAMkQAIkQAIkQAIkQAIkkEgEPF1pNzw8QqZM/86VorGWyZo1q/R+rmOs+U9CBjk8CbPEPpIACZAACZAACZBAyiHgFmWYs+7cvXtPChSp4KyYw3w/v4Ky9881Dsuk9ExySOkzxP6RAAmQAAmQAAmQQMoi4JJnO2V1+fF689pbw2X3nr2WRurUqi6fjhlhOU8rB+SQVmaa4yQBEiABEiABEkhOAmlObJ8+HSjHjp2wMC/gm99ynJYOEorDoD+nyeYz2+RheFhawufyWD3TeUmdQjVlcrUBLtdhQRIgARIgARIggdRDwCWx7e3tLXO+n2p31G8OGSZXr16z5FWpUlHefDWmsMiUycdS5kk9IAfrmYPQXn98vXUiz6wIYBMCRoOMVApuKzQ8IQESIAESIIE0QcAlse3h4S4tmjW0C2TocG+r9Ny5csVa1qqgcXL9xk0JDDwvbm4ifn4FJOvTWWyLOD2/efOWnDh5RooU8Y9XfacXMBUgBxMM4xAebZprBBQrerddg8VSJEACJEACJJCKCLgkthNyvLdv3zGebDJLZv/0q1y8cMmqaV8jpKNH907y2sC+kjFjBqs888n6jVtl3MRphsg+JZcvX7Fk5cmTR0qUKCb9+jwnLZs3sqTjoELVhnLr9m25c+euVfrGTVulcImqKq1zx7Yy9uPhVvmJdZIaODB0xPXVQVaus2JJEiABEiABEkhNBJJUbB83PNDdeg2QwDOBdhkGBV2QsZ9NlHkLlsrPs6dJMcNbbbbIyEj56JMJMmnyNImMjPkQleDgYMFr46YtMvj1V2T40Dcs1eFFv22IbVsLDw+XG0YezFaI25ZNqHNySCiSbIcESIAESIAESIAEUjaBJPtSG4R7tOnQK1ahbcZ0+vQZad+lj+BRe2b7cMx4mThpqpXQ9vT0kFy5cpqLSZQhxMdNmCyffDbJKj0lnJBDSpgF9oEESIAESIAESIAEkoZAkontt4eOMkI+LltGhfjnd//zhmzb+Jv89edaGT1qmHh5pbfkI8Rk6IgxlnMczJo91+q8ZYumcvbEXjl6YKvs3blOOhlhIGZbsGi55fTTT96X8V98bMR2F7ak4aBUqRIqHXm9enaxykuMk7TDwU2ezpxH8DSOuFqZAhUlIF+ZuFZLsPLod7MSTeLdXs3CtSVfjkLxrs+KJEACJEACJEACqYdAkoSRwJu7fPlKK2qjRr4nrwzoY0nDcc4c2WTAoLctaYuWLJfPxgwXPAXkn+s35ObN6HAPXeCNQS9KhgzRN2j6FfSVCZ99KNt27JQb16PLBYeEyOkzZ6VwIT/p2qmNqvbrvCVy6tRp3YTky5tH+vTobDlPzIO0wcFN+lXpLr0K15NcXlkkIipSdlw7Ie9unyr/3LCO0Y+Ndc9ijeR62B0Ze/FgbEUSNb1YNn8ZV7WvrDy6Kl7XeadcR5lzar3Mv3omXvVZiQRIgARIgARIIPUQSBLP9sIlv8sDIzZa21NPZbIS2jq9c8fWgpsctd0zwkhWrtmoTvGkEtQz28QpMwwBfsuShJsqD+7ZKEGn90W/Tu1TQttSIJkP0gKHFyp3k1cDWsiw3bOl4ryXpNnK4XL/4QP5seEw46bXp5N5Bnh5EiABEiABEiABEkhaAkni2T52/KTVqPAkju69Blql6RPc4Gi2M4ZnGuZmPB+wSpVKsn79Jkv2ihUrZdWqtVKxQjmpVLGcVK1SQRrWqyVZsmS2lElJB6mdg5e3j/ynVFt5c9cM2Xp6i0J/IfS2DNk0Xla2GSftijeWn/bNl7zZ/WX0M33lk71z5Y2y7cXbM73MPrlONp2I3ljpOWtduoX0LtJATt+5LFMPLZMzIUd1lrQo2UzaFKwmmTy9ZW3wAflh/3yJeBi9ocuZ1VfeKt9NymQtIIFG3cmHl8nRCwdU3der9TXSgsXXJ6c0zVdBOq4YKunTZZCBFbpIzZwBsuPqcdlz5dGXHqGSZzpv6VuhkzTMU07O37sqs46vloPnH30Lae2idaRXkUbi7ZFOPv97vqWPPCABEiABEiABEiCBJBHbwSGPHs+nkf+xeq0+dPgeHPwozhthIq3a9ZTzQUGWOniayM5de9Rr6nQxhFM6qWl8BXvP7h2lQ9sWlnIp4SC1c/DLFh2nvO38HivcD8LuyaaQw1I5e1H5ycjxSZdRauQoLi+Xbi3Tj/4mdfKWk6nVB0qN4CNy83b0fLf1rSqREiWj982VzoXrys8N3pUmy9+RW3euSMeybeSd0u3l7d0z5faDezKqUk8pnCm3jNg4QdzdPWR2g/dk5cW/ZPq25dLMr5rMN84rz39JwkLvSOmnC0qPQnXk25Nr5COj7cjICPmq3tvydPqM8r/98yS3TzYZWaGrVf//V/cNI99HRuyZJYUz55Mf6r4lHdaMlsCQY1LKt4JMrzFIxh1ZJrsvH5O+Ac0kf4ZsVvV5QgIkQAIkQAIkkHYJJEkYSURERLwJhz14YKlbwDef/L7sZ+ncqZ3E9o2UCFfZsGGzvDjgTRn+wVhL3ZRwkNo5+GfOKw+NGO07d6/HwH36doiUzJLPKn3s3h/lb8NDPNUIObkVfl9q5q9gyb8Yel0+3zZd9p/bIyM3T5LwqAip6VtR5fcr1ljGHlooW05uVvnv7pwhHQtWF3jWIZ6bLRwkE3bMUJ7wmQcWirvxqYifEYetbY3hCf9m94+yO/BPyeyTQ6rnKCaDjZjynYE7ZNmh32TO6UefnmTyyS4t8lWU93ZMlxMXD8sfR9fIsqDd0sa/lmqunX9NWW20963R3r5zu+XdzRMlg8ejG331NflOAiRAAiRAAiSQNgkkiWc7T27rR/OVKFFclsyf5RJxn4wZrcrly5tbpn31qUCEr/h9jWzdtkv27j8oR44ckbCwR8IclaZMnSF1a1eXJo3rWbWRXCepnUPgrUvi6eYumXyyGoL7HyvMRYwnfBy+ecEq7da9aFGO56cH3b8mmQzvsrb9/wRKVFT0s9QjIx7KkRtBUjRLfkmXPoP4++SS48a5tqCbF9Vhviy+cib0mDQOaCQ9jfCTUsZ5Ro/op6F4GP3Sdu7uVX0o+Y1+wS6a2jtkXFtbQSMUBba25afyICI6TCWjp5dsunxEpZc0rrEx5JA6xg948c/ejflJjqUAD0iABEiABEiABNIUgSQR24UL+VtBDQ4OMZ48kt0qLa4nXunTqzARHSqCGyVn/jBXRo/53BBpj1rbtGVHihHbqZ3D2X+in75Ru0AVqyd5eHlnknq5S8k0I9bZVfPLlMuqaEEjxvq3C7sl/MF9uRp2S3JnzCb6WSVZM2ZVZa8YISZ+uYrJl8+8JF02jJXDF/Yrcb638wyrtswnV+5dU6eZjQ3CNaNtWP5MOdQ7foTcjQ5rqbHoVeO579YbCORDWPtmfLSWEcaSz+gbjQRIgARIgARIgARA4JG7LxF5tG/b3IildbNcAd/YOPvnBZZzfQBPZptOfaRUhbqW14aN21T2vAXLpGzl+pZXvcbt5P79UF1V3RQ5+LX+UqpkSUsaDoJDosWSTvQwvgTHbOfOP/KQmtMT4zi1cwgLvSufHFwon1TuLXWL1VNPH/HLVVzG1x0sd8PDZPEx18V29ezF5NmAxuJjxFB3Ld/eELTZZGdwtAd5iRHG8ZZxI2aOrPlV/pDyXWTf9UDlTc9g3OwYZfy7Y8Ryuxs3LPYoHf3Ix9jm8+qNi3Lu7jX5b6XekuWp3FIod4C8WqKFpTgeV3jSuKFykHEDZXovH3W90fUHS0vjBk3Yuov7VQhLFX/jZk0j5OSVqr0lnZv1GrM0xgMSIAESIAESIIE0RyBJxDbCJ+rXr2MFd8g7I+Xr6T9I0MVgFS5w9NhJ6dpzgGzZsl195TqeShJuPF2ijhEGAkMoyNVr1+TChYvq9ffBw/L2ux8IvoZd287de+XUmWjvqk4rWbK4PlTvBfJbxw0fN56UsmDRCgkNC7MqlxgnaYHD7L3zZOLR5TLSeBrI7o5TZcmz7yvx22PtGGNz9GiunPH95exWqZ2ntOzqMEVeLt5M3tj1rVz897nVE3Z+p54a8nuzMbK9/VeS3t1TXlwXHZ9//NIh+eXsNln+7Aeyo9N0uRx6w+GlEOP9/MbPpKAhlLe3myifV+8vk42bNrVhA9hzzRgJMG6M3NP5G9nZYbJEGmmrTm1URdYdXy9Tjv8hU2oMNPoySULuX1fiXNfnOwmQAAmQAAmQQNom4GaICVPQRdxhlKvSQIKCHsXi4lsdZ8+cFKOhi5dCpGa9lnLr1q0YeenTp5MHD6LjYXWmm+EJn/bVF9KpQyudJC/0HyxLlq6wnOMA5YoULqS83BcvXVJf1a4LZMmSRfbvWieZMz+lk2TSlJny/of/s5zrA09PT+napYNMGjdaJ8XpPS1yKDW7m0NGmTPllLuG2NWP5HNYOJZMPHYv4mGYJX7bXMzd3d2Yf08j3zpWH2XwzZWI9YaYdtUQD44wldgMbUYZN4DaGw/CR9yM/tjL0+0d7jVXH/KdBEiABEiABEggjRBIEs82WOLGxrk/fiO5clnfLIk8W6HtaYR6jPjvECuhjXJfjf9Y2rR+9BE/0qIio+TkydPK241jbQEBxeSPFb9aCW3k9Xu+u+Q1vjXS1h4+NITZYzw1xba92M7TEgc8ps+R+IyNkTn9YXioXaGNMrix0p7QRt5DI2wlLkIbdRwJbd1mbOPBtWLLQ10aCZAACZAACZBA2iSQZGIbeKtXrSib1i6Rfi/0lKxZo29qM2PHM7IbNqxrlFkmb776kjlLHfv4ZJTvv5kg47/4WEqVKmF8VXsGqzIeHu7i7+8n/V/sIxvXLJbiRQtZ5eME3zL5iyH6axnP4k4uI4fkIs/rkgAJkAAJkAAJkEDSEnjsMJL4djc8PEJOnwmUc0YIysPwhxJQvIj4+xUwbqR0Xf8jAibw7Hk5cvSkIB66dOkAwVNKXLWQy1fkdOB5uXQp2KjnJWWM+n4FfV2tniDlnmQOzsJIEgRQKmqEYSSpaDI5FBIgARIgARJwkUCyiW0X+8diKZhAubl9VLhGCu5iiuka4r0PdJuVYvrDjpAACZAACZAACSQNAdfdyEnTH17lCSJQp1DNJ6i3ydtVskpe/rw6CZAACZAACSQXAXq2k4t8KrnuoD+nyeYz2+jhjmU+4dGG0J5cbUAsJZhMAiRAAiRAAiSQmglQbKfm2eXYSIAESIAESIAESIAEkpUAw0iSFT8vTgIkQAIkQAIkQAIkkJoJUGyn5tnl2EiABEiABEiABEiABJKVAMV2suLnxUmABEiABEiABEiABFIzAYrt1Dy7HBsJkAAJkAAJkAAJkECyEqDYTlb8vDgJkAAJkAAJkAAJkEBqJkCxnZpnl2MjARIgARIgARIgARJIVgIU28mKnxcnARIgARIgARIgARJIzQQ8U/LgwsLCJDQ0VLy9vcXLyysld5V9I4E0TWDlypWybt26WBm89NJLUqxYsVjzmUECJEACJEACqZWAy2J71apVcvv27RgcSpQoIaVLl46RnhAJW7ZskT/++EOaNGkijRs3TogmE7yNa9euyZ49e+TUqVOSLVs2qVevnuTJk8dyHTBbv369XLhwQeXXrFlTChQo4HK+pWA8DiIjI2XXrl1y8OBBde2qVauKr6+vVUvBwcHy559/ypUrV9Q8VqlSRdKlS2cpc/78edmxY4dcvXpV8uXLp+bBx8dH5WPcmzZtksGDB1vK2x789ddfcubMGavk7NmzS/369a3SzCcjRoyQF198Ufz8/OTXX39VG622bduai1gd21ubibkurS5uczJz5kzV70aNGtnkxDyND5uYrcSecvfuXTU/Z8+eFcxZnTp1xN/f36pCYGCg7N27V27cuCF58+aVWrVqyVNPPWVVxpUTzHHDhg2lSJEidotTaNvFwkQSIAESIIE0QMDlMJJ9+/YpUQZhZn6dO3cuDWCyP8T79+/L1KlTlVCtUaOGEjRfffWVhISEqArwyk+ePFlQDiIcgmfatGly6dIll/LtX9X1VIjQjRs3SpkyZZSAnj59uly/ft3SADYC6D9EeYUKFWT79u2yfPlySz7m9ptvvlFCvW7duoKNBcYXERFhKePsAEL/zp07SsBBxOGlxbqzuq7mo9/YIOj28Z4+fXpXqydbucRkc+/ePZkyZYra5FWvXl0JaczlkSNHLOM9dOiQfPvtt2o+MP/YUE2cOFEg0uNjENpaVGPzaX7B861f8WmbdUiABEiABEjgSSXgsmdbD3DgwIGSO3dufWrxguIPK0Ql/tgGBQUJPKYBAQGSI0cOdXzy5EnJlSuXFC9eXNWF0IPHLXPmzCodf/ghwlDfw8PD0r69A3iJIQSzZs2qPHUIM4FgPHz4sCoOT7ubm5s6Pn78uDx48ECKFi2qwlHQxxMnTqg0iAO0YTYIydOnTysBDc9q/vz5zdlWx8uWLVOe4h49eqh0CBYIPfQPjI4ePar4dO3aVeWXKlVKsdm/f78SP87y9cXgdfznn38kZ86cqn2djneMB6xxXbDWBuEEoT1o0CCLNxuid/HixfLCCy+oYitWrFBe2Pbt26tzjHfcuHGiPeDwilesWFG0lxbe4pEjRyo+WlTp66EPUVFRalw6De+4JjyeqBuboR486BkzZrQag7k85hdlsmTJIk8//bQlC3UhLFu2bOlw3ehrYI3Bs25rt27dErxsPf8o54g/8i9fvqzWk726uC4+NUAf4Tk2h0O5wgbtO+obuOD3DXMPftqwxmB9+/YVd/foPTV+T7BmS5YsqfKwaYYnG58cwTDXn332mfokpFq1aioNP/D7gzWN319nGyUdToI5t2cINTGLcntlmEYCJEACJEACqYlAnMV2hgwZrP6oaxgQbvijX6lSJcHH4zB4G5s1a6a8pRAdMHh4IYzwx/uHH35QYhlCEoIChlCMN998UwljlWD6gTZmzZplEdXIgoDo37+/Ekm//fab8s698sorql2IhO+++048PT3lgw8+UCIRnryHDx9aWm3durX6eB0J2ADAc2v2/sIr3KtXL4t4t1Q0DiDKu3TpooQUxCYENsanDQLTVpSiL9qc5aMcwij+/vtvxQUec4QCgB8M4R3gDmbwOkPsQVzBq4vNCMS5WQBCRM+ZM0fVxQ9sdnRbOEf5ggULqnTUgwgze4gh2rRwQ3kY5gTzCG+9jq8Hf4h/GJjiGIIT82G7ecE6wJxoLuXLl1dtqsr//oAoxSYAGyisFWycnn/+eXWO9rEG0C8t2G3FNDZyc+fOVRs7rDOIXtSHOMXmCqEf6AfOsXlBCIvupyP+uKfg66+/Vn3CGDNlymTFBwIbY7t586bqI9bVc889pz5pcIWNs75hXL/88ovagOAaWKtYjzCMB3Npni/MKTZhYIBNLgQ66mnD/GAOIaq14Xdq69ataoOCTcUzzzwjHTp00Nl23wsVKqR+7+1lOorrtleeaSRAAiRAAiTwpBN4pPxcHAk8VxDc2hB7a/Z0h4eHy2uvvaY+MoYHGX9cIV7gHZw3b56KITYLPMSMwgtWuHBhFZ8NwYQ/8Pb+oKMteK/hGUM+vOWLFi2S77//XoYPHy4QamvXrlUeZX8jNhXXh2ApW7as6i7KYQMA7zy8oziHpw/iDQIMggyCqHPnzqrO77//rkIrIDZq166th6ze0S7KQmRCbEK8QFCiD/BkQxhCBJoNY8WrY8eOKtlZPpjBczl06FDlUcRm5ssvv5QGDRooYQhB1a9fP7WxQH8+/vhjNfZy5cqpvth67SHKESIAQQkPK/pvWwbnEFUwLZjVifED/OFZBi9t2GTAC9q7d2+VhM0QBCDmHAahvHr1auV9x9rAeOBZhxCEzZ49WxAnrtcEPO8QfWaDqMScIdYdfUeoA+LgsW4gHDGn2CRB/EI8QmxjAwbxDIY///yzdO/eXcWk4/oI5cFYWrVqpeYf14LHHsJ027Ztal0MGzZM1XXEf8mSJWozgo0c6iIsBGtB88FaxrrG2LAeEN+OexAgimHO2GBtwuz1DeMEZ2wEsaGDSMbawAYMYSOIr8c9D+i/FtzYgMEguLFecR/EggULBOFFYIbNF8KFIJZh8I7v3LlThgwZotYJWGPTA8+49o6rgvxBAiRAAiRAAiQQK4Hoz5djzY6ZgXARCF79gmAwG8Q3RBE+koZp7y28qhCX8PZBGGqDKID3G+ElOpwBIsWewZMMg8cVXljESUMkQwRAQMCrDkPoCOzYsWPqHeEdEKoQJBBrEB0HDhyweFDRLjy0EOcwiD3c/Ke9uvq6KvPfH/Coog7EzTvvvCNvvfWWEsXgs3nzZnNRdYz+QYi2a9cuhsBFAXv52BB069ZN9QMCWHODqIdBtCP0A3UvXryohJXOw1h1/1Vh44cOYUAexgghptN0GdSBaLU1CEmIRYTM6BAdlMGcIhRBGzYCuFkObNBfhARhA4INA258RFl4kpEPwQhPtQ5TQRvPPvusbsryDjGpbyrFRg/eVXCGYT5xDWyQIApHjRqlNgnwSMMwd9hk6Jt4ITxffvllad68ucrHvQjYvIEvNg7YBKBf4OiMP9qGONViFiIa61Ibwqgg6MEbbaOcjud3xgZtOOobro35w4YIbWNTgRtz9ZrH7x+4YGOBDcTSpUvVJ07mjTLGjM2iOWwLvwPoLwy/R/jd0RsyCHQIf4yLRgIkQAIkQAIk4BqBOHu2EQNsftqG7WW0wNMCxPyHXKeZ68BTqk3/UYeQtWcQFDCzxxXHEAwQbRDsEO/w+EKEQThAXEDwQ1xrQ6wqDCIV14THFZsAbTofYgZmFpe6DIQHDJ5LHSuLsVSuXFmJFIgwbdgM4OY0hIDAi2trseVjDPDKwhuOj/zNQglt4GZGeB4hChFLax4DyoOD2cAI4RoojzGhDrzbKKsNjLXXWadB2OJTCXivsbkxm3n+kK55YhOGuYHX12zwRsMrjc0PuEPsmz386BM81WZDf82Ga6DfMAjx9957z5KNNYZrIHwIgh7hNbZ9xNj1ugQzbCIQP69Ns3TGH6xs+2Y+B398WoJPE+A51n3GdXB9R2ywuXDUN6xdbJgWLlyou63Ws/Y4Y61gU4G1rO+XwKcg+PRDfxKFTxXASm+WwGvGjBkqNAkbOawXW2Ft73fY0gEekAAJkAAJkAAJxCAQZ7Edo4XHTIAggeiCwNKPiDN7B83NQ+jB4wgvLgQixLD2FOrYZHj0kA9vHoQWxC8EAkQ4DMIbcc0w1IcXFwIU10fMLTyOeJSdFtgQXPYEBtLQB7NQRZuIB9cbDpyjPoQ2+gVhY2uO8jEGCPH3339fiTP0DeEyMHzkj3x41bXAw9MntCHuFmwgyHR/UAeiT48NnJGm48rRPtiZNwQQxYjzRhgGPMC2BkEGkabbxPxAPENoY9MELz+8yDofZfFCn+BxBn+U0xsoCFisB7NBWJoN19BrBBsRbLbwKYc2zCvELK6JNYNPKcwGEYvrQrRDeMKbjtAbW0NIUmz8URYs0Re99pCGvmIDBkM4FI71JzbY/GETAHPGBmUc9Q3ed+QjPt6eIR8eavOaw4YCc4PNBNYd+mCeU/DCJyX6Ex60r0OK9DUwP5g7vcHU6XwnARIgARIgARKwT8DdfnLsqYgjhUdMv/BR9+MYvH4QifDQwXsK094523bxkTYMH4kj5hZhGRAVEAz6jz9ELUQDYmNhug7EJwQ3BAduKoQAmzRpkhKyWuQj3AEiBO3iJk+ITAhdeGLtGUIm4BWF4IIh/AVP8NAhCxCNuEEOwhCebog8vPTH9M7yMQ6UgYCHgETsMwQxDHkQrTrkA3HN5vAbxA1jIwDBh7rYeIAZ+qwNxxDDEFS6fYgx3X+MCzcAIswH3m7dfwh4begPYpfRT8wl2OKpKzAIaDzDec2aNeoc/UXMP9Ih5CD64MFFnDaYgD3m1tYQMoF2UB+bM8TQ67hntIE6WiCCBzhhUwWD2EXf0Af0FeIZ603fxIt2UB4iEoZH433xxReqP474oyw44fGKqIu2Ic6xHrWhvg7Xwfg2bNigs5yyQUFHfcOax6cHYIG5Q/v4ndTXwDgR247NFAxzDE76ySPwfGOTgPkAdxjYYv3qJwZhA4K4bR2agrbwtBK93lWlf38gzltv2szpPCYBEiABEiCBtE4gzp5tLWo0OAg6LWh1WlzeIYog8BD7jJAC3GxnDsEwtwXxgRsjIRohEuCNhjDHEx60IbwDf/gh0CDEtHBAPm6ag4CGQIGAheCA11GXadOmjRJNEBiISYd3FDebaYGir6Hf4QGGJxPiDGIfwqp+/frKm44y+AgfAhgvxDxrg8DETaTO8nFtCB2EG2CsuKFNx1hD/OL6EyZMUJ55cNQ35uE6EHq4UfOnn35SccwQZCiv49pRBuzgEcbNhSgPdogR1yEWEOoQqriJDi9tGGOLFi3UKUQzOCJWGtdAH8w3t+JTBGxeIOohluGFxzxo69OnjxKJH374oRoHbia0XWPoN8Q2NmP4FAJrBPcAwLCRwRM4cGMiPK4QjphP3QfMC27InD9/vto0oQ9YrxgDrGnTpmqTMH78eLUmUB5rAmvSEX/UhcceQhsCFAa2ZsGJTQr6hThnzBueVKM3dijvjI2jvqG+HpfeUEH840uTYFhjYImbH3FtrHf0T+ejDOojzOWjjz5SXJGGMesYeu2Vx0YYXnCwx5jg/bY1pNNIgARIgARIgARiEnAzxEdUzOTET4GHGTfKQUAjFhhCFX/M7YVs2OsN/vhDTNuWh+CDeET4Az5CtycC4IWEV9A2ltd8HYgoiE/b9s1l9DG8qYjHhffclfK6nqvv8FpCbGsRbK4HMYzxQBzGZugbQmTQhj1DfYwXYRHxNfQDS0mHrNi2gz6g/zrW3TYfY0RdR/xQBsIRGwNbw7XhvYWY1xsS2zKOroH6EOr6ExJzXUf8Uc7Z2OHxR7v2+o36ztg46hvqO+of5haeaEdrE78z+H1y9PsANthUOTNsgrGhiO0bXxFSxa9ud0aR+SRAAiRAAqmJQJw924k1+NhEWmzX0zG+5nx4pPEUCogfeNy199JcBscQfY6EBcroOGgcOzOIO0c3jTqr7yzfkZCGgI5NROt2EZvsyMDjcYQ22n7cPjgao+67ozIQsvCyOzJn9e0JbbTnqB7ynY0dm0JH5mx+MLbY+oZ2HfUPc+tsbWKD4+z3wRWhjb4gvAViG6LanjHcxB4VppEACZAACaRmAsnm2YY3D6EVCAPQ8bWPCxqP9EMMOdrEjZFxFfCPe33WJwESIAESIAESIAESIAEzgWQT2+ZO8JgESIAESIAESIAESIAEUiOBOD+NJDVC4JhIgARIgARIgARIgARIIDEIuBSzXTAg5hexJEZn2CYJkAAJkAAJkAAJkAAJJDWBc8d2J9ol6dlONLRsmARIgARIgARIgARIIK0ToNhO6yuA4ycBEiABEiABEiABEkg0AhTbiYaWDZMACZAACZAACZAACaR1AhTbaX0FcPwkQAIkQAIkQAIkQAKJRoCP/ks0tGyYBEggpRPgzd9xn6HEvIko7r1hDRIgARJI+QTo2U75c8QekgAJkAAJkAAJkAAJPKEEKLaf0Iljt0mABEiABEiABEiABFI+AYrtlD9H7CEJkAAJkAAJkAAJkMATSoBi+wmdOHabBEiABEiABEiABEgg5ROg2E75c8QekgAJkAAJkAAJkAAJPKEEXPq69id0bOw2CZAACTwWgXfffk3KlioRo41fFy2TVavXy7dTxsXI6//af+TevXtSp1YNGfhSbylSyE9OnDwjE7+eIbt2/yVFixaRD957K0Y9JPR56TWJiIy05HXu0EbatmyqzkMfhMq+A4dl9dqNcuz4SUsZHHRq31rG/e99GfHR5zJrzlyV56jvS5evVGXeHzZE+vXuJh179Fd9U4n8QQIkQAIkkKAE6NlOUJxsjARIIDURCA65IqfOnJX0Xumlbu1qcuPmTXV+48ZN8fD0UGnZs2dVaSiHV2REhBQvVlTmzPhS7t2/J+MmTZco49+82dMkf768EhYaZilf/ZmK4u/nazmPsoFXyK+gusb5C5ck9H6Y9H+hhyyd972ULV3SquQr/fuo81cH9BEP9+j/1h31HYVz5sghfXt1VfWe69pOvfMHCZAACZBAwhOgZzvhmbJFEiCBVEJAe4m7dW4v1atWlAlTZsjJk6fU6Hx8Mqr39Ru3yafjv7IacaWKZcXNzU3GT/pGDh0+KitWrpamzzYUd3cPOR8UJO+P/lSVb9e6qRw4eMRybtWI6WT02HFy9+49yZsnt6xYNEc+GD5EOnbvp0oEFC8qRQv7y+ixX8rwd1+XihXLye49+ywebnt9R8VmTRpKeHi4jJ/8rbw+sK/8d+Qncv/+fdNVeUgCJEACJJAQBOjZTgiKbIMESCDNEqhWtYIMHPCCevXo1klx2LP3gDx48EB+/n6KjB09Qho1qCur12xQQvtxQF0KDpF167dI+TIlxdMz2lfSukUTuX37jnw/52eBN7vNv2Enzq7TsW0L2bBluyxdvkoyeHtL/bo1nVVhPgmQAAmQQDwIUGzHAxqrkAAJkIAmkDtXTqlseLLxKvNvfPeJE6ekVac+snj5H1KzWmWZ9PlHsnnNYilcyF9Xi/f77bt3JV26dJLOENvuRshIt05tZLch7r29vGX7rr+kS4dWFiEe20V88+eTShXKyJ8798lNIzTmn+s3pEObFrEVZzoJkAAJkMBjEGAYyWPAY1USIAESWLpidYwwkqezZFECduSHYxUg3Cz548xJKnRjyrSZ8YaWLp2n1KpeRY4ZYv5+aKiUL19GcuXMoV4Hd6+3tFujWlXZvHW75dz2oGWzZ1XSiKFvCF6wpo3rSeannpJbt2+rc/4gARIgARJIGAL0bCcMR7ZCAiSQRgkUKewnDevXsbwQ3tGqxbOye/Pv0t7wFhfw9ZUiRkw17NTpQPUe1x/169aW9m1byoyvx0sJI0Z7+swfVRNtW0Q/qaRRq65StW4Lqd24vUpv1yo6PbbrdOrQUq5cuabqoN6A199VRRs3qhdbFaaTAAmQAAnEkwA92/EEx2okQAIkAALNmzRQL02jTJUGsmDRcqlQtrSMHzvKCPVwkwjjCSUQyGvWbdTF4vT+9YQxEhb2QHb9tV8GDx1ltL9MPDw8pF2bZrJh83ZB2Iq2xUYMdsvmjWTYB59IaFiYTra849GDAUULqxsqQ0Iuq3Q8xvDK1evSoXVzWbh4uaUsD0iABEiABB6fgFuUYY/fDFsgARIggSePQMGAKonaaS8vL8lphHkEGzc2Pnz4MFGvlVSNnzu2O6kuxeuQAAmQQKogwDCSVDGNHAQJkEB8CGTIkCE+1VyuE2Z4loOCLqQaoe3ywFmQBEiABEjAQoBi24KCByRAAmmNQLWqldLakB9rvLjxkkYCJEACJBA3AhTbcePF0iRAAqmIQP06fLZ0XKazZfPop5jEpQ7LkgAJkEBaJ0CxndZXAMdPAmmYQKvmjaVPz27q69jTMAaXhv58r+7SpX1Ll8qyEAmQAAmQwCMCvEHyEQsekQAJpFECM3/4xfgCmpVy7PhJfmW5zRpA6Ag82hDa3t5eNrk8JQESIAEScEaAYtsZIeaTAAmQAAmQAAmQAAmQQDwJMIwknuBYjQRIgARIgARIgARIgAScEaDYdkaI+SRAAiRAAiRAAiRAAiQQTwIU2/EEx2okQAIkQAIkQAIkQAIk4IwAxbYzQswnARIgARIgARIgARIggXgSoNiOJzhWIwESIAESIAESIAESIAFnBCi2nRFiPgmQAAmQAAmQAAmQAAnEk8D/Aci6HgA4POkzAAAAAElFTkSuQmCC" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "_id": "6441ca035c80ac24a2fc22" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "_id": { "type": "string", "example": "6441ca035c80ac24a2fc22" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "code": 47, "message": "id_type 'check' is not valid, it must be one of: drivers_license, passport" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer", "example": 47, "default": 0 }, "message": { "type": "string", "example": "id_type 'check' is not valid, it must be one of: drivers_license, passport" } } } } } } } } } }, "deprecated": false } }, "/employeeRequirements": { "get": { "summary": "Get Employee Requirements (Early Access)", "description": "Get additional tax requirements for an employee", "operationId": "get-employee-requirements", "x-fern-sdk-group-name": "employeeRequirements", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "The ID of the company.", "required": true, "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "description": "The ID of the employee.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": [ { "employeeRequirementID": "8bafd033-55c7-4edc-b671-xxxxxxxxxxxx", "type": "FORM", "status": "OPEN", "workLocationID": "635ae06ac6cf7b0f2b1xxxxx", "jurisdiction": "KY", "formTemplateID": "form-ebc648e7-0b11-424a-b7fb-xxxxxxxxxxxx", "employeeID": "657b627deca2a90023bxxxxx", "companyID": "24b5b29f07924840b119c34c135xxxxx", "date": "2023-12-14T20:52:18.280Z" } ], "success": true } } }, "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "employeeRequirementID": { "type": "string", "example": "8bafd033-55c7-4edc-b671-xxxxxxxxxxxx" }, "type": { "type": "string", "example": "FORM" }, "status": { "type": "string", "example": "OPEN" }, "workLocationID": { "type": "string", "example": "635ae06ac6cf7b0f2b1xxxxx" }, "jurisdiction": { "type": "string", "example": "KY" }, "formTemplateID": { "type": "string", "example": "form-ebc648e7-0b11-424a-b7fb-xxxxxxxxxxxx" }, "employeeID": { "type": "string", "example": "657b627deca2a90023bxxxxx" }, "companyID": { "type": "string", "example": "24b5b29f07924840b119c34c135xxxxx" }, "date": { "type": "string", "example": "2023-12-14T20:52:18.280Z" } } } }, "success": { "type": "boolean", "example": true, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/employeeRequirements/link": { "get": { "summary": "Get Employee Requirements Link (Early Access)", "description": "Get links to submit additional tax requirements for an employee. (Early Access - please contact the Zeal team to learn more)", "operationId": "get-employee-requirements-link", "x-fern-sdk-group-name": "employeeRequirements", "x-fern-sdk-method-name": "getLink", "parameters": [ { "name": "companyID", "in": "query", "description": "ID of the company.", "required": true, "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "description": "ID of the employee.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": "https://app.zeal.com/employee-requirements?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ.eyJjb21wYW55SUQiOiIyNGI1YjI5ZjA3OTI0ODQwYjExOWMzNGMxMzU4OTQwYyIsImVtcGxveWVlSUQiOiI2NTdiNjI3ZGVjYTJhOTAwMjNiNzg5NzgiLCJ0ZXN0TW9kZSI6dHJ1ZSwidXNlclR5cGUiOiJXb3JrZXIiLCJzdGFnZXMiOnsiZW1wbG95ZWVfYWNjdCI6ZmFsc2UsImk5IjpmYWxzZSwiaWRfc2NhbiI6ZmFsc2V9LCJhZG1pbklEIjpudWxsLCJ3aGl0ZUxhYmVsSUQiOm51bGwsImVtYWlsIjpudWxsLCJ2ZXJzaW9uIjoyLCJjb250cmFjdG9ySUQiOm51bGwsImV4cCI6MTcwMzE5MjMzNywiaWF0IjoxNzAyNTg3N", "success": true } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://app.zeal.com/employee-requirements?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ.eyJjb21wYW55SUQiOiIyNGI1YjI5ZjA3OTI0ODQwYjExOWMzNGMxMzU4OTQwYyIsImVtcGxveWVlSUQiOiI2NTdiNjI3ZGVjYTJhOTAwMjNiNzg5NzgiLCJ0ZXN0TW9kZSI6dHJ1ZSwidXNlclR5cGUiOiJXb3JrZXIiLCJzdGFnZXMiOnsiZW1wbG95ZWVfYWNjdCI6ZmFsc2UsImk5IjpmYWxzZSwiaWRfc2NhbiI6ZmFsc2V9LCJhZG1pbklEIjpudWxsLCJ3aGl0ZUxhYmVsSUQiOm51bGwsImVtYWlsIjpudWxsLCJ2ZXJzaW9uIjoyLCJjb250cmFjdG9ySUQiOm51bGwsImV4cCI6MTcwMzE5MjMzNywiaWF0IjoxNzAyNTg3N" }, "success": { "type": "boolean", "example": true, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/forms/list": { "get": { "summary": "Get Forms List", "description": "", "operationId": "get-form-list", "x-fern-sdk-group-name": "forms", "x-fern-sdk-method-name": "list", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID"], "properties": { "companyID": { "type": "string", "description": "ID of the company. Passing this solely will return a list of all form templates" }, "form_type": { "type": "string", "description": "Specifies the type of form template to be returned (w4, i9, or w9). If left blank and a contractor or employee ID is passed, this parameter will default to their respective worker's form (w9 for contractor, i9/w4 for employee)" }, "jurisdiction": { "type": "string", "description": "2 letter abbreviation for the jurisdiction which the forms are to be based off. Example - \"US\" for federal and \"KY\" for Kentucky" }, "effective_date": { "type": "string", "description": "Date which form API should return effective form templates", "format": "date" }, "contractor_id": { "type": "string", "description": "ID of the contractor you would like to specify a form template for" }, "employee_id": { "type": "string", "description": "ID of the employee you would like to specify a form template for" } } }, "examples": { "Request Example": { "value": { "companyID": "235e38447eezee044893yy9348z", "form_type": "w4", "jurisdiction": "US", "effective_date": "2023-01-01" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/forms/template": { "get": { "summary": "Get Forms Template", "description": "", "operationId": "get-forms-template", "x-fern-sdk-group-name": "forms", "x-fern-sdk-method-name": "getTemplate", "parameters": [ { "name": "media_type", "in": "query", "description": "Accepts \"pdf\", \"json\" - Affects the response header, i.e \"content-type:application/pdf\" vs \"application/json\"", "required": true, "schema": { "type": "string" } }, { "name": "formTemplateID", "in": "query", "description": "ID of a specific form template", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/forms": { "get": { "summary": "Get Forms", "description": "", "operationId": "get-forms", "x-fern-sdk-group-name": "forms", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "media_type", "in": "query", "description": "Media type of the form, accepts \"pdf\" or \"json\"", "required": true, "schema": { "type": "string" } }, { "name": "formID", "in": "query", "description": "ID of the form", "required": true, "schema": { "type": "string" } }, { "name": "companyID", "in": "query", "description": "ID of the company", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false }, "post": { "summary": "Submit Forms", "description": "", "operationId": "submit-forms", "x-fern-sdk-group-name": "forms", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "formTemplateID"], "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "formTemplateID": { "type": "string", "description": "ID of the specified form template" }, "contractorID": { "type": "string", "description": "ID of the contractor" }, "employeeID": { "type": "string", "description": "ID of the employee" } } }, "examples": { "Request Example": { "value": { "companyID": "23942428ee349ze49545qq33c", "employeeID": "23550cce4984eezeweo4845v" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/employees/onboard": { "post": { "summary": "Generate Employee Onboarding Link", "description": "Generates an expirable link to Zeal's employee payroll onboarding for a specified employee.", "operationId": "generate-employee-onboarding-link", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "generateOnboardingLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employeeID"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "employeeID": { "type": "string", "description": "ID of Employee" }, "employee_acct": { "type": "boolean", "description": "If false, the employee account information (username and password) collection step of the onboarding will be left out", "default": false }, "survey": { "type": "boolean", "description": "If false, the employee survey step will be left out (Early Access)", "default": false }, "i9_form": { "type": "boolean", "description": "If false, the I9 form in the paperwork step of the onboarding will be left out", "default": false }, "id_scan": { "type": "boolean", "description": "If false, the ID scan step of the onboarding will be left out.", "default": false }, "payment_method_required": { "type": "boolean", "description": "If false, the onboarding worker will be able to skip the bank account collection section of onboarding", "default": true }, "paycard": { "type": "boolean", "description": "If false, the paycard enrollment screen will be left out. NOTE: Only applicable for Paycards (Early Access)", "default": false }, "instant_pay": { "type": "boolean", "description": "If false, the instant pay enrollment screen will be left out. NOTE: Only applicable for Instant Pay (Early Access)" } } }, "examples": { "Request Example": { "value": { "profile": false, "employee_acct": false, "i9_form": false, "id_scan": false, "companyID": "123456789", "employeeID": "123456789", "payment_method": true } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": "https://payroll.your-domain.com/form/NjE5NmIyNThjZGQwMDIzYWEwMjFiL2NiYzFkMDcyYjAyNTRjZWY5MzUwNTdlZWExNmUyNjNkLzE2Mzc4NzcxMTcwMTIvP3Rlc3Q9dHJ1ZSZwcm9maWxlPXRydWUmwbG95ZWVfYWNjdD10cnVlJmlkX3NjYW49dHJ1ZSZpOT10cnVlJnBhcGVyd29yaz10cnVl" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "string", "example": "https://payroll.your-domain.com/form/NjE5NmIyNThjZGQwMDIzYWEwMjFiL2NiYzFkMDcyYjAyNTRjZWY5MzUwNTdlZWExNmUyNjNkLzE2Mzc4NzcxMTcwMTIvP3Rlc3Q9dHJ1ZSZwcm9maWxlPXRydWUmwbG95ZWVfYWNjdD10cnVlJmlkX3NjYW49dHJ1ZSZpOT10cnVlJnBhcGVyd29yaz10cnVl" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee ID is not formatted correctly", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee ID is not formatted correctly" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/sendLink": { "post": { "summary": "Send Employee Onboarding Link", "description": "Sends an employee onboarding link to the specified employee's email.", "operationId": "send-employee-onboarding-link", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "sendOnboardingLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "employees": { "type": "array", "description": "Array of Employee objects to be sent onboarding links.", "items": { "properties": { "employeeID": { "type": "string", "description": "Zeal Employee ID" }, "profile": { "type": "boolean", "description": "If false, the profile information collection step of the onboarding will be left out. **If you are leaving the profile information out, please ensure that you have given all employee information so Zeal can autofill the paperwork. **", "default": false }, "employee_acct": { "type": "boolean", "description": "If false, the employee account information (username and password) collection step of the onboarding will be left out", "default": false }, "i9_form": { "type": "boolean", "description": "If false, the I9 form in the paperwork step of the onboarding will be left out", "default": false }, "id_scan": { "type": "boolean", "description": "If false, the ID scan step of the onboarding will be left out" }, "paperwork": { "type": "boolean", "description": "If false, the paperwork step of the onboarding will be left out", "default": false } }, "required": ["employeeID"], "type": "object" } } } }, "examples": { "Request Example": { "value": { "companyID": "1eeec343485723ee58ufefhz", "employees": [ { "profile": false, "employee_acct": false, "i9_form": false, "id_scan": false, "paperwork": false, "employeeID": "cc4482374ee49487ruzieun" }, { "profile": true, "employee_acct": false, "i9_form": false, "id_scan": false, "paperwork": false, "employeeID": "dd5582374ee494ccru998eun" } ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "employeeID": "cc4482374ee49487ruzieun" }, { "employeeID": "dd5582374ee494ccru998eun" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "employeeID": { "type": "string", "example": "cc4482374ee49487ruzieun" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/sendContractorLink": { "post": { "summary": "Send Contractor Onboarding Link", "description": "Sends a contractor onboarding link to the specified contractor's email.", "operationId": "send-contractor-onboarding-link", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "contractors"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "contractors": { "type": "array", "description": "Array of Contractor objects to be sent onboarding links.", "items": { "type": "object", "required": ["contractorID"], "properties": { "contractorID": { "type": "string", "description": "Zeal Contractor ID" }, "contractor_acct": { "type": "boolean", "description": "If false, the contractor account information (username and password) collection step of onboarding will be left out.", "default": true }, "id_scan": { "type": "boolean", "description": "If false, the ID collection step of contractor onboarding will be left out.", "default": false }, "paperwork": { "type": "boolean", "description": "If false, the paperwork step of the onboarding will be left out.", "default": true }, "paymentMethod": { "type": "boolean", "description": "If false, the onboarding worker will be able to skip the bank account collection section of onboarding.", "default": true }, "profile_info": { "type": "boolean", "description": "If false, the profile information collection step of the onboarding will be left out. If you are leaving the profile information out, please ensure that you have given all contractor information so Zeal can autofill the paperwork.", "default": true }, "bank_info": { "type": "boolean", "description": "If false, the bank account information collection step of the onboarding will be left out.", "default": true }, "paycard": { "type": "boolean", "description": "If false, the paycard enrollment screen will be left out. NOTE: Only applicable for Paycards (Early Access)", "default": false }, "instant_pay": { "type": "boolean", "description": "If false, the Instant Pay enrollment screen will be left out. NOTE: Only applicable for Instant Pay (Early Access)", "default": false }, "idScanDocuments": { "type": "object", "description": "Optional flags controlling which ID documents are collected during the ID scan step.", "properties": { "i9_requirements": { "type": "boolean" }, "government_photo_id": { "type": "boolean" }, "drivers_license": { "type": "boolean" }, "social_security_card": { "type": "boolean" }, "passport": { "type": "boolean" }, "other": { "type": "boolean" } } } } } } } }, "examples": { "Request Example": { "value": { "companyID": "1eeec343485723ee58afef12", "contractors": [ { "contractorID": "674759a85785745748e3847a", "contractor_acct": true, "id_scan": false, "paperwork": true, "paymentMethod": true, "profile_info": true, "bank_info": true, "paycard": false, "instant_pay": false }, { "contractorID": "774759a85785745748e3847b", "contractor_acct": false, "id_scan": true, "paperwork": true, "paymentMethod": true, "profile_info": true, "bank_info": true, "paycard": false, "instant_pay": false } ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "employeeID": "674759a85785745748e3847a", "link": "https://payroll.your-domain.com/contractoronboarding/10983755744920193854758300657020834" }, { "employeeID": "774759a85785745748e3847b", "link": "https://payroll.your-domain.com/contractoronboarding/20983755744920193854758300657020835" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "employeeID": { "type": "string", "description": "Zeal Contractor ID (returned under the shared field name employeeID)", "example": "674759a85785745748e3847a" }, "link": { "type": "string", "description": "Web onboarding link for this contractor", "example": "https://payroll.your-domain.com/contractoronboarding/10983755744920193854758300657020834" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Failed to create onboarding link for worker 674759a85785745748e3847a", "code": 0 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Failed to create onboarding link for worker 674759a85785745748e3847a" }, "code": { "type": "integer", "example": 0, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/employees/getTaxParameterDefinitions": { "post": { "summary": "Generate Employee Tax Parameter Definitions", "description": "Retrieve all tax parameters used for withholding calculations.", "operationId": "get-employee-tax-parameter-definitions", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "getTaxParameterDefinitions", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["jurisdictions"], "properties": { "jurisdictions": { "type": "array", "description": "\"US\" for federal or a US State (2 letter abbreviation)", "items": { "type": "string" } } } }, "examples": { "Request Example": { "value": { "jurisdictions": ["CA"] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "US": [ { "code": "FILINGSTATUS", "label": "Filing Status", "effectiveDate": "2020-01-01T00:00:00.000Z", "type": "options", "options": [ { "code": "S", "name": "Single or Married filing separately", "effectiveDate": 2020 }, { "code": "M", "name": "Married filing jointly", "effectiveDate": 2020 }, { "code": "H", "name": "Head of Household", "effectiveDate": 2020 } ], "defaults": [ { "effectiveDate": 2020, "code": "S" } ] }, { "code": "IS_NON_RESIDENT_ALIEN", "label": "Nonresident Alien", "effectiveDate": "2020-01-01T00:00:00.000Z", "type": "boolean", "defaults": [ { "effectiveDate": 2020, "value": false } ] }, { "code": "TWO_JOBS", "effectiveDate": "2020-01-01T00:00:00.000Z", "label": "Two Jobs", "type": "boolean", "defaults": [ { "effectiveDate": 2020, "value": false } ] }, { "code": "DEPENDENTS_AMOUNT", "label": "Dependents Amount", "effectiveDate": "2020-01-01T00:00:00.000Z", "type": "dollars", "constraints": [ { "min": 0, "max": null, "effectiveDate": 2020 } ], "defaults": [ { "effectiveDate": 2020, "value": 0 } ] }, { "code": "OTHER_INCOME", "label": "Other Income", "effectiveDate": "2020-01-01T00:00:00.000Z", "type": "dollars", "constraints": [ { "min": 0, "max": null, "effectiveDate": 2020 } ], "defaults": [ { "effectiveDate": 2020, "value": 0 } ] }, { "code": "EXTRA_WH", "label": "Extra Withholding", "effectiveDate": "2020-01-01T00:00:00.000Z", "type": "dollars", "constraints": [ { "min": 0, "max": null, "effectiveDate": 2020 } ], "defaults": [ { "effectiveDate": 2020, "value": 0 } ] }, { "code": "DEDUCTIONS", "label": "Deductions", "effectiveDate": "2020-01-01T00:00:00.000Z", "type": "dollars", "constraints": [ { "min": 0, "max": null, "effectiveDate": 2020 } ], "defaults": [ { "effectiveDate": 2020, "value": 0 } ] }, { "code": "EXEMPT", "effectiveDate": "2020-01-01T00:00:00.000Z", "type": "boolean", "defaults": [ { "effectiveDate": 2020, "value": false } ], "label": "Exempt from withholding" }, { "code": "SUBJECT", "effectiveDate": "2020-01-01T00:00:00.000Z", "type": "boolean", "defaults": [ { "effectiveDate": 2020, "value": true } ], "label": "Subject to tax" }, { "type": "options", "code": "FICA_SocialSecurity_EE_EXEMPT", "label": "FICA Social Security Employee Exempt", "scope": "FICA_SocialSecurity_EE", "options": [ { "code": "NOT_EXEMPT", "name": "Not exempt", "effectiveDate": 2020 }, { "code": "NO_REPORTING", "name": "No reporting", "effectiveDate": 2020 }, { "code": "NO_WITHHOLDING", "name": "No withholding", "effectiveDate": 2020 } ], "defaults": [ { "code": "NOT_EXEMPT", "effectiveDate": 2020 } ], "effectiveDate": "2020-01-01T00:00:00.000Z" }, { "type": "options", "code": "FICA_Medicare_EE_EXEMPT", "label": "FICA Medicare Employee Exempt", "scope": "FICA_Medicare_EE", "options": [ { "code": "NOT_EXEMPT", "name": "Not exempt", "effectiveDate": 2020 }, { "code": "NO_REPORTING", "name": "No reporting", "effectiveDate": 2020 }, { "code": "NO_WITHHOLDING", "name": "No withholding", "effectiveDate": 2020 } ], "defaults": [ { "code": "NOT_EXEMPT", "effectiveDate": 2020 } ], "effectiveDate": "2020-01-01T00:00:00.000Z" }, { "type": "options", "code": "FICA_Medicare_ER_EXEMPT", "label": "FICA Medicare Employer Exempt", "scope": "FICA_Medicare_ER", "options": [ { "code": "NOT_EXEMPT", "name": "Not exempt", "effectiveDate": 2020 }, { "code": "NO_REPORTING", "name": "No reporting", "effectiveDate": 2020 }, { "code": "NO_WITHHOLDING", "name": "No withholding", "effectiveDate": 2020 } ], "defaults": [ { "code": "NOT_EXEMPT", "effectiveDate": 2020 } ], "effectiveDate": "2020-01-01T00:00:00.000Z" }, { "type": "options", "code": "FICA_SocialSecurity_ER_EXEMPT", "label": "FICA Social Security Employer Exempt", "scope": "FICA_SocialSecurity_ER", "options": [ { "code": "NOT_EXEMPT", "name": "Not exempt", "effectiveDate": 2020 }, { "code": "NO_REPORTING", "name": "No reporting", "effectiveDate": 2020 }, { "code": "NO_WITHHOLDING", "name": "No withholding", "effectiveDate": 2020 } ], "defaults": [ { "code": "NOT_EXEMPT", "effectiveDate": 2020 } ], "effectiveDate": "2020-01-01T00:00:00.000Z" }, { "type": "options", "code": "FUTA_EXEMPT", "label": "FUTA Exempt", "scope": "FUTA", "options": [ { "code": "NOT_EXEMPT", "name": "Not exempt", "effectiveDate": 2020 }, { "code": "NO_REPORTING", "name": "No reporting", "effectiveDate": 2020 }, { "code": "NO_WITHHOLDING", "name": "No withholding", "effectiveDate": 2020 } ], "defaults": [ { "code": "NOT_EXEMPT", "effectiveDate": 2020 } ], "effectiveDate": "2020-01-01T00:00:00.000Z" } ] } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "US": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "FILINGSTATUS" }, "label": { "type": "string", "example": "Filing Status" }, "effectiveDate": { "type": "string", "example": "2020-01-01T00:00:00.000Z" }, "type": { "type": "string", "example": "options" }, "options": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "S" }, "name": { "type": "string", "example": "Single or Married filing separately" }, "effectiveDate": { "type": "integer", "example": 2020, "default": 0 } } } }, "defaults": { "type": "array", "items": { "type": "object", "properties": { "effectiveDate": { "type": "integer", "example": 2020, "default": 0 }, "code": { "type": "string", "example": "S" } } } } } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Invalid tax parameter jurisdiction", "code": 91 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid tax parameter jurisdiction" }, "code": { "type": "integer", "example": 91, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/employees/setTaxParameters": { "post": { "summary": "Set Employee Tax Parameters", "description": "Set an employee's tax withholding parameters.", "operationId": "set-employee-tax-parameters", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "setTaxParameters", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["employeeID", "companyID", "federalParameters"], "properties": { "employeeID": { "type": "string", "description": "ID of the Employee being updated" }, "companyID": { "type": "string", "description": "ID of the company that the employee belongs to" }, "federalParameters": { "type": "array", "description": "An array of Tax Parameter entries", "items": { "properties": { "code": { "type": "string", "description": "Codename of tax parameter" }, "value": { "type": "string", "description": "Value you want to set for the given tax parameter" }, "jurisdiction": { "type": "string", "description": "\"US\" for federal or a State (2 level abbreviation)" }, "effectiveDate": { "type": "string", "description": "Effective date of the tax parameter. Only accepts YYYY-MM-DD date format.", "format": "date" } }, "type": "object" } }, "stateParameters": { "type": "array", "description": "An array of state Tax Parameter entries", "items": { "properties": { "code": { "type": "string", "description": "Codename of tax parameter" }, "value": { "type": "string", "description": "Value you want to set for the given tax parameter" }, "jurisdiction": { "type": "string", "description": "\"US\" for federal or a State (2 level abbreviation)" }, "effectiveDate": { "type": "string", "description": "Effective date of the tax parameter. Only accepts YYYY-MM-DD date format.", "format": "date" } }, "type": "object" } }, "effectiveDate": { "type": "string", "description": "Effective Date of the tax parameters in this request. Only accepts YYYY-MM-DD date format. This effective date will apply to any net new changed parameters unless the date is explicitly declared in the individual parameter object. **Note: Will default to the time of the request**", "format": "date" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "employeeID": "6547etrc312314213", "federalParameters": [ { "_id": "660dbaf23c1e233277df7f", "code": "FILINGSTATUS", "value": "H", "jurisdiction": "US", "effectiveDate": "2024-04-03T00:00:00.000Z" }, { "_id": "660dbaf23c1e233277df7f", "code": "TWO_JOBS", "value": "false", "jurisdiction": "US", "effectiveDate": "2024-04-03T00:00:00.000Z" } ], "stateParameters": [ { "_id": "660dbaf23c1e233277df7f", "code": "FILINGSTATUS", "value": "H", "jurisdiction": "CA", "effectiveDate": "2024-04-03T00:00:00.000Z" }, { "code": "REGULAR_ALLOWANCES", "value": "1", "jurisdiction": "CA", "effectiveDate": "2024-04-03T00:00:00.000" }, { "code": "SUTA_CA_EXEMPT", "value": "NO_REPORTING", "jurisdiction": "CA", "effectiveDate": "2024-04-03T00:00:00.000" } ] } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "employeeID": { "type": "string", "example": "6547etrc312314213" }, "federalParameters": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "660dbaf23c1e233277df7f" }, "code": { "type": "string", "example": "FILINGSTATUS" }, "value": { "type": "string", "example": "H" }, "jurisdiction": { "type": "string", "example": "US" }, "effectiveDate": { "type": "string", "example": "2024-04-03T00:00:00.000Z" } } } }, "stateParameters": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "660dbaf23c1e233277df7f" }, "code": { "type": "string", "example": "FILINGSTATUS" }, "value": { "type": "string", "example": "H" }, "jurisdiction": { "type": "string", "example": "CA" }, "effectiveDate": { "type": "string", "example": "2024-04-03T00:00:00.000Z" } } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee with this employeeID does not exist", "status": 400, "code": 23 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "status": { "type": "integer", "example": 400, "default": 0 }, "code": { "type": "integer", "example": 23, "default": 0 } } } } } } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "curl", "code": { "employeeID": "6547etrc312314213", "companyID": "123rwqeq123123", "federalParameters": [ { "code": "FILINGSTATUS", "jurisdiction": "US", "value": "H" } ], "stateParameters": [ { "code": "FILINGSTATUS", "jurisdiction": "CA", "value": "H" }, { "code": "REGULAR_ALLOWANCES", "jurisdiction": "CA", "value": "1" }, { "code": "SUTA_CA_EXEMPT", "jurisdiction": "CA", "value": "NO_REPORTING" } ] } } ], "samples-languages": ["curl"] } } }, "/employees/getTaxParameterSummary": { "post": { "summary": "Get Employee Tax Parameter Summary", "description": "Retrieve a list of an employee's tax withholding parameters.", "operationId": "get-employee-tax-parameter", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "getTaxParameters", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["employeeID", "companyID"], "properties": { "employeeID": { "type": "string", "description": "ID of the Employee" }, "companyID": { "type": "string", "description": "ID of the employer that the Employee belongs to" }, "jurisdictions": { "type": "array", "description": "List of jurisdictions for which the tax parameters are to be fetched. \"US\" for federal, or State (2 letter abbreviation)", "items": { "type": "string" } }, "effectiveDate": { "type": "string", "description": "Effective date of the tax parameters in this request. Only accepts YYYY-MM-DD date format **Note: Will default to the time of the request**", "format": "date" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "employeeID": "622fbd3d2d883a0025b18e96", "effectiveDate": "2021-11-11T00:00:00.000Z", "jurisdiction": "US", "params": [ { "code": "FILINGSTATUS", "type": "options", "value": "S", "valueDescription": "Single or Married filing separately", "label": "Filing Status", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "IS_NON_RESIDENT_ALIEN", "type": "boolean", "value": "false", "label": "Nonresident Alien", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "TWO_JOBS", "type": "boolean", "value": "false", "label": "Two Jobs", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "DEPENDENTS_AMOUNT", "type": "dollars", "value": "0", "label": "Dependents Amount", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "OTHER_INCOME", "type": "dollars", "value": "0", "label": "Other Income", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "EXTRA_WH", "type": "dollars", "value": "0", "label": "Extra Withholding", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "DEDUCTIONS", "type": "dollars", "value": "0", "label": "Deductions", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "EXEMPT", "type": "boolean", "value": "false", "label": "Exempt from withholding", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "SUBJECT", "type": "boolean", "value": "true", "label": "Subject to tax", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "FICA_SocialSecurity_EE_EXEMPT", "type": "options", "value": "NOT_EXEMPT", "valueDescription": "Not exempt", "label": "FICA Social Security Employee Exempt", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "FICA_Medicare_EE_EXEMPT", "type": "options", "value": "NOT_EXEMPT", "valueDescription": "Not exempt", "label": "FICA Medicare Employee Exempt", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "FICA_Medicare_ER_EXEMPT", "type": "options", "value": "NOT_EXEMPT", "valueDescription": "Not exempt", "label": "FICA Medicare Employer Exempt", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "FICA_SocialSecurity_ER_EXEMPT", "type": "options", "value": "NOT_EXEMPT", "valueDescription": "Not exempt", "label": "FICA Social Security Employer Exempt", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "FUTA_EXEMPT", "type": "options", "value": "NOT_EXEMPT", "valueDescription": "Not exempt", "label": "FUTA Exempt", "isDefaultValue": true, "isUserProvidedValue": false } ] }, { "employeeID": "622fbd3d2d883a0025b18e96", "effectiveDate": "2021-11-11T00:00:00.000Z", "jurisdiction": "GA", "params": [ { "code": "FILINGSTATUS", "type": "options", "value": "S", "valueDescription": "Single", "label": "Filing Status", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "PERSONALALLOWANCE", "type": "integer", "value": "0", "label": "Allowances based on Marital Status", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "DEPENDENTALLOWANCE", "type": "integer", "value": "0", "label": "Dependent Allowances", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "ADDITIONAL_WH", "type": "dollars", "value": "0", "label": "Additional Withholding per pay period", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "EXEMPT", "type": "boolean", "value": "false", "label": "Exempt from withholding", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "SUBJECT", "type": "boolean", "value": "true", "label": "Subject to tax", "isDefaultValue": true, "isUserProvidedValue": false }, { "code": "SUTA_GA_EXEMPT", "type": "options", "value": "NOT_EXEMPT", "valueDescription": "Not exempt", "label": "SUTA GA Exempt", "isDefaultValue": true, "isUserProvidedValue": false } ] } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "employeeID": { "type": "string", "example": "622fbd3d2d883a0025b18e96" }, "effectiveDate": { "type": "string", "example": "2021-11-11T00:00:00.000Z" }, "jurisdiction": { "type": "string", "example": "US" }, "params": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "FILINGSTATUS" }, "type": { "type": "string", "example": "options" }, "value": { "type": "string", "example": "S" }, "valueDescription": { "type": "string", "example": "Single or Married filing separately" }, "label": { "type": "string", "example": "Filing Status" }, "isDefaultValue": { "type": "boolean", "example": true, "default": true }, "isUserProvidedValue": { "type": "boolean", "example": false, "default": true } } } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/employees/setOnboardedStatusToTrue": { "post": { "summary": "Set Onboarded Status to True", "description": "Set an employee as onboarded.", "operationId": "set-onboarded-status-to-true", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "setOnboardedStatusToTrue", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["employeeID", "companyID"], "properties": { "employeeID": { "type": "string", "description": "ID of the Employee being updated" }, "companyID": { "type": "string", "description": "ID of the employer that the employee belongs to" } } }, "examples": { "Request Example": { "value": { "employeeID": "62350595e7f1225023b3b824", "companyID": "24b5b29f07924840b119c34c13522940c" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "employeeID": "633c323231018d840022913ca6", "companyID": "2cb5b29f0792634128c34c1358940c", "onboarded": true, "employment_status": "live", "first_name": "Erlich", "middle_initial": null, "last_name": "Bachman", "title": "4345", "start_date": "2019-11-01", "term_date": null, "working_state": "CA", "workLocationID": "6142deeb548f55223a0c67", "dob": "1825-10-02", "email": "erlich@test.com", "address": "1 Ferry Building", "address_line2": "", "city": "San Francisco", "state": "CA", "zip": "94105", "phone_number": "12345", "default_pay_schedule": "weekly", "default_wage": 5, "default_ot_wage": 100, "default_dt_wage": 100, "ssn": "000000000", "autopilot": { "autopilot_on": true, "salary": 30000, "salary_firstDate": "2022-10-06" }, "is_943": true, "is_scheduleH": false, "metadata": {} } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "employeeID": { "type": "string", "example": "633c323231018d840022913ca6" }, "companyID": { "type": "string", "example": "2cb5b29f0792634128c34c1358940c" }, "onboarded": { "type": "boolean", "example": true, "default": true }, "employment_status": { "type": "string", "example": "live" }, "first_name": { "type": "string", "example": "Erlich" }, "middle_initial": {}, "last_name": { "type": "string", "example": "Bachman" }, "title": { "type": "string", "example": "4345" }, "start_date": { "type": "string", "example": "2019-11-01" }, "term_date": {}, "working_state": { "type": "string", "example": "CA" }, "workLocationID": { "type": "string", "example": "6142deeb548f55223a0c67" }, "dob": { "type": "string", "example": "1825-10-02" }, "email": { "type": "string", "example": "erlich@test.com" }, "address": { "type": "string", "example": "1 Ferry Building" }, "address_line2": { "type": "string", "example": "" }, "city": { "type": "string", "example": "San Francisco" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": "94105" }, "phone_number": { "type": "string", "example": "12345" }, "default_pay_schedule": { "type": "string", "example": "weekly" }, "default_wage": { "type": "integer", "example": 5, "default": 0 }, "default_ot_wage": { "type": "integer", "example": 100, "default": 0 }, "default_dt_wage": { "type": "integer", "example": 100, "default": 0 }, "ssn": { "type": "string", "example": "000000000" }, "autopilot": { "type": "object", "properties": { "autopilot_on": { "type": "boolean", "example": true, "default": true }, "salary": { "type": "integer", "example": 30000, "default": 0 }, "salary_firstDate": { "type": "string", "example": "2022-10-06" } } }, "is_943": { "type": "boolean", "example": true, "default": true }, "is_scheduleH": { "type": "boolean", "example": false, "default": true }, "metadata": { "type": "object", "properties": {} } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee is already onboarded", "status": 400, "code": 38 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee is already onboarded" }, "status": { "type": "integer", "example": 400, "default": 0 }, "code": { "type": "integer", "example": 38, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/employees/profile_information": { "post": { "summary": "Create Profile Information Collection Link", "description": "", "operationId": "create-profile-information-collection-link", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "createProfileInformationCollectionLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employeeID"], "properties": { "companyID": { "type": "string", "description": "ID of the Employee being updated" }, "employeeID": { "type": "string", "description": "ID of the Employee being updated" }, "send_to_worker": { "type": "boolean", "description": "If true, notification email will be sent to employee", "default": false } } }, "examples": { "Request Example": { "value": { "companyID": "3f5c2afcc5ea40c87a2c8f3f7e5a1cb1", "employeeID": "c2fc3a5fe5c74ca08a38f5f7b1a2ec15" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": "https://payroll.your-domain.com/employee-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ", "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://payroll.your-domain.com/employee-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ" }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23, "status": 400, "correlationId": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } ], "success": false, "testMode": true } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/employees/account_information": { "post": { "summary": "Create Account Setup Link", "description": "", "operationId": "create-account-setup-link", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "createAccountSetupLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employeeID"], "properties": { "companyID": { "type": "string", "description": "ID of the Employee being updated" }, "employeeID": { "type": "string", "description": "ID of the Employee being updated" }, "send_to_worker": { "type": "boolean", "description": "If true, notification email will be sent to employee", "default": false } } }, "examples": { "Request Example": { "value": { "companyID": "3f5c2afcc5ea40c87a2c8f3f7e5a1cb1", "employeeID": "c2fc3a5fe5c74ca08a38f5f7b1a2ec15" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": "https://payroll.your-domain.com/employee-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ", "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://payroll.your-domain.com/employee-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ" }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23, "status": 400, "correlationId": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } ], "success": false, "testMode": true } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/employees/i9": { "post": { "summary": "Create I9 Link (Early Access)", "description": "", "operationId": "create-i9-link-early-access", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "createI9Link", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employeeID"], "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "employeeID": { "type": "string", "description": "ID of the Employee being updated" } } }, "examples": { "Request Example": { "value": { "companyID": "1eeec343485723ee58ufefhz", "employeeID": "cc4482374ee49487ruzieun" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": "https://payroll.your-domain.com/form/NjE5NmIyNThjZGQwMDIzYWEwMjFiL2NiYzFkMDcyYjAyNTRjZWY5MzUwNTdlZWExNmUyNjNkLzE2Mzc4NzcxMTcwMTIvP3Rlc3Q9dHJ1ZSZwcm9maWxlPXRydWUmwbG95ZWVfYWNjdD10cnVlJmlkX3NjYW49dHJ1ZSZpOT10cnVlJnBhcGVyd29yaz10cnVl", "success": true } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://payroll.your-domain.com/form/NjE5NmIyNThjZGQwMDIzYWEwMjFiL2NiYzFkMDcyYjAyNTRjZWY5MzUwNTdlZWExNmUyNjNkLzE2Mzc4NzcxMTcwMTIvP3Rlc3Q9dHJ1ZSZwcm9maWxlPXRydWUmwbG95ZWVfYWNjdD10cnVlJmlkX3NjYW49dHJ1ZSZpOT10cnVlJnBhcGVyd29yaz10cnVl" }, "success": { "type": "boolean", "example": true, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Account not found", "code": 115, "status": 404, "correlationId": "7d1d65c3-329d-4542-8f9b-0ed292d7fcf6" } ], "success": false, "testMode": true } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Account not found" }, "code": { "type": "integer", "example": 115, "default": 0 }, "status": { "type": "integer", "example": 404, "default": 0 }, "correlationId": { "type": "string", "example": "7d1d65c3-329d-4542-8f9b-0ed292d7fcf6" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/employees/custom_paperwork": { "post": { "summary": "Create Custom Paperwork Link (Early Access)", "description": "", "operationId": "create-custom-paperwork-link", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "createCustomPaperworkLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employeeID", "formTemplateIDs"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "employeeID": { "type": "string", "description": "Employee ID of the employee" }, "formTemplateIDs": { "type": "array", "description": "Array of form template IDs (in order of how it appears to worker)", "items": { "type": "string" } }, "send_to_worker": { "type": "boolean", "description": "If true, this link will be sent to the worker's email address", "default": false } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": "https://zeal-prod.embedpayroll.com/employee-information?accessToken=...", "success": true, "testMode": true } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://zeal-prod.embedpayroll.com/employee-information?accessToken=..." }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "The following formTemplateIDs: (3b1d9b0e-a146-4b48-a77d-c02ae5e5c35d) are not applicable to this worker. Please remove them from the request and try again.", "code": 13, "status": 400, "correlationId": "5d5544f9-fb8b-4c81-a8cc-68415bc214e0" } ], "success": false, "testMode": true } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "The following formTemplateIDs: (3b1d9b0e-a146-4b48-a77d-c02ae5e5c35d) are not applicable to this worker. Please remove them from the request and try again." }, "code": { "type": "integer", "example": 13, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "5d5544f9-fb8b-4c81-a8cc-68415bc214e0" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/employees/w4": { "post": { "summary": "Create W4 Link", "description": "", "operationId": "create-w4-link", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "createW4Link", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employeeID", "jurisdiction"], "properties": { "companyID": { "type": "string", "description": "ID of the Employee being updated" }, "employeeID": { "type": "string", "description": "ID of the Employee being updated" }, "jurisdiction": { "type": "string", "description": "Jurisdiction for W4 (can be \"US\" or any state abbreviation)" }, "send_to_worker": { "type": "boolean", "description": "If true, notification email will be sent to employee", "default": false } } }, "examples": { "Request Example": { "value": { "companyID": "3f5c2afcc5ea40c87a2c8f3f7e5a1cb1", "employeeID": "c2fc3a5fe5c74ca08a38f5f7b1a2ec15", "jurisdiction": "CA" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": "https://payroll.your-domain.com/employee-requirements?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ", "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://payroll.your-domain.com/employee-requirements?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ" }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23, "status": 400, "correlationId": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } ], "success": false, "testMode": true } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/employees/paycard": { "post": { "summary": "Create Paycard Enrollment Link (Early Access)", "description": "", "operationId": "create-paycard-enrollment-link", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "createPaycardEnrollmentLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employeeID"], "properties": { "companyID": { "type": "string", "description": "ID of the Employee being updated" }, "employeeID": { "type": "string", "description": "ID of the Employee being updated" }, "send_to_worker": { "type": "boolean", "description": "If true, notification email will be sent to employee", "default": false } } }, "examples": { "Request Example": { "value": { "companyID": "3f5c2afcc5ea40c87a2c8f3f7e5a1cb1", "employeeID": "c2fc3a5fe5c74ca08a38f5f7b1a2ec15" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": "https://payroll.your-domain.com/employee-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ", "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://payroll.your-domain.com/employee-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ" }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23, "status": 400, "correlationId": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } ], "success": false, "testMode": true } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/employees/getI9Status": { "get": { "summary": "Get I9 Status (Early Access)", "description": "Get the status of an I9's completion", "operationId": "get-i9-status", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "getI9Status", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of employer", "required": true, "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "description": "Employee ID of the employee", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": { "companyID": "1eeec343485723ee58ufefhz", "employeeID": "cc4482374ee49487ruzieun", "status": "SECTION_2_COMPLETED", "status_achieved_on": "2024-10-06T09:11:55Z", "admin_review_status": "PENDING_REVIEW", "admin_reviewed_on": "2024-10-07T09:11:55Z" }, "success": true, "testMode": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23, "status": 400, "correlationId": "70f9f6b1-c388-4d8b-bade-0a4f79e31c91" } ], "success": false, "testMode": true } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "70f9f6b1-c388-4d8b-bade-0a4f79e31c91" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/bankaccount": { "post": { "summary": "Create Bank Account", "description": "Create's a bank account for a specified worker in Zeal.", "operationId": "create-bank-account", "x-fern-sdk-group-name": "bankaccounts", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "id", "account_number", "routing_number", "type" ], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "id": { "type": "string", "description": "Employee ID or Contractor ID of the worker who owns this bank account" }, "institution_name": { "type": "string", "description": "Institution Name for bank account (Bank Name)" }, "account_number": { "type": "string", "description": "Account number of bank account" }, "routing_number": { "type": "string", "description": "Routing number of bank account" }, "transit_number": { "type": "string", "description": "Canadian transit number (exactly 5 digits). Required for Canadian bank accounts; do not send with `routing_number`. **NOTE: Only applicable for Canadian Payroll (Early Access)**", "minLength": 5, "maxLength": 5 }, "institution_number": { "type": "string", "description": "Canadian institution number (exactly 3 digits). Required for Canadian bank accounts; do not send with `routing_number`. **NOTE: Only applicable for Canadian Payroll (Early Access)**", "minLength": 3, "maxLength": 3 }, "type": { "type": "string", "description": "Account type. Can either be `checking` or `savings`", "enum": ["checking", "savings"] }, "nickname": { "type": "string", "description": "Nickname of the bank account" } } }, "examples": { "Request Example": { "value": { "companyID": "fc235fcccee46aa8a082f357715bcfa", "id": "624ccccca41ba35c05c256a66e", "institution_name": "Chase", "account_number": "1243686537", "routing_number": "267084131", "type": "checking" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "bankAccountID": "1b5n28nrideucd24", "companyID": "0987654321", "id": "0982354562734", "institution_name": "Chase", "account_number": "1243686537", "routing_number": "09876283743", "type": "checking", "nickname": "Main spending account", "transit_number": null, "institution_number": null } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "bankAccountID": { "type": "string", "example": "1b5n28nrideucd24" }, "companyID": { "type": "string", "example": "0987654321" }, "id": { "type": "string", "example": "0982354562734" }, "institution_name": { "type": "string", "example": "Chase" }, "account_number": { "type": "string", "example": "1243686537" }, "routing_number": { "type": "string", "example": "09876283743" }, "transit_number": { "type": "string", "nullable": true, "description": "Canadian transit number (exactly 5 digits). Null for US bank accounts. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "institution_number": { "type": "string", "nullable": true, "description": "Canadian institution number (exactly 3 digits). Null for US bank accounts. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "type": { "type": "string", "example": "checking" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Routing number is invalid", "status": 400, "code": 56 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Routing number is invalid" }, "status": { "type": "integer", "example": 400, "default": 0 }, "code": { "type": "integer", "example": 56, "default": 0 } } } } } } } } } } }, "patch": { "summary": "Update Bank Account", "description": "Updates an existing bank account for a specified worker.", "operationId": "update-bank-account", "x-fern-sdk-group-name": "bankaccounts", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "bankAccountID"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "bankAccountID": { "type": "string", "description": "Bank Account ID" }, "account_number": { "type": "string", "description": "Bank Account number" }, "routing_number": { "type": "string", "description": "Bank Routing number" }, "transit_number": { "type": "string", "description": "Canadian transit number (exactly 5 digits). Required for Canadian bank accounts; do not send with `routing_number`. **NOTE: Only applicable for Canadian Payroll (Early Access)**", "minLength": 5, "maxLength": 5 }, "institution_number": { "type": "string", "description": "Canadian institution number (exactly 3 digits). Required for Canadian bank accounts; do not send with `routing_number`. **NOTE: Only applicable for Canadian Payroll (Early Access)**", "minLength": 3, "maxLength": 3 }, "institution_name": { "type": "string", "description": "Name of banking institution" }, "type": { "type": "string", "description": "Account type. Can either be `checking` or `savings`", "enum": ["checking", "savings"] }, "nickname": { "type": "string", "description": "Nickname of the bank account" } } }, "examples": { "Request Example": { "value": { "bankAccountID": "61d3f2c3a8593140cda7c5cb", "companyID": "fc235f012tay46aa8a082f357715bcfa", "account_number": "123124215", "type": "checking", "routing_number": "061092387", "institution_name": "PNS" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "bankAccountID": "61d3f2c3a8593cc3948decda7c5cb", "companyID": "fc235f012tay46334e394cceir48bcfa", "id": "1234567890", "institution_name": "PNC", "account_number": "123435234", "routing_number": "061092387", "type": "checking", "nickname": "Main spending account", "transit_number": null, "institution_number": null } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "bankAccountID": { "type": "string", "example": "61d3f2c3a8593cc3948decda7c5cb" }, "companyID": { "type": "string", "example": "fc235f012tay46334e394cceir48bcfa" }, "id": { "type": "string", "example": "1234567890" }, "institution_name": { "type": "string", "example": "PNC" }, "account_number": { "type": "string", "example": "123435234" }, "routing_number": { "type": "string", "example": "061092387" }, "transit_number": { "type": "string", "nullable": true, "description": "Canadian transit number (exactly 5 digits). Null for US bank accounts. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "institution_number": { "type": "string", "nullable": true, "description": "Canadian institution number (exactly 3 digits). Null for US bank accounts. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "type": { "type": "string", "example": "checking" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No user with this company ID exists", "code": 4 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No user with this company ID exists" }, "code": { "type": "integer", "example": 4, "default": 0 } } } } } } } } } } }, "get": { "summary": "Get Bank Account by ID", "description": "Retrieve a single bank account object by its Zeal bank account ID.", "operationId": "get-bank-account-by-id", "x-fern-sdk-group-name": "bankaccounts", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of the employer", "required": true, "schema": { "type": "string" } }, { "name": "bankAccountID", "in": "query", "description": "Zeal Bank Account ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "bankAccountID": "0987675234", "companyID": "0987654321", "id": "1234567890", "institution_name": "PNC", "account_number": "091736576493", "routing_number": "092784765833", "type": "checking", "nickname": "Main spending account", "transit_number": null, "institution_number": null } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "bankAccountID": { "type": "string", "example": "0987675234" }, "companyID": { "type": "string", "example": "0987654321" }, "id": { "type": "string", "example": "1234567890" }, "institution_name": { "type": "string", "example": "PNC" }, "account_number": { "type": "string", "example": "091736576493" }, "routing_number": { "type": "string", "example": "092784765833" }, "transit_number": { "type": "string", "nullable": true, "description": "Canadian transit number (exactly 5 digits). Null for US bank accounts. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "institution_number": { "type": "string", "nullable": true, "description": "Canadian institution number (exactly 3 digits). Null for US bank accounts. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "type": { "type": "string", "example": "checking" }, "nickname": { "type": "string", "example": "Main spending account" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Bank Account with this employeeID or contractorID does not exist", "code": 68 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Bank Account with this employeeID or contractorID does not exist" }, "code": { "type": "integer", "example": 68, "default": 0 } } } } } } } } } } } }, "/bankaccount/": { "get": { "summary": "Get Bank Accounts by Worker ID", "description": "Retrieve all bank account objects belonging to a worker (employee or contractor) by their Zeal Employee ID or Contractor ID.", "operationId": "get-bank-accounts-by-worker-id", "x-fern-sdk-group-name": "bankaccounts", "x-fern-sdk-method-name": "getByWorkerID", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of the employer", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Employee ID or Contractor ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "bankAccountID": "0987675234", "companyID": "0987654321", "id": "1234567890", "institution_name": "PNC", "account_number": "091736576493", "routing_number": "092784765833", "type": "checking", "nickname": "Main spending account", "transit_number": null, "institution_number": null } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "bankAccountID": { "type": "string", "example": "0987675234" }, "companyID": { "type": "string", "example": "0987654321" }, "id": { "type": "string", "example": "1234567890" }, "institution_name": { "type": "string", "example": "PNC" }, "account_number": { "type": "string", "example": "091736576493" }, "routing_number": { "type": "string", "example": "092784765833" }, "transit_number": { "type": "string", "nullable": true, "description": "Canadian transit number (exactly 5 digits). Null for US bank accounts. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "institution_number": { "type": "string", "nullable": true, "description": "Canadian institution number (exactly 3 digits). Null for US bank accounts. **NOTE: Only applicable for Canadian Payroll (Early Access)**" }, "type": { "type": "string", "example": "checking" }, "nickname": { "type": "string", "example": "Main spending account" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Bank Account with this employeeID or contractorID does not exist", "code": 68 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Bank Account with this employeeID or contractorID does not exist" }, "code": { "type": "integer", "example": 68, "default": 0 } } } } } } } } } } } }, "/paperwork/employeePaperwork": { "post": { "summary": "View/Sign Employee Paperwork", "description": "View/sign paperwork for a specified employee and specified jurisdiction.", "operationId": "employee-paperwork", "x-fern-sdk-group-name": "paperwork", "x-fern-sdk-method-name": "createEmployee", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employeeID", "jurisdiction"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "employeeID": { "type": "string", "description": "Employee ID for employee" }, "jurisdiction": { "type": "string", "description": "\"US\" for federal or a US State(2 letter abbreviation)", "default": "Work_state" }, "signature_text": { "type": "string", "description": "Base64 png of employee's signature" } } }, "examples": { "Request Example": { "value": { "companyID": "55b5b29f07934820b119c34c1358940c", "employeeID": "6222222ccc8f221f9b0024b6f6c1", "jurisdiction": "US", "signature_text": "Base64 Test Signature" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "PDF STREAM" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/paperwork/contractorPaperwork": { "post": { "summary": "View/Sign Contractor Paperwork", "description": "View/sign paperwork for a specified contractor and specified jurisdiction.", "operationId": "get-contractor-paperwork", "x-fern-sdk-group-name": "paperwork", "x-fern-sdk-method-name": "getContractor", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "contractorID"], "properties": { "companyID": { "type": "string", "description": "Company ID of Employer" }, "contractorID": { "type": "string", "description": "ID of the Contractor" }, "signature_text": { "type": "string", "description": "Base64 png of contractor's signature" } } }, "examples": { "Request Example": { "value": { "companyID": "55b5b29f07934820b119c34c1358940c", "contractorID": "6222222ccc8f221f9b0024b6f6c1", "signature_text": "Base64 test Signature" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "PDF STREAM" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Contractor with this contractorID does not exist", "code": 73 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor with this contractorID does not exist" }, "code": { "type": "integer", "example": 73, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reportingPeriod": { "get": { "summary": "Get Reporting Period by ID", "description": "", "operationId": "retrieve-reporting-period-by-id", "x-fern-sdk-group-name": "reportingPeriod", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of the employer", "required": true, "schema": { "type": "string" } }, { "name": "reportingPeriodID", "in": "query", "description": "ID of Reporting period", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "reportingPeriodID": "5eb317a40d1158d5ddcb6895", "pay_schedule": "weekly", "start": "2020-05-06", "end": "2020-05-12" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "reportingPeriodID": { "type": "string", "example": "5eb317a40d1158d5ddcb6895" }, "pay_schedule": { "type": "string", "example": "weekly" }, "start": { "type": "string", "example": "2020-05-06" }, "end": { "type": "string", "example": "2020-05-12" } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No user with this company ID exists", "code": 4 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No user with this company ID exists" }, "code": { "type": "integer", "example": 4, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reportingPeriod/": { "get": { "summary": "Get All Reporting Periods", "description": "", "operationId": "get-all-reporting-periods", "x-fern-sdk-group-name": "reportingPeriod", "x-fern-sdk-method-name": "list", "parameters": [ { "name": "companyID", "in": "query", "description": "ID of the company", "required": true, "schema": { "type": "string" } }, { "name": "pay_schedule", "in": "query", "schema": { "type": "string", "enum": [ "daily", "weekly", "biweekly", "semimonthly", "monthly", "quarterly" ] } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "reportingPeriodID": "5eb317a40d1158d5ddcb6895", "pay_schedule": "weekly", "start": "2023-08-02", "end": "2023-08-08" }, { "reportingPeriodID": "522317a404341158d5c3b6895", "pay_schedule": "monthly", "start": "2023-07-01", "end": "2023-08-01" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "reportingPeriodID": { "type": "string", "example": "5eb317a40d1158d5ddcb6895" }, "pay_schedule": { "type": "string", "example": "weekly" }, "start": { "type": "string", "example": "2023-08-02" }, "end": { "type": "string", "example": "2023-08-08" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No user with this company ID exists", "code": 4 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No user with this company ID exists" }, "code": { "type": "integer", "example": 4, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/employeeCheck": { "post": { "summary": "Create Employee Check", "description": "Create a check for an employee.", "operationId": "create-employee-check", "x-fern-sdk-group-name": "employeeChecks", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "employeeID", "reportingPeriodID", "check_date", "shifts" ], "properties": { "companyID": { "type": "string", "description": "Company ID of the employer" }, "employeeID": { "type": "string", "description": "Employee ID of the employee" }, "reportingPeriodID": { "type": "string", "description": "The reporting period ID that you want this employee check to belong to. See [Reporting Periods](ref:reporting-periods)" }, "check_date": { "type": "string", "description": "Check date for this employee check. If the check_date falls on a weekend/bank holiday, or the current time is after 2PM PST, two days before the check_date, adjust the `check_date` to the next valid business day. Zeal will not roll forward this date automatically.", "format": "date" }, "approval_required": { "type": "boolean", "description": "Set to true if this check requires manual approval by the employer. Otherwise, by default, Zeal will automatically process the check on the day before the check date. You can approve the check either in the dashboard, or by using [update check](ref:update-employee-check)", "default": false }, "disbursement": { "type": "object", "description": "This object includes information regarding how the net pay is disbursed to the employee. Zeal supports Direct Deposit, Download Check, Physical Check, Prepaid, Instant Pay and Paycard (Early Access) disbursement methods.", "properties": { "method": { "type": "string", "description": "The method of disbursement. There are 6 options: `direct_deposit` (Zeal will make a direct deposit to the employee's bank account), `download_check` (Zeal will give you the link to a PDF version of the check), `physical_check` (Zeal will send a physical check to the employee's home address on file), `prepaid` (Zeal will *not* disburse the net pay), `paycard` (Zeal will instantly transfer funds to the existing paycard), and `instant_pay` (Zeal will send funds to the existing worker's Instant Pay wallet)", "default": "direct_deposit", "enum": [ "direct_deposit", "download_check", "physical_check", "prepaid", "paycard", "instant_pay" ] } } }, "shifts": { "type": "array", "description": "Array of shift objects. The set of shifts attached to this employee check describe the work done and the earnings owed to this employee. You can only create shifts by creating an employee check (through this endpoint). However, you can edit and delete shifts that are still pending. Also supports various earning components as objects. See [Shift Object](ref:shift-object) for more information.", "items": { "properties": { "time": { "type": "string", "description": "ISO-8601 indicating when the shift was completed", "format": "date-time" }, "hourly": { "type": "object", "required": ["hours"], "properties": { "hours": { "type": "number", "description": "Number of regular hours worked in this shift", "default": 0, "format": "float" }, "wage": { "type": "number", "description": "Wage for this employee. If not provided, Zeal uses employee's default_wage", "default": 0, "format": "float" }, "custom_name": { "type": "string", "description": "Custom name to be attached to an earning component" } } } }, "required": ["time"], "type": "object" } }, "flsa_ot_recommendation": { "type": "boolean", "description": "If set to true, we will automatically convert the check to include our OT recommendation at the time of processing **NOTE: Only applicable for FLSA Overtime Policy**", "default": false }, "speed": { "type": "string", "description": "The ACH speed of the check, accepts `two_day`, `one_day`,`one_day_no_reserve`, or `zero_day_no_reserve` as values", "default": "two_day", "enum": [ "two_day", "one_day", "one_day_no_reserve", "zero_day_no_reserve" ] }, "apply_employee_deductions": { "type": "boolean", "description": "Applies a deduction to this check for each employee deduction template that is effective at the time of the check_date for the employee", "default": false }, "metadata": { "type": "object", "description": "Custom object you can attach to the employee check object. This is useful for storing additional information about the object in a custom, structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata. [Metadata](ref:metadata)", "properties": {} } } }, "examples": { "Request Example": { "value": { "approval_required": true, "disbursement": { "method": "direct_deposit" }, "shifts": [ { "hourly": { "hours": 20, "wage": 30 }, "time": "2022-02-10" } ], "reportingPeriodID": "61d5533c8fc6b7af3bfc2ff3", "check_date": "2022-02-15", "companyID": "fc235f012bae46aa8a082f347715bcfa", "employeeID": "62547a2228a58200241e2b42" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "employeeCheckID": "9827465739", "employerCheckID": null, "companyID": "1b5n28nrideucd24", "employeeID": "1234567890", "status": "pending", "is_salary": false, "first_name": "erlich", "middle_initial": null, "last_name": "bachman", "reportingPeriodID": "0982349584387523234", "check_date": "2020-01-07", "approval_required": true, "approved": false, "metadata": { "checkCorrelationID": "1" }, "disbursement": { "method": "direct_deposit" }, "disbursement_status": "pending", "gross_pay": 40, "net_pay": null, "taxes": null, "total_employer_taxes": null, "total_employee_taxes": null, "totals": { "gross_earnings": 0, "gross_pay": 40, "net_pay": 0, "employer_taxes": 0, "employee_taxes": 0, "employee_deductions": 0, "employee_garnishments": 0, "employer_deductions": 0, "company_debit": 0, "company_cash_requirement": 0 }, "shifts": [ { "employeeID": "1234567890", "shiftID": "123456789", "first_name": "erlich", "last_name": "bachman", "metadata": {}, "time": "2019-12-12T10:00:00", "hourly": { "hours": 2, "wage": 20 } } ], "currency": "USD" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "employeeCheckID": { "type": "string", "example": "9827465739" }, "employerCheckID": {}, "companyID": { "type": "string", "example": "1b5n28nrideucd24" }, "employeeID": { "type": "string", "example": "1234567890" }, "status": { "type": "string", "example": "pending" }, "is_salary": { "type": "boolean", "example": false, "default": true }, "first_name": { "type": "string", "example": "erlich" }, "middle_initial": {}, "last_name": { "type": "string", "example": "bachman" }, "reportingPeriodID": { "type": "string", "example": "0982349584387523234" }, "check_date": { "type": "string", "example": "2020-01-07" }, "approval_required": { "type": "boolean", "example": true, "default": true }, "approved": { "type": "boolean", "example": false, "default": true }, "metadata": { "type": "object", "properties": { "checkCorrelationID": { "type": "string", "example": "1" } } }, "currency": { "type": "string", "description": "Currency of the employee check. `USD` for US payroll or `CAD` for Canadian payroll. **NOTE: `CAD` is only applicable for Canadian Payroll (Early Access)**", "enum": ["USD", "CAD"] }, "disbursement": { "type": "object", "properties": { "method": { "type": "string", "example": "direct_deposit" } } }, "disbursement_status": { "type": "string", "example": "pending" }, "gross_pay": { "type": "integer", "example": 40, "default": 0 }, "net_pay": {}, "taxes": {}, "total_employer_taxes": {}, "total_employee_taxes": {}, "totals": { "type": "object", "properties": { "gross_earnings": { "type": "integer", "example": 0, "default": 0 }, "gross_pay": { "type": "integer", "example": 40, "default": 0 }, "net_pay": { "type": "integer", "example": 0, "default": 0 }, "employer_taxes": { "type": "integer", "example": 0, "default": 0 }, "employee_taxes": { "type": "integer", "example": 0, "default": 0 }, "employee_deductions": { "type": "integer", "example": 0, "default": 0 }, "employee_garnishments": { "type": "integer", "example": 0, "default": 0 }, "employer_deductions": { "type": "integer", "example": 0, "default": 0 }, "company_debit": { "type": "integer", "example": 0, "default": 0 }, "company_cash_requirement": { "type": "integer", "example": 0, "default": 0 } } }, "shifts": { "type": "array", "items": { "type": "object", "properties": { "employeeID": { "type": "string", "example": "1234567890" }, "shiftID": { "type": "string", "example": "123456789" }, "first_name": { "type": "string", "example": "erlich" }, "last_name": { "type": "string", "example": "bachman" }, "metadata": { "type": "object", "properties": {} }, "time": { "type": "string", "example": "2019-12-12T10:00:00" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-21T21:29:42Z" }, "hourly": { "type": "object", "properties": { "hours": { "type": "integer", "example": 2, "default": 0 }, "wage": { "type": "integer", "example": 20, "default": 0 } } } } } } } } } } } } }, "400": { "description": "400", "content": { "text/plain": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee Check for this employee and check date already exists. Please choose another check date or add shifts to the existing check.", "code": 32 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee Check for this employee and check date already exists. Please choose another check date or add shifts to the existing check." }, "code": { "type": "integer", "example": 32, "default": 0 } } } } } } } } } }, "deprecated": false }, "patch": { "summary": "Update Employee Check", "description": "Update a pending employee check.", "operationId": "update-employee-check", "x-fern-sdk-group-name": "employeeChecks", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employeeCheckID"], "properties": { "companyID": { "type": "string", "description": "Company ID of the employer" }, "employeeCheckID": { "type": "string", "description": "ID of Employee Check" }, "reportingPeriodID": { "type": "string", "description": "Reporting Period ID of Employee Check" }, "check_date": { "type": "string", "description": "Date of Employee Check", "format": "date" }, "approval_required": { "type": "boolean", "description": "Whether manual approval is required for this Employee Check." }, "approved": { "type": "boolean", "description": "Set this field to `true` in order to approve this Employee Check" }, "metadata": { "type": "object", "description": "Set the metadata object of this Employee Check", "properties": {} }, "disbursement": { "type": "object", "description": "Set the disbursement method of check - Zeal supports Direct Deposit, Download Check, Physical Check, Prepaid, and Paycard (Early Access) disbursement methods", "properties": { "method": { "type": "string", "description": "The method of disbursement. There are 6 options: `direct_deposit` (Zeal will make a direct deposit to the contractor's bank account using Next Day ACH), `direct_deposit_same_day` (Zeal will make a direct deposit to the contractor's bank account using Same Day ACH), `physical_check` (Zeal will send a physical check to the employee's home address on file), `prepaid` (Zeal will *not* disburse the net pay), `paycard` (Zeal will instantly transfer funds to the existing paycard), and `instant_pay` (Zeal will send funds to the existing worker's Instant Pay wallet)", "default": "direct_deposit", "enum": [ "direct_deposit", "download_check", "physical_check", "prepaid", "paycard" ] } } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "employeeCheckID": "9827465739", "employerCheckID": null, "companyID": "1b5n28nrideucd24", "employeeID": "1234567890", "status": "pending", "is_salary": false, "first_name": "erlich", "middle_initial": null, "last_name": "bachman", "reportingPeriodID": "0982349584387523234", "check_date": "2020-01-07", "approval_required": true, "approved": false, "metadata": { "checkCorrelationID": "1" }, "disbursement": { "method": "direct_deposit" }, "disbursement_status": "pending", "gross_pay": 40, "net_pay": null, "taxes": null, "total_employer_taxes": null, "total_employee_taxes": null, "totals": { "gross_earnings": 0, "gross_pay": 40, "net_pay": 0, "employer_taxes": 0, "employee_taxes": 0, "employee_deductions": 0, "employee_garnishments": 0, "employer_deductions": 0, "company_debit": 0, "company_cash_requirement": 0 }, "shifts": [ { "employeeID": "1234567890", "shiftID": "123456789", "first_name": "erlich", "last_name": "bachman", "metadata": {}, "time": "2019-12-12T10:00:00", "hourly": { "hours": 2, "wage": 20 } } ], "currency": "USD" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "employeeCheckID": { "type": "string", "example": "9827465739" }, "employerCheckID": {}, "companyID": { "type": "string", "example": "1b5n28nrideucd24" }, "employeeID": { "type": "string", "example": "1234567890" }, "status": { "type": "string", "example": "pending" }, "is_salary": { "type": "boolean", "example": false, "default": true }, "first_name": { "type": "string", "example": "erlich" }, "middle_initial": {}, "last_name": { "type": "string", "example": "bachman" }, "reportingPeriodID": { "type": "string", "example": "0982349584387523234" }, "check_date": { "type": "string", "example": "2020-01-07" }, "approval_required": { "type": "boolean", "example": true, "default": true }, "approved": { "type": "boolean", "example": false, "default": true }, "metadata": { "type": "object", "properties": { "checkCorrelationID": { "type": "string", "example": "1" } } }, "currency": { "type": "string", "description": "Currency of the employee check. `USD` for US payroll or `CAD` for Canadian payroll. **NOTE: `CAD` is only applicable for Canadian Payroll (Early Access)**", "enum": ["USD", "CAD"] }, "disbursement": { "type": "object", "properties": { "method": { "type": "string", "example": "direct_deposit" } } }, "disbursement_status": { "type": "string", "example": "pending" }, "gross_pay": { "type": "integer", "example": 40, "default": 0 }, "net_pay": {}, "taxes": {}, "total_employer_taxes": {}, "total_employee_taxes": {}, "totals": { "type": "object", "properties": { "gross_earnings": { "type": "integer", "example": 0, "default": 0 }, "gross_pay": { "type": "integer", "example": 40, "default": 0 }, "net_pay": { "type": "integer", "example": 0, "default": 0 }, "employer_taxes": { "type": "integer", "example": 0, "default": 0 }, "employee_taxes": { "type": "integer", "example": 0, "default": 0 }, "employee_deductions": { "type": "integer", "example": 0, "default": 0 }, "employee_garnishments": { "type": "integer", "example": 0, "default": 0 }, "employer_deductions": { "type": "integer", "example": 0, "default": 0 }, "company_debit": { "type": "integer", "example": 0, "default": 0 }, "company_cash_requirement": { "type": "integer", "example": 0, "default": 0 } } }, "shifts": { "type": "array", "items": { "type": "object", "properties": { "employeeID": { "type": "string", "example": "1234567890" }, "shiftID": { "type": "string", "example": "123456789" }, "first_name": { "type": "string", "example": "erlich" }, "last_name": { "type": "string", "example": "bachman" }, "metadata": { "type": "object", "properties": {} }, "time": { "type": "string", "example": "2019-12-12T10:00:00" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-21T21:29:42Z" }, "hourly": { "type": "object", "properties": { "hours": { "type": "integer", "example": 2, "default": 0 }, "wage": { "type": "integer", "example": 20, "default": 0 } } } } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No employeeCheckID found in the query of request", "code": 16 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No employeeCheckID found in the query of request" }, "code": { "type": "integer", "example": 16, "default": 0 } } } } } } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "curl", "code": { "companyID": "12345676", "employeeID": "3455678899", "reportingPeriodID": "234567789900", "check_date": "2023-11-30", "approval_required": false, "disbursement": { "method": "direct_deposit" }, "shifts": [ { "time": "2023-11-30T01:17:28.188Z", "hourly": { "hours": 0, "wage": 0, "custom_name": "random" } } ], "flsa_ot_recommendation": false } } ], "samples-languages": ["curl"] } }, "delete": { "summary": "Delete Employee Check", "description": "Delete a pending employee check.", "operationId": "delete-employee-check", "x-fern-sdk-group-name": "employeeChecks", "x-fern-sdk-method-name": "delete", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of the employer", "required": true, "schema": { "type": "string" } }, { "name": "employeeCheckID", "in": "query", "description": "ID of Employee Check", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "text/plain": { "examples": { "Result": { "value": { "success": true, "message": "Employee Check(s) deleted." } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "message": { "type": "string", "example": "Employee Check(s) deleted." } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee Checks(s) with given employeeCheckID(s) is not found for this user", "code": 31 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee Checks(s) with given employeeCheckID(s) is not found for this user" }, "code": { "type": "integer", "example": 31, "default": 0 } } } } } } } } } }, "deprecated": false }, "get": { "summary": "Get Employee Checks by Employee", "description": "", "operationId": "retrieve-employee-checks-by-employee", "x-fern-sdk-group-name": "employeeChecks", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of the employer", "required": true, "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "required": false, "description": "ID of Employee", "schema": { "type": "string", "default": "" } }, { "name": "status", "in": "query", "required": false, "description": "Status to filter by. Can be `pending`, `pre-processed`, or `processed`", "schema": { "type": "string", "default": "" } }, { "name": "reportingPeriodID", "in": "query", "required": false, "description": "ID of reporting period to filter by", "schema": { "type": "string", "default": "" } }, { "name": "employeeCheckID", "in": "query", "description": "ID of the Employee Check to retrieve", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "employeeCheckID": "987234657", "employerCheckID": "123456789", "status": "processed", "is_salary": false, "employeeID": "0987654321", "companyID": "123456789", "check_date": "2020-01-07", "approval_required": false, "approved": false, "metadata": {}, "disbursement": { "method": "direct_deposit" }, "disbursement_status": "settled", "first_name": "peter", "last_name": "gregory", "reportingPeriodID": "01739fc4cfd84c2e93dba5e802d1dda1", "gross_pay": 40, "net_pay": 26.82, "total_employee_taxes": 13.18, "total_employer_taxes": 2.8, "taxes": [ { "name": "Employee Medicare Tax", "paidBy": "EMPLOYEE_WITHHOLDING", "amount": 1.16 } ], "deductions": [], "shifts": [ { "shiftID": "4712c99283304b7b989179aae36b4590", "employeeID": "1234567890", "time": "2019-12-13T04:00:00Z", "hourly": { "hours": 2, "wage": 20 }, "overtime": { "hours": 2.5, "wage": 30 } } ], "currency": "USD" } ] } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee ID is not formatted correctly", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee ID is not formatted correctly" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/employeeChecks": { "post": { "summary": "Create Bulk Employee Checks", "description": "Create a batch of employee checks.", "operationId": "create-bulk-employee-checks", "x-fern-sdk-group-name": "employeeChecks", "x-fern-sdk-method-name": "createBulk", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID"], "properties": { "companyID": { "type": "string", "description": "Company ID of the employer" }, "employeeChecks": { "type": "array", "description": "Array of employee check objects", "items": { "properties": { "employeeID": { "type": "string", "description": "Employee ID of the employee" }, "reportingPeriodID": { "type": "string", "description": "The reporting period ID that you want this employee check to belong to. See [Reporting Periods](ref:reporting-periods)" }, "check_date": { "type": "string", "description": "Check date for this employee check. If the `check_date` falls on a weekend/bank holiday, or the current time is after 2PM PST, two days before the `check_date`, adjust the `check_date` to the next valid business day. Zeal will not roll forward this date automatically.", "format": "date" }, "approval_required": { "type": "boolean", "description": "Set to true if this check requires manual approval by the employer. Otherwise, by default, Zeal will automatically process the check on the day before the check date. You can approve the check either in the dashboard, or by using [update check](ref:update-employee-check)" }, "disbursement": { "type": "object", "description": "This object includes information regarding how the net pay is disbursed to the employee. Zeal supports Direct Deposit, Download Check, and Prepaid disbursement methods.", "properties": { "method": { "type": "string", "description": "The method of disbursement. There are 5 options: `direct_deposit` (Zeal will make a direct deposit to the employee's bank account), `download_check` (Zeal will give you the link to a PDF version of the check), `physical_check` (Zeal will send a physical check to the employee's home address on file), `prepaid` (Zeal will *not* disburse the net pay), and `paycard` (Zeal will instantly transfer funds to the existing paycard)", "default": "direct_deposit", "enum": [ "direct_deposit", "download_check", "physical_check", "prepaid", "paycard" ] } } }, "metadata": { "type": "object", "description": "Custom object you can attach to the employee check object. This is useful for storing additional information about the object in a custom, structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata. [Metadata](ref:metadata)" }, "shifts": { "type": "array", "description": "Array of shift objects. The set of shifts attached to this employee check describe the work done and the earnings owed to this employee. You can only create shifts by creating an employee check (through this endpoint). However, you can edit and delete shifts that are still pending. Also supports various earning components as objects. See [Shift Object](ref:shift-object) for more information.", "items": { "properties": { "time": { "type": "string", "description": "ISO-8601 indicating when the shift was completed", "format": "date-time" }, "hourly": { "type": "object", "required": ["hours"], "properties": { "hours": { "type": "number", "description": "Number of regular hours worked in this shift", "default": 0, "format": "float" }, "wage": { "type": "number", "description": "Wage for this employee. If not provided, Zeal uses employee's default_wage", "default": 0, "format": "float" }, "custom_name": { "type": "string", "description": "Custom name to be attached to an earning component" } } } }, "required": ["time"], "type": "object" } }, "idempotency_key": { "type": "string", "description": "Unique key given to a specific employee check object (lasts 24 hours)" } }, "required": [ "employeeID", "reportingPeriodID", "check_date" ], "type": "object" } } } }, "examples": { "Request Example": { "value": { "companyID": "fc235fcc12ae4c6cce4082f357715bcfa", "employeeChecks": [ { "employeeID": "6cc3cc3f37c91f5f123c25cde490e", "reportingPeriodID": "235ccd0c9291f5f2b00c25de490e", "check_date": "2024-03-27", "approval_required": true, "shifts": [ { "time": "2024-03-27T19:38:55.527Z", "hourly": { "hours": 5, "wage": 40, "custom_name": "example" } } ] }, { "employeeID": "5cc33f3791f52325d2e490e", "reportingPeriodID": "235cd09291f5f2b0025de490e", "check_date": "2022-09-27", "approval_required": true, "shifts": [ { "time": "2024-03-27T19:38:55.527Z", "hourly": { "hours": 4, "wage": 20, "custom_name": "example" } } ] } ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": { "success": true, "failed_checks": [], "created_checks": [ { "employeeCheckID": "fbd359a66e8f4ae0a3erer3bcab9ada6063", "employerCheckID": null, "companyID": "fc235fcc12ae4c6cce4082f357715bcfa", "employeeID": "6cc3cc3f37c91f5f123c25cde490e", "status": "pending", "is_salary": false, "approval_required": false, "approved": false, "first_name": "Erlich", "middle_initial": null, "last_name": "Bachman", "reportingPeriodID": "5ecee24ac2b00264c105ab97", "check_date": "2024-05-15", "speed": "two_day", "metadata": { "newKey": "New Value" }, "disbursement": { "method": "download_check", "history": [], "link": null }, "taxes": [], "gross_pay": 300, "net_pay": null, "total_employer_taxes": null, "total_employee_taxes": null, "totals": { "gross_earnings": 0, "gross_pay": 300, "net_pay": 0, "employer_taxes": 0, "employee_taxes": 0, "employee_deductions": 0, "employee_garnishments": 0, "employer_deductions": 0, "company_debit": 0, "company_cash_requirement": 0 }, "shifts": [ { "shiftID": "7ea23a1c34b245dde1150bffed65d686", "status": null, "employeeID": "6cc3cc3f37c91f5f123c25cde490e", "employeeCheckID": "fbd359a66e8f4ae0a3erer3bcab9ada6063", "first_name": "Erlich", "last_name": "Bachman", "time": "2024-09-27T19:38:55Z", "metadata": {}, "wcc_code": null, "workLocationID": null, "customerAccountID": null, "flsa_ot_exempt": null, "hourly": { "hours": 10, "wage": 30 } } ], "deductions": [] } ] }, "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "failed_checks": { "type": "array" }, "created_checks": { "type": "array", "items": { "type": "object", "properties": { "employeeCheckID": { "type": "string", "example": "fbd359a66e8f4ae0a3erer3bcab9ada6063" }, "employerCheckID": {}, "companyID": { "type": "string", "example": "fc235fcc12ae4c6cce4082f357715bcfa" }, "employeeID": { "type": "string", "example": "6cc3cc3f37c91f5f123c25cde490e" }, "status": { "type": "string", "example": "pending" }, "is_salary": { "type": "boolean", "example": false, "default": true }, "approval_required": { "type": "boolean", "example": false, "default": true }, "approved": { "type": "boolean", "example": false, "default": true }, "first_name": { "type": "string", "example": "Erlich" }, "middle_initial": {}, "last_name": { "type": "string", "example": "Bachman" }, "reportingPeriodID": { "type": "string", "example": "5ecee24ac2b00264c105ab97" }, "check_date": { "type": "string", "example": "2024-05-15" }, "speed": { "type": "string", "example": "two_day" }, "metadata": { "type": "object", "properties": { "newKey": { "type": "string", "example": "New Value" } } }, "disbursement": { "type": "object", "properties": { "method": { "type": "string", "example": "download_check" }, "history": { "type": "array" }, "link": {} } }, "taxes": { "type": "array" }, "gross_pay": { "type": "integer", "example": 300, "default": 0 }, "net_pay": {}, "total_employer_taxes": {}, "total_employee_taxes": {}, "totals": { "type": "object", "properties": { "gross_earnings": { "type": "integer", "example": 0, "default": 0 }, "gross_pay": { "type": "integer", "example": 300, "default": 0 }, "net_pay": { "type": "integer", "example": 0, "default": 0 }, "employer_taxes": { "type": "integer", "example": 0, "default": 0 }, "employee_taxes": { "type": "integer", "example": 0, "default": 0 }, "employee_deductions": { "type": "integer", "example": 0, "default": 0 }, "employee_garnishments": { "type": "integer", "example": 0, "default": 0 }, "employer_deductions": { "type": "integer", "example": 0, "default": 0 }, "company_debit": { "type": "integer", "example": 0, "default": 0 }, "company_cash_requirement": { "type": "integer", "example": 0, "default": 0 } } }, "shifts": { "type": "array", "items": { "type": "object", "properties": { "shiftID": { "type": "string", "example": "7ea23a1c34b245dde1150bffed65d686" }, "status": {}, "employeeID": { "type": "string", "example": "6cc3cc3f37c91f5f123c25cde490e" }, "employeeCheckID": { "type": "string", "example": "fbd359a66e8f4ae0a3erer3bcab9ada6063" }, "first_name": { "type": "string", "example": "Erlich" }, "last_name": { "type": "string", "example": "Bachman" }, "time": { "type": "string", "example": "2024-09-27T19:38:55Z" }, "metadata": { "type": "object", "properties": {} }, "wcc_code": {}, "workLocationID": {}, "customerAccountID": {}, "flsa_ot_exempt": {}, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-21T21:29:42Z" }, "hourly": { "type": "object", "properties": { "hours": { "type": "integer", "example": 10, "default": 0 }, "wage": { "type": "integer", "example": 30, "default": 0 } } } } } }, "deductions": { "type": "array" } } } } } }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "data": { "success": true, "failed_checks": [ { "employeeID": "6cc3cc3f37c91f5f123c25cde490e", "error": { "message": "This worker does not have a bank account. Please choose download_check or prepaid as the method of disbursement.", "status": 400, "code": 13 } } ], "created_checks": [] }, "success": true, "testMode": true } } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "failed_checks": { "type": "array", "items": { "type": "object", "properties": { "employeeID": { "type": "string", "example": "6cc3cc3f37c91f5f123c25cde490e" }, "error": { "type": "object", "properties": { "message": { "type": "string", "example": "This worker does not have a bank account. Please choose download_check or prepaid as the method of disbursement." }, "status": { "type": "integer", "example": 400, "default": 0 }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } }, "created_checks": { "type": "array" } } }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } } } }, "/paystub/company/{companyID}/check/{employeeCheckID}": { "get": { "summary": "Download Paystub PDF", "description": "Download an employee's paystub in PDF. For US payroll, the employee check must be processed.", "operationId": "download-paystub-pdf", "x-fern-sdk-group-name": "paystub", "x-fern-sdk-method-name": "downloadPdf", "parameters": [ { "name": "companyID", "in": "path", "description": "ID of the company", "schema": { "type": "string" }, "required": true }, { "name": "employeeCheckID", "in": "path", "description": "ID of the employee check to download paystub for", "schema": { "type": "string" }, "required": true }, { "name": "paystubSnapshotRevisionID", "in": "query", "description": "Optional paystub snapshot revision to download.", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "description": "Paystub PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "testMode": false, "errors": [ { "message": "Employee Check with this ID does not exist", "code": 17 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee Check with this ID does not exist" }, "code": { "type": "integer", "example": 17, "default": 0 } } } } } } } } }, "409": { "description": "The paystub is not available because the US employee check has not been processed.", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "testMode": false, "errors": [ { "message": "Paystub is not available until the check is processed.", "code": "PAYSTUB_NOT_AVAILABLE" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "testMode": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Paystub is not available until the check is processed." }, "code": { "type": "string", "example": "PAYSTUB_NOT_AVAILABLE" } } } } } } } } } }, "deprecated": false } }, "/payroll/setup": { "post": { "summary": "Setup Payroll", "description": "", "operationId": "setup-payroll", "x-fern-sdk-group-name": "payroll", "x-fern-sdk-method-name": "setup", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "firstCheckDate", "paySchedule", "reportingPeriodID" ], "properties": { "companyID": { "type": "string" }, "firstCheckDate": { "type": "string", "description": "The first check date this company will be running payroll on.", "format": "date" }, "paySchedule": { "type": "string", "description": "The pay schedule this company will be running payroll on.", "enum": [ "daily", "weekly", "biweekly", "semimonthly", "monthly" ] }, "reportingPeriodID": { "type": "string", "description": "The first pay period for which this company runs payroll." } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": { "user_type": "sole_co", "companyID": "{{companyID}}", "status": "live", "first_name": "someone", "last_name": "random", "email": "some@emaiasdfasfasdfada.coasdfa", "business_name": "Teas Tea", "business_ein": "00-0000000", "business_address": "1 Market Plaza", "business_city": "San Francisco", "business_state": "CA", "business_zip": "94105", "mail_address": "1234", "mail_city": "city", "mail_state": "state", "mail_zip": "123145", "skip_migration": false, "business_phone": "1234253", "account_number": "1234567890", "routing_number": "0987654321", "requirements": [], "onboarding_url": "{{onboardingUrl}}", "is_sandbox": true, "payroll_schedule": "biweekly", "payroll_firstDate": "2023-09-12T07:00:00Z", "payroll_firstPayPeriodID": "6376c294fada4cbf00000000" }, "success": true, "testMode": true } } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user_type": { "type": "string", "example": "sole_co" }, "companyID": { "type": "string", "example": "{{companyID}}" }, "status": { "type": "string", "example": "live" }, "first_name": { "type": "string", "example": "someone" }, "last_name": { "type": "string", "example": "random" }, "email": { "type": "string", "example": "some@emaiasdfasfasdfada.coasdfa" }, "business_name": { "type": "string", "example": "Teas Tea" }, "business_ein": { "type": "string", "example": "00-0000000" }, "business_address": { "type": "string", "example": "1 Market Plaza" }, "business_city": { "type": "string", "example": "San Francisco" }, "business_state": { "type": "string", "example": "CA" }, "business_zip": { "type": "string", "example": "94105" }, "mail_address": { "type": "string", "example": "1234" }, "mail_city": { "type": "string", "example": "city" }, "mail_state": { "type": "string", "example": "state" }, "mail_zip": { "type": "string", "example": "123145" }, "skip_migration": { "type": "boolean", "example": false, "default": true }, "business_phone": { "type": "string", "example": "1234253" }, "account_number": { "type": "string", "example": "1234567890" }, "routing_number": { "type": "string", "example": "0987654321" }, "requirements": { "type": "array" }, "onboarding_url": { "type": "string", "example": "{{onboardingUrl}}" }, "is_sandbox": { "type": "boolean", "example": true, "default": true }, "payroll_schedule": { "type": "string", "example": "biweekly" }, "payroll_firstDate": { "type": "string", "example": "2023-09-12T07:00:00Z" }, "payroll_firstPayPeriodID": { "type": "string", "example": "6376c294fada4cbf00000000" } } }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "curl", "code": "curl --location 'https://api.zeal.com/payroll/setup' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer ' \\\n--data '{\n \"companyID\": \"6c1d1693de2646ac9aff5be900000000\",\n \"firstCheckDate\": \"2023-09-12\",\n \"paySchedule\": \"biweekly\",\n \"reportingPeriodID\": \"6376c294fada4cbf00000000\"\n}'" } ], "samples-languages": ["curl"] } } }, "/payroll/regular": { "get": { "summary": "Get Upcoming Regular Payroll", "description": "Get the upcoming 'regularly' scheduled check date for the company and associated reporting period information.", "operationId": "get-upcoming-regular-payroll", "x-fern-sdk-group-name": "payroll", "x-fern-sdk-method-name": "getUpcomingRegular", "parameters": [ { "name": "companyID", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": { "reportingPeriodID": "6376xx94xxdaxxbfxx1exx78", "start": "2023-09-23", "end": "2023-10-06", "checkDate": "2023-10-10" }, "success": true, "testMode": true } } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "reportingPeriodID": { "type": "string", "example": "6376xx94xxdaxxbfxx1exx78" }, "start": { "type": "string", "example": "2023-09-23" }, "end": { "type": "string", "example": "2023-10-06" }, "checkDate": { "type": "string", "example": "2023-10-10" } } }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/deductionTemplateDefinitions": { "get": { "summary": "Get Deduction Template Definitions", "description": "Get a definition for a deduction template.", "operationId": "get-deduction-template-definitions", "x-fern-sdk-group-name": "deductionTemplate", "x-fern-sdk-method-name": "getDefinitions", "parameters": [ { "name": "deduction_type", "in": "query", "description": "Deduction type for which Deduction Template Definition is required. `garnishment` is deprecated and will no longer be accepted after October 15, 2026. Use POST /garnishments instead.", "required": true, "schema": { "type": "string", "enum": [ "401k", "section_125", "hsa", "miscellaneous", "garnishment", "403b", "roth_ira", "simple_ira", "roth_401k" ] } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "type": "object", "required": [ "employee_contribution", "additional_fields" ], "properties": { "required_template_fields": { "const": ["employee_contribution"] }, "custom_name": { "type": "string" }, "deduction_type": { "const": "hsa" }, "employee_contribution": { "type": "object", "properties": { "contribution_type": { "enum": ["dollars"] }, "value": { "type": "number" }, "override_type": { "enum": ["overridable", "needs_input", "final"] }, "required_template_fields": { "const": ["value"] } }, "allOf": [ { "if": { "properties": { "override_type": { "const": "final" } }, "required": ["override_type"] }, "then": { "required": ["value"] } }, { "if": { "properties": { "override_type": { "const": "overridable" } }, "required": ["override_type"] }, "then": { "required": ["value"] } } ], "required": ["override_type", "contribution_type"] }, "employer_contribution": { "type": "object", "properties": { "contribution_type": { "enum": ["dollars"] }, "value": { "type": "number" }, "override_type": { "enum": ["overridable", "needs_input", "final"] }, "required_template_fields": { "const": ["value"] } }, "allOf": [ { "if": { "properties": { "override_type": { "const": "final" } }, "required": ["override_type"] }, "then": { "required": ["value"] } }, { "if": { "properties": { "override_type": { "const": "overridable" } }, "required": ["override_type"] }, "then": { "required": ["value"] } } ], "required": ["override_type", "contribution_type"] }, "additional_fields": { "type": "object", "properties": { "hsa_type": { "enum": ["family", "individual"] } }, "required": ["hsa_type"] } } } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "type": { "type": "string", "example": "object" }, "required": { "type": "array", "items": { "type": "string", "example": "employee_contribution" } }, "properties": { "type": "object", "properties": { "required_template_fields": { "type": "object", "properties": { "const": { "type": "array", "items": { "type": "string", "example": "employee_contribution" } } } }, "custom_name": { "type": "object", "properties": { "type": { "type": "string", "example": "string" } } }, "deduction_type": { "type": "object", "properties": { "const": { "type": "string", "example": "hsa" } } }, "employee_contribution": { "type": "object", "properties": { "type": { "type": "string", "example": "object" }, "properties": { "type": "object", "properties": { "contribution_type": { "type": "object", "properties": { "enum": { "type": "array", "items": { "type": "string", "example": "dollars" } } } }, "value": { "type": "object", "properties": { "type": { "type": "string", "example": "number" } } }, "override_type": { "type": "object", "properties": { "enum": { "type": "array", "items": { "type": "string", "example": "overridable" } } } }, "required_template_fields": { "type": "object", "properties": { "const": { "type": "array", "items": { "type": "string", "example": "value" } } } } } }, "allOf": { "type": "array", "items": { "type": "object", "properties": { "if": { "type": "object", "properties": { "properties": { "type": "object", "properties": { "override_type": { "type": "object", "properties": { "const": { "type": "string", "example": "final" } } } } }, "required": { "type": "array", "items": { "type": "string", "example": "override_type" } } } }, "then": { "type": "object", "properties": { "required": { "type": "array", "items": { "type": "string", "example": "value" } } } } } } }, "required": { "type": "array", "items": { "type": "string", "example": "override_type" } } } }, "employer_contribution": { "type": "object", "properties": { "type": { "type": "string", "example": "object" }, "properties": { "type": "object", "properties": { "contribution_type": { "type": "object", "properties": { "enum": { "type": "array", "items": { "type": "string", "example": "dollars" } } } }, "value": { "type": "object", "properties": { "type": { "type": "string", "example": "number" } } }, "override_type": { "type": "object", "properties": { "enum": { "type": "array", "items": { "type": "string", "example": "overridable" } } } }, "required_template_fields": { "type": "object", "properties": { "const": { "type": "array", "items": { "type": "string", "example": "value" } } } } } }, "allOf": { "type": "array", "items": { "type": "object", "properties": { "if": { "type": "object", "properties": { "properties": { "type": "object", "properties": { "override_type": { "type": "object", "properties": { "const": { "type": "string", "example": "final" } } } } }, "required": { "type": "array", "items": { "type": "string", "example": "override_type" } } } }, "then": { "type": "object", "properties": { "required": { "type": "array", "items": { "type": "string", "example": "value" } } } } } } }, "required": { "type": "array", "items": { "type": "string", "example": "override_type" } } } }, "additional_fields": { "type": "object", "properties": { "type": { "type": "string", "example": "object" }, "properties": { "type": "object", "properties": { "hsa_type": { "type": "object", "properties": { "enum": { "type": "array", "items": { "type": "string", "example": "family" } } } } } }, "required": { "type": "array", "items": { "type": "string", "example": "hsa_type" } } } } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Unsupported deduction type", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Unsupported deduction type" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": {}, "examples": { "Request Example": { "value": { "success": true, "data": { "type": "object", "required": [ "employee_contribution", "additional_fields" ], "properties": { "required_template_fields": { "const": ["employee_contribution"] }, "custom_name": { "type": "string" }, "deduction_type": { "const": "hsa" }, "employee_contribution": { "type": "object", "properties": { "contribution_type": { "enum": ["dollars"] }, "value": { "type": "number" }, "override_type": { "enum": ["overridable", "needs_input", "final"] }, "required_template_fields": { "const": ["value"] } }, "allOf": [ { "if": { "properties": { "override_type": { "const": "final" } }, "required": ["override_type"] }, "then": { "required": ["value"] } }, { "if": { "properties": { "override_type": { "const": "overridable" } }, "required": ["override_type"] }, "then": { "required": ["value"] } } ], "required": ["override_type", "contribution_type"] }, "employer_contribution": { "type": "object", "properties": { "contribution_type": { "enum": ["dollars"] }, "value": { "type": "number" }, "override_type": { "enum": ["overridable", "needs_input", "final"] }, "required_template_fields": { "const": ["value"] } }, "allOf": [ { "if": { "properties": { "override_type": { "const": "final" } }, "required": ["override_type"] }, "then": { "required": ["value"] } }, { "if": { "properties": { "override_type": { "const": "overridable" } }, "required": ["override_type"] }, "then": { "required": ["value"] } } ], "required": ["override_type", "contribution_type"] }, "additional_fields": { "type": "object", "properties": { "hsa_type": { "enum": ["family", "individual"] } }, "required": ["hsa_type"] } } } } } } } } } } }, "/deductionTemplate": { "post": { "summary": "Create Deduction Template", "description": "Create a deduction template.", "operationId": "create-deduction-template", "x-fern-sdk-group-name": "deductionTemplate", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "custom_name"], "properties": { "companyID": { "type": "string", "description": "ID of Company" }, "custom_name": { "type": "string", "description": "Name assigned to deduction template (this is what will show on paystubs)" }, "deduction_type": { "type": "string", "description": "Type of deduction. `garnishment` is deprecated and will no longer be accepted after October 15, 2026. Use POST /garnishments instead.", "enum": [ "401k", "hsa", "garnishment", "miscellaneous", "section_125", "roth_401k", "403b", "simple_ira", "roth_ira" ], "x-enumDescriptions": { "garnishment": "Deprecated. Use POST /garnishments instead. Sunset October 15, 2026." } }, "employee_contribution": { "type": "object", "description": "Object containing all the fields which are needed to define the employee contribution.", "properties": { "override_type": { "type": "string", "description": "Override type (Accepts: final, overridable, needs_input)" }, "contribution_type": { "type": "string", "description": "Type of contribution (Accepts: dollars, percentage)" }, "value": { "type": "number", "description": "The Value of the employee contribution", "format": "float" } } }, "employer_contribution": { "type": "object", "description": "Object containing all the fields which are needed to define the employer_contribution.", "properties": { "override_type": { "type": "string", "description": "Override type (Accepts: final, overridable, needs_input)" }, "contribution_type": { "type": "string", "description": "Type of contribution (Accepts: dollars, percentage)" }, "value": { "type": "number", "description": "The Value of the employee contribution", "format": "float" } } }, "additional_fields": { "type": "object", "description": "If the Deduction Template Definition contains additional_fields, pass those values here", "properties": {} }, "deduction_credit": { "type": "boolean", "description": "(Customer Accounts Only - Early Access) Denotes whether the deduction should be returned back to the company or not. By default, garnishments and miscellaneous type deductions are not returned back, and all others are." } } }, "examples": { "401k": { "value": { "companyID": "fc235f012baa12312asdasdaseda", "deduction_type": "401k", "custom_name": "Zeal Testing 401k", "employee_contribution": { "contribution_type": "dollars", "value": 20, "override_type": "overridable" }, "employer_contribution": { "contribution_type": "dollars", "matching": false, "value": 30, "override_type": "overridable" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "deductionTemplateID": "61cad98c3e6f8201c34c77c0", "companyID": "fc235f012baa12312asdasdaseda", "custom_name": { "const": "Zeal Testing 401k" }, "deduction_type": { "const": "401k" }, "employee_contribution": { "properties": { "contribution_type": { "const": "dollars" }, "value": { "type": "number", "default": 0 }, "override_type": { "const": "overridable" } }, "required": ["value"] }, "employer_contribution": { "properties": { "contribution_type": { "const": "dollars" }, "percentage_source": { "enum": ["contribution", "paycheck"] }, "matching": { "const": false }, "value": { "type": "number", "default": 0 }, "override_type": { "const": "overridable" } }, "required": ["value"] }, "additional_properties": {} } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "deductionTemplateID": { "type": "string", "example": "61cad98c3e6f8201c34c77c0" }, "companyID": { "type": "string", "example": "fc235f012baa12312asdasdaseda" }, "custom_name": { "type": "object", "properties": { "const": { "type": "string", "example": "Zeal Testing 401k" } } }, "deduction_type": { "type": "object", "properties": { "const": { "type": "string", "example": "401k" } } }, "employee_contribution": { "type": "object", "properties": { "properties": { "type": "object", "properties": { "contribution_type": { "type": "object", "properties": { "const": { "type": "string", "example": "dollars" } } }, "value": { "type": "object", "properties": { "type": { "type": "string", "example": "number" }, "default": { "type": "integer", "example": 0, "default": 0 } } }, "override_type": { "type": "object", "properties": { "const": { "type": "string", "example": "overridable" } } } } }, "required": { "type": "array", "items": { "type": "string", "example": "value" } } } }, "employer_contribution": { "type": "object", "properties": { "properties": { "type": "object", "properties": { "contribution_type": { "type": "object", "properties": { "const": { "type": "string", "example": "dollars" } } }, "percentage_source": { "type": "object", "properties": { "enum": { "type": "array", "items": { "type": "string", "example": "contribution" } } } }, "matching": { "type": "object", "properties": { "const": { "type": "boolean", "example": false, "default": true } } }, "value": { "type": "object", "properties": { "type": { "type": "string", "example": "number" }, "default": { "type": "integer", "example": 0, "default": 0 } } }, "override_type": { "type": "object", "properties": { "const": { "type": "string", "example": "overridable" } } } } }, "required": { "type": "array", "items": { "type": "string", "example": "value" } } } }, "additional_properties": { "type": "object", "properties": {} } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Provided deduction template name already exists", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Provided deduction template name already exists" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false }, "get": { "summary": "Get Deduction Template", "description": "Get a deduction template.", "operationId": "get-deduction-template", "x-fern-sdk-group-name": "deductionTemplate", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "ID of Company", "required": true, "schema": { "type": "string" } }, { "name": "deductionTemplateID", "in": "query", "description": "ID of Deduction template. If no value is passed, then all deduction templates will be retrieved.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "companyID": "fc235f012bae46aa8a082f", "deductionTemplateID": "61cad98c3e6f8201c34c77c0", "custom_name": "Zeal Testing 401k", "deduction_type": "401k", "employer_contribution": { "properties": { "contribution_type": { "const": "dollars" }, "percentage_source": { "enum": ["contribution", "paycheck"] }, "matching": { "const": false }, "value": { "type": "number", "default": 0 }, "override_type": { "const": "overridable" } }, "required": ["value"] }, "employee_contribution": { "properties": { "contribution_type": { "const": "dollars" }, "value": { "type": "number", "default": 0 }, "override_type": { "const": "overridable" } }, "required": ["value"] } } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "companyID": { "type": "string", "example": "fc235f012bae46aa8a082f" }, "deductionTemplateID": { "type": "string", "example": "61cad98c3e6f8201c34c77c0" }, "custom_name": { "type": "string", "example": "Zeal Testing 401k" }, "deduction_type": { "type": "string", "example": "401k" }, "employer_contribution": { "type": "object", "properties": { "properties": { "type": "object", "properties": { "contribution_type": { "type": "object", "properties": { "const": { "type": "string", "example": "dollars" } } }, "percentage_source": { "type": "object", "properties": { "enum": { "type": "array", "items": { "type": "string", "example": "contribution" } } } }, "matching": { "type": "object", "properties": { "const": { "type": "boolean", "example": false, "default": true } } }, "value": { "type": "object", "properties": { "type": { "type": "string", "example": "number" }, "default": { "type": "integer", "example": 0, "default": 0 } } }, "override_type": { "type": "object", "properties": { "const": { "type": "string", "example": "overridable" } } } } }, "required": { "type": "array", "items": { "type": "string", "example": "value" } } } }, "employee_contribution": { "type": "object", "properties": { "properties": { "type": "object", "properties": { "contribution_type": { "type": "object", "properties": { "const": { "type": "string", "example": "dollars" } } }, "value": { "type": "object", "properties": { "type": { "type": "string", "example": "number" }, "default": { "type": "integer", "example": 0, "default": 0 } } }, "override_type": { "type": "object", "properties": { "const": { "type": "string", "example": "overridable" } } } } }, "required": { "type": "array", "items": { "type": "string", "example": "value" } } } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/deductions": { "post": { "summary": "Create Deduction", "description": "Create a deduction.", "operationId": "create-deduction", "x-fern-sdk-group-name": "deductions", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "employeeCheckID", "deductionTemplateID", "deduction" ], "properties": { "companyID": { "type": "string", "description": "ID of Company" }, "employeeCheckID": { "type": "string", "description": "ID of EmployeeCheck to attach Deduction to" }, "deductionTemplateID": { "type": "string", "description": "ID of Deduction Template used to create this deduction" }, "deduction": { "type": "object", "description": "The deduction object", "properties": { "employee_contribution": { "type": "object", "properties": { "override_type": { "type": "string", "description": "Override type (Accepts: final, overridable, needs_input)" }, "contribution_type": { "type": "string", "description": "Type of contribution (Accepts: dollars, percentage)" }, "value": { "type": "number", "description": "The Value of the employee contribution", "format": "float" } } }, "employer_contribution": { "type": "object", "properties": { "value": { "type": "number", "description": "Value of Employer contribution", "format": "float" }, "contribution_type": { "type": "string", "description": "Type of contribution (Accepts: dollars, percentage)" } } } } }, "additional_fields": { "type": "object", "description": "Additional fields contingent upon the deduction type/template", "properties": {} } } }, "examples": { "Request Example": { "value": { "companyID": "fc235f012bae46aa8a082f3", "employeeCheckID": "7f0da5e428324c049ae6a6bac2e62f88", "deductionTemplateID": "61d12e74db7df700237de5d4", "deduction": { "employee_contribution": { "value": 1.33 }, "employer_contribution": { "value": 2.66 } } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "fc235f012bae46aa8a082f3", "deductionID": "61cadff23e6f8201c34c77c6", "employeeCheckID": "73a99095827d4f32bbb18adce048c081", "deduction_type": "401k", "employer_contribution": { "value": 1.33, "contribution_type": "dollars", "matching": false }, "employee_contribution": { "value": 2.66, "contribution_type": "dollars" }, "deductionTemplateID": "61cad98c3e6f8201c34c77c0" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "fc235f012bae46aa8a082f3" }, "deductionID": { "type": "string", "example": "61cadff23e6f8201c34c77c6" }, "employeeCheckID": { "type": "string", "example": "73a99095827d4f32bbb18adce048c081" }, "deduction_type": { "type": "string", "example": "401k" }, "employer_contribution": { "type": "object", "properties": { "value": { "type": "number", "example": 1.33, "default": 0 }, "contribution_type": { "type": "string", "example": "dollars" }, "matching": { "type": "boolean", "example": false, "default": true } } }, "employee_contribution": { "type": "object", "properties": { "value": { "type": "number", "example": 2.66, "default": 0 }, "contribution_type": { "type": "string", "example": "dollars" } } }, "deductionTemplateID": { "type": "string", "example": "61cad98c3e6f8201c34c77c0" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No deduction template found with provided ID", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No deduction template found with provided ID" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false }, "get": { "summary": "Get Deduction", "description": "Get a specific deduction.", "operationId": "retrieve-deduction", "x-fern-sdk-group-name": "deductions", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "deductionID", "in": "query", "description": "ID of Deduction to be retrieved", "required": true, "schema": { "type": "string" } }, { "name": "companyID", "in": "query", "description": "CompanyID of the employer", "required": true, "schema": { "type": "string" } }, { "name": "employeeCheckID", "in": "query", "description": "ID of the employee check", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "deductionID": "61d32bb356fdba0023fafa57", "deduction_type": "401k", "employer_contribution": { "value": 7, "contribution_type": "dollars", "matching": false }, "employee_contribution": { "value": 5, "contribution_type": "percentage" }, "employee_calculated_contribution": 96.61, "deductionTemplateID": "61cadff23e6f8201c34c77c6" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "deductionID": { "type": "string", "example": "61d32bb356fdba0023fafa57" }, "deduction_type": { "type": "string", "example": "401k" }, "employer_contribution": { "type": "object", "properties": { "value": { "type": "integer", "example": 7, "default": 0 }, "contribution_type": { "type": "string", "example": "dollars" }, "matching": { "type": "boolean", "example": false, "default": true } } }, "employee_contribution": { "type": "object", "properties": { "value": { "type": "integer", "example": 5, "default": 0 }, "contribution_type": { "type": "string", "example": "percentage" } } }, "employee_calculated_contribution": { "type": "number", "example": 96.61, "default": 0 }, "deductionTemplateID": { "type": "string", "example": "61cadff23e6f8201c34c77c6" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee Check with this check ID does not exist", "code": 43 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee Check with this check ID does not exist" }, "code": { "type": "integer", "example": 43, "default": 0 } } } } } } } } } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": {}, "examples": { "Request Example": { "value": { "companyID": "fc235f012bae46aa8a082f3", "employeeCheckID": "7f0da5e428324c049ae6a6bac2e62f88", "deductionID": "61d32bb356fdba0023fafa57" } } } } } } }, "patch": { "summary": "Update Deduction", "description": "Update a deduction.", "operationId": "update-deduction", "x-fern-sdk-group-name": "deductions", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "employeeCheckID", "deductionID", "deduction" ], "properties": { "companyID": { "type": "string", "description": "ID of Company" }, "employeeCheckID": { "type": "string", "description": "ID of Employee Check" }, "deductionID": { "type": "string", "description": "ID of Deduction to be updated" }, "deduction": { "type": "array", "description": "Contribution details to be updated", "items": { "properties": { "employee_contribution": { "type": "object", "properties": { "override_type": { "type": "string", "description": "Override type (Accepts: final, overridable, needs_input)" }, "contribution_type": { "type": "string", "description": "Type of contribution (Accepts: dollars, percentage)" }, "value": { "type": "number", "description": "The Value of the employee contribution", "format": "float" } } }, "employer_contribution": { "type": "object", "properties": { "value": { "type": "number", "description": "Value of Employer contribution", "format": "float" }, "contribution_type": { "type": "string", "description": "Type of contribution (Accepts: dollars, percentage)" } } } }, "type": "object" } } } }, "examples": { "Request Example": { "value": { "companyID": "fc235f012bae46aa8a082f3", "employeeCheckID": "7f0da5e428324c049ae6a6bac2e62f88", "deductionID": "61d12e74db7df700237de5d4", "deduction": { "employee_contribution": { "value": 10, "contribution_type": "percentage" }, "employer_contribution": { "value": 20, "contribution_type": "dollars" } } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "fc235f012bae46aa8a082f3", "deductionID": "61cae1e03e6f8201c34c77ca", "employeeCheckID": "73a99095827d4f32bbb18adce048c081", "deduction_type": "hsa", "employer_contribution": { "value": 3, "contribution_type": "dollars", "matching": false }, "employee_contribution": { "value": 2, "contribution_type": "dollars" }, "deductionTemplateID": "61cae1e03e6f8201c34c77ca" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "fc235f012bae46aa8a082f3" }, "deductionID": { "type": "string", "example": "61cae1e03e6f8201c34c77ca" }, "employeeCheckID": { "type": "string", "example": "73a99095827d4f32bbb18adce048c081" }, "deduction_type": { "type": "string", "example": "hsa" }, "employer_contribution": { "type": "object", "properties": { "value": { "type": "integer", "example": 3, "default": 0 }, "contribution_type": { "type": "string", "example": "dollars" }, "matching": { "type": "boolean", "example": false, "default": true } } }, "employee_contribution": { "type": "object", "properties": { "value": { "type": "integer", "example": 2, "default": 0 }, "contribution_type": { "type": "string", "example": "dollars" } } }, "deductionTemplateID": { "type": "string", "example": "61cae1e03e6f8201c34c77ca" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false }, "delete": { "summary": "Delete Deduction", "description": "Delete a deduction.", "operationId": "delete-deduction", "x-fern-sdk-group-name": "deductions", "x-fern-sdk-method-name": "delete", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "deductionID", "employeeCheckID"], "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "deductionID": { "type": "string", "description": "ID of the deduction to be deleted" }, "employeeCheckID": { "type": "string", "description": "corresponding employeeCheckID in which the deduction is attached to" } } }, "examples": { "Request Example": { "value": { "companyID": "fc235f012bae46aa8a082f3", "employeeCheckID": "7f0da5e428324c049ae6a6bac2e62f88", "deductionID": "61d32bb356fdba0023fafa57" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "employeeCheckID": "fc235f012bae46aa8a082f3", "deductionID": "61d32bb356fdba0023fafa57", "deduction_type": "hsa", "employer_contribution": { "value": 3, "contribution_type": "dollars", "matching": false }, "employee_contribution": { "value": 2, "contribution_type": "dollars" }, "deductionTemplateID": "61cae1e03e6f8201c34c77ca" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "employeeCheckID": { "type": "string", "example": "fc235f012bae46aa8a082f3" }, "deductionID": { "type": "string", "example": "61d32bb356fdba0023fafa57" }, "deduction_type": { "type": "string", "example": "hsa" }, "employer_contribution": { "type": "object", "properties": { "value": { "type": "integer", "example": 3, "default": 0 }, "contribution_type": { "type": "string", "example": "dollars" }, "matching": { "type": "boolean", "example": false, "default": true } } }, "employee_contribution": { "type": "object", "properties": { "value": { "type": "integer", "example": 2, "default": 0 }, "contribution_type": { "type": "string", "example": "dollars" } } }, "deductionTemplateID": { "type": "string", "example": "61cae1e03e6f8201c34c77ca" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/shifts": { "post": { "summary": "Add Shifts to Existing Check", "description": "", "operationId": "add-shifts-to-existing-check", "x-fern-sdk-group-name": "shifts", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["shifts", "companyID", "employeeCheckID"], "properties": { "shifts": { "type": "array", "description": "List of [Shift Object](ref:shift-object) that need to be added to the employee check.", "items": { "properties": { "time": { "type": "string", "description": "ISO-8601 indicating when the shift was completed", "format": "date-time" }, "hourly": { "type": "object", "required": ["hours"], "properties": { "hours": { "type": "number", "description": "Number of regular hours worked in this shift", "default": 0, "format": "float" }, "wage": { "type": "number", "description": "Wage for this employee. If not provided, Zeal uses employee's default_wage", "default": 0, "format": "float" }, "custom_name": { "type": "string", "description": "Custom name to be attached to an earning component" } } } }, "required": ["time"], "type": "object" } }, "companyID": { "type": "string", "description": "Company ID of the employer" }, "employeeCheckID": { "type": "string", "description": "ID of Employee Check that the shift should be added to" } } }, "examples": { "Request Example": { "value": { "shifts": [ { "hourly": { "hours": 10, "wage": 33, "custom_name": "hourly" }, "overtime": { "hours": 2 }, "time": "2023-3-29" } ], "companyID": "fc235f092bwe46aa8a082f357715bcfa", "employeeCheckID": "f251842623e942d6bab6ad2bca436d95" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "employeeCheckID": "9827465739", "employerCheckID": null, "companyID": "1b5n28nrideucd24", "employeeID": "1234567890", "status": "pending", "first_name": "erlich", "middle_initial": null, "last_name": "bachman", "reportingPeriodID": "0982349584387523234", "check_date": "2023-10-07", "metadata": { "checkCorrelationID": "1" }, "disbursement": { "method": "direct_deposit" }, "net_pay": null, "taxes": null, "total_employer_taxes": null, "total_employee_taxes": null, "shifts": [ { "employeeID": "1234567890", "shiftID": "123456789", "first_name": "erlich", "last_name": "bachman", "metadata": {}, "time": "2023-01-12T10:00:00", "workLocationID": "bcc34345ereretwe3rw31234ee", "updatedAt": "2024-01-21T21:29:42Z", "hourly": { "hours": 2, "wage": 20 } } ] } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Shift object(s) is missing required fields or has improperly formatted data", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Shift object(s) is missing required fields or has improperly formatted data" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false }, "get": { "summary": "Get Shift Information", "description": "", "operationId": "retrieve-shift-information", "x-fern-sdk-group-name": "shifts", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of the employer", "required": true, "schema": { "type": "string" } }, { "name": "shiftID", "in": "query", "description": "Shift ID of the shift", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "shiftID": "4712c99283304b7b989179aae36b4590", "employeeID": "1234567890", "employeeCheckID": "1095673922", "first_name": "erlich", "last_name": "bachman", "time": "2023-12-13T04:00:00Z", "metadata": {}, "updatedAt": "2024-01-21T21:29:42Z", "hourly": { "hours": 8, "wage": 20, "custom_name": "hourly" }, "reimbursement": { "amount": 8.5 } } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "shiftID": { "type": "string", "example": "4712c99283304b7b989179aae36b4590" }, "employeeID": { "type": "string", "example": "1234567890" }, "employeeCheckID": { "type": "string", "example": "1095673922" }, "first_name": { "type": "string", "example": "erlich" }, "last_name": { "type": "string", "example": "bachman" }, "time": { "type": "string", "example": "2023-12-13T04:00:00Z" }, "metadata": { "type": "object", "properties": {} }, "hourly": { "type": "object", "properties": { "hours": { "type": "integer", "example": 8, "default": 0 }, "wage": { "type": "integer", "example": 20, "default": 0 }, "custom_name": { "type": "string", "example": "hourly" } } }, "reimbursement": { "type": "object", "properties": { "amount": { "type": "number", "example": 8.5, "default": 0 } } }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp of when the shift was last modified", "example": "2024-01-21T21:29:42Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No shiftID in the query of request", "code": 26 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No shiftID in the query of request" }, "code": { "type": "integer", "example": 26, "default": 0 } } } } } } } } } }, "deprecated": false }, "patch": { "summary": "Update Pending Shifts", "description": "", "operationId": "update-pending-shifts", "x-fern-sdk-group-name": "shifts", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "shifts"], "properties": { "companyID": { "type": "string", "description": "Company ID of the employer" }, "shifts": { "type": "array", "description": "List of [Shift Object](ref:shift-object) fields. The patchable fields are the actual shift time & earning components.", "items": { "type": "string" } } } }, "examples": { "Request Example": { "value": { "companyID": "ccf239880ccmneu847zefze84", "shifts": [ { "shiftID": "4712c9923383304b7b989179aae36b4590", "reimbursement": { "amount": 20 } } ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "shiftID": "4712c9923383304b7b989179aae36b4590", "status": "pending", "employeeID": "1234567890", "employeeCheckID": "0843792216", "time": "2023-12-13T00:00:00Z", "metadata": {}, "updatedAt": "2024-01-21T21:29:42Z", "hourly": { "hours": 2.5, "wage": 20, "custom_name": "hourly" } }, { "shiftID": "6712c99283304b7b989179aae36b4591", "status": "pending", "employeeID": "1234567890", "employeeCheckID": "0843792216", "time": "2023-12-13T00:00:00Z", "metadata": {}, "updatedAt": "2024-01-21T21:29:42Z", "reimbursement": { "amount": 20 } } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "shiftID": { "type": "string" }, "status": { "type": "string" }, "employeeID": { "type": "string" }, "employeeCheckID": { "type": "string" }, "time": { "type": "string", "format": "date-time" }, "metadata": { "type": "object" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp of when the shift was last modified", "example": "2024-01-21T21:29:42Z" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No shiftID in the query of request", "code": 26 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No shiftID in the query of request" }, "code": { "type": "integer", "example": 26, "default": 0 } } } } } } } } } }, "deprecated": false }, "delete": { "summary": "Delete Pending Shifts", "description": "", "operationId": "delete-pending-shifts", "x-fern-sdk-group-name": "shifts", "x-fern-sdk-method-name": "delete", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of the employer", "required": true, "schema": { "type": "string" } }, { "name": "shiftID", "in": "query", "description": "ID of Shift", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "message": "Shift(s) deleted." } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "message": { "type": "string", "example": "Shift(s) deleted." } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/paycards": { "get": { "summary": "Get Paycards", "description": "", "operationId": "get-paycard", "x-fern-sdk-group-name": "paycards", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Zeal company ID", "required": true, "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "description": "Zeal employee ID", "schema": { "type": "string" } }, { "name": "contractorID", "in": "query", "description": "Zeal contractor ID", "schema": { "type": "string" } }, { "name": "paycardID", "in": "query", "description": "Paycard ID", "schema": { "type": "string" } }, { "name": "start_at", "in": "query", "schema": { "type": "string" } }, { "name": "end_at", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 25 } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "paycardID": "f15b00a4bce0e60d52bf0f0a", "companyID": "bf015b00e052f60cfb0e4a0d", "employeeID": "d210f054bf5b006f50aecbe0", "contractorID": null, "status": "active", "card_type": "virtual" } ], "meta": { "next": "https://api.zeal.com/paycard?start_at=f15b00a4bce0e60d52bf0f1a", "previous": null } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Contractor Payment with this payment ID does not exist", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor Payment with this payment ID does not exist" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/employees/instant-pay": { "post": { "summary": "Create Instant Pay Enrollment Link", "description": "", "operationId": "create-instant-pay-enrollment-link", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "createInstantPayEnrollmentLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID"], "properties": { "companyID": { "type": "string", "description": "ID of the Company" }, "employeeID": { "type": "string", "description": "ID of the Employee" }, "send_to_worker": { "type": "boolean", "description": "If true, notification email will be sent to employee", "default": false } } }, "examples": { "Request Example": { "value": { "companyID": "3f5c2afcc5ea40c87a2c8f3f7e5a1cb1", "employeeID": "c2fc3a5fe5c74ca08a38f5f7b1a2ec15" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": "https://payroll.your-domain.com/employee-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ", "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://payroll.your-domain.com/employee-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ" }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23, "status": 400, "correlationId": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } ], "success": false, "testMode": true } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/card": { "get": { "summary": "Get Card", "description": "", "operationId": "get-card", "x-fern-sdk-group-name": "card", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "ID of Company", "required": true, "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "required": false, "description": "Zeal employee ID", "schema": { "type": "string", "default": "" } }, { "name": "contractorID", "in": "query", "required": false, "description": "Zeal contractor ID", "schema": { "type": "string", "default": "" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "cardID": "f15b00a4bce0e60d52bf0f0a", "companyID": "bf015b00e052f60cfb0e4a0d", "employeeID": "d210f054bf5b006f50aecbe0", "contractorID": null, "status": "active", "last_four": "0432" } ], "testMode": false } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": {}, "description": "Card object" }, "testMode": { "type": "boolean" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/wallet": { "get": { "summary": "Get Wallet Balance", "description": "", "operationId": "get-wallet-balance", "x-fern-sdk-group-name": "wallet", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "ID of Company", "required": true, "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "description": "Zeal employee ID", "schema": { "type": "string" } }, { "name": "contractorID", "in": "query", "description": "Zeal contractor ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "walletID": "954918f937934c753c944a97d04c5334", "companyID": "bf015b00e052f60cfb0e4a0d", "employeeID": "d210f054bf5b006f50aecbe0", "contractorID": null, "current_balance": 546.9, "available_balance": 546.9 } ], "testMode": false } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": {}, "description": "Wallet Object" }, "testMode": { "type": "boolean" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/wallet/transfer": { "post": { "summary": "Transfer Funds", "description": "", "operationId": "card-ptc-transfer", "x-fern-sdk-group-name": "wallet", "x-fern-sdk-method-name": "createTransfer", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "amount"], "properties": { "companyID": { "type": "string", "description": "ID of company" }, "employeeID": { "type": "string", "description": "Zeal employee ID" }, "contractorID": { "type": "string", "description": "Zeal contractor ID" }, "amount": { "type": "number", "description": "The total amount (gross) to transfer to this worker's card", "format": "float" }, "connection": { "type": "object", "description": "Connect this transfer to an employee check or contractor payment in Zeal", "properties": { "connection_type": { "type": "string", "enum": ["employee_check", "contractor_payment"] }, "connectionID": { "type": "string", "description": "Employee Check ID or Contractor Payment ID, depending on `connection_type`" } } }, "cardID": { "type": "string" }, "bankAccountID": { "type": "string" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "walletTransactionID": "d21a3b12e051f60cfb014b1d", "type": "debit", "companyID": "bf015b00e052f60cfb0e4a0d", "employeeID": "d210f054bf5b006f50aecbe0", "contractorID": null, "bankAccountID": null, "cardID": "10c313104851406408f4130be0540451", "status": "settled", "description": "Instant transfer", "gross_amount": 102, "partner_fee": 1, "zeal_fee": 1, "net_amount": 100, "last_four": "0432", "date": "2025-08-02T23:00:00.000Z" }, "testMode": false } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": {}, "description": "Wallet Transaction Object" }, "testMode": { "type": "boolean" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/wallet/transactions": { "get": { "summary": "Get Wallet Transactions", "description": "", "operationId": "get-wallet-transactions", "x-fern-sdk-group-name": "wallet", "x-fern-sdk-method-name": "getTransactions", "parameters": [ { "name": "companyID", "in": "query", "description": "ID of Company", "required": true, "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "description": "Zeal employeeID", "schema": { "type": "string" } }, { "name": "contractorID", "in": "query", "description": "Zeal contractor ID", "schema": { "type": "string" } }, { "name": "walletTransactionID", "in": "query", "description": "Wallet Transaction ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "walletTransactionID": "c2213b02e052f60cfb0e4ba4", "type": "credit", "companyID": "bf015b00e052f60cfb0e4a0d", "employeeID": "d210f054bf5b006f50aecbe0", "contractorID": null, "bankAccountID": null, "cardID": null, "status": "settled", "description": "Payment", "gross_amount": 1000, "partner_fee": 0, "zeal_fee": 0, "net_amount": 1000, "last_four": null, "date": "2025-08-01T23:00:00.000Z" }, { "walletTransactionID": "d21a3b12e051f60cfb014b1d", "type": "debit", "companyID": "bf015b00e052f60cfb0e4a0d", "employeeID": "d210f054bf5b006f50aecbe0", "contractorID": null, "bankAccountID": null, "cardID": "10c313104851406408f4130be0540451", "status": "settled", "description": "Instant transfer", "gross_amount": 102, "partner_fee": 1, "zeal_fee": 1, "net_amount": 100, "last_four": "0432", "date": "2025-08-02T23:00:00.000Z" } ], "testMode": false } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "properties": {}, "type": "object" }, "description": "Array of Wallet Transaction objects" }, "testMode": { "type": "boolean" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/directPayments": { "post": { "summary": "Create Direct Payment", "description": "", "operationId": "create-direct-payment", "x-fern-sdk-group-name": "directPayments", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "amount"], "properties": { "companyID": { "type": "string", "description": "Zeal Company ID" }, "employeeID": { "type": "string", "description": "Zeal employee ID (required if no contractorID is provided)" }, "contractorID": { "type": "string", "description": "Zeal contractor ID (required if no employeeID is provided)" }, "amount": { "type": "string", "description": "Amount of the transaction" }, "disbursement_method": { "type": "string", "description": "Default: `direct_deposit_same_day`", "enum": [ "direct_deposit", "direct_deposit_same_day", "paycard", "instant_pay" ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "directPaymentID": "a0bfc150f02d05e0eb40d65b", "companyID": "b0a5f0e60d2f41b0ec5b0a", "employeeID": "5b02f60aed0c0bf1b504e0a", "contractorID": null, "bankAccountID": "0e5b40f2a01bcfd0b6e50a", "last_four": "4763", "status": "processing", "amount": 5.5, "disbursement_method": "direct_deposit_same_day" }, "testMode": false } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "directPaymentID": { "type": "string", "example": "a0bfc150f02d05e0eb40d65b" }, "companyID": { "type": "string", "example": "b0a5f0e60d2f41b0ec5b0a" }, "employeeID": { "type": "string", "example": "5b02f60aed0c0bf1b504e0a" }, "contractorID": {}, "bankAccountID": { "type": "string", "example": "0e5b40f2a01bcfd0b6e50a" }, "last_four": { "type": "string", "example": "4763" }, "status": { "type": "string", "example": "processing" }, "amount": { "type": "number", "example": 5.5, "default": 0 } } }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Contractor Payment with this payment ID does not exist", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor Payment with this payment ID does not exist" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "curl", "code": "curl --request POST \\\n --url https://api.zeal.com/directPayments \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '\n{\n \"companyID\": \"b0a5f0e60d2f41b0ec5b0a\",\n \"employeeID\": \"5b02f60aed0c0bf1b504e0a\",\n \"amount\": 5.50\n}\n'" } ], "samples-languages": ["curl"] } }, "get": { "summary": "Get Direct Payments", "description": "", "operationId": "get-direct-payment", "x-fern-sdk-group-name": "directPayments", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Zeal Company ID", "required": true, "schema": { "type": "string" } }, { "name": "directPaymentID", "in": "query", "description": "Direct Payment ID", "schema": { "type": "string" } }, { "name": "contractorID", "in": "query", "description": "Contractor ID", "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "description": "Employee ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "directPaymentID": "a0bfc150f02d05e0eb40d65b", "companyID": "b0a5f0e60d2f41b0ec5b0a", "employeeID": "5b02f60aed0c0bf1b504e0a", "contractorID": null, "bankAccountID": "0e5b40f2a01bcfd0b6e50a", "last_four": "4763", "status": "processing", "amount": 5.5, "disbursement_method": "direct_deposit_same_day" } ], "testMode": false } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "directPaymentID": { "type": "string", "example": "a0bfc150f02d05e0eb40d65b" }, "companyID": { "type": "string", "example": "b0a5f0e60d2f41b0ec5b0a" }, "employeeID": { "type": "string", "example": "5b02f60aed0c0bf1b504e0a" }, "contractorID": {}, "bankAccountID": { "type": "string", "example": "0e5b40f2a01bcfd0b6e50a" }, "last_four": { "type": "string", "example": "4763" }, "status": { "type": "string", "example": "processing" }, "amount": { "type": "number", "example": 5.5, "default": 0 } } } }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Contractor Payment with this payment ID does not exist", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor Payment with this payment ID does not exist" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/employerCheck": { "get": { "summary": "Get All Employer Checks", "description": "", "operationId": "retrieve-all-employer-checks", "x-fern-sdk-group-name": "employerCheck", "x-fern-sdk-method-name": "list", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of the employer", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "employerCheckID": "123456789", "createdAt": "2023-05-09T22:00:00Z", "reporting_periods": [ "01739fc4cfd84c2e93dba5e802d1dda2", "01739fc4cfd84c2e93dba5e802d1dda3" ] }, { "employerCheckID": "787654320", "createdAt": "2023-05-20T22:00:00Z", "reporting_periods": [ "01739fc4cfd84c2e93dba5e802d1dda5", "01739fc4cfd84c2e93dba5e802d1dda6" ] }, { "employerCheckID": "987654321", "createdAt": "2023-05-10T22:00:00Z", "reporting_periods": [ "01739fc4cfd84c2e93dba5e802d1dda0", "01739fc4cfd84c2e93dba5e802d1dda1" ] } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "employerCheckID": { "type": "string", "example": "123456789" }, "createdAt": { "type": "string", "example": "2023-05-09T22:00:00Z" }, "reporting_periods": { "type": "array", "items": { "type": "string", "example": "01739fc4cfd84c2e93dba5e802d1dda2" } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No user with this companyID exists", "code": 4 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No user with this companyID exists" }, "code": { "type": "integer", "example": 4, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/preview/checks": { "post": { "summary": "Preview Payroll by Check IDs", "description": "", "operationId": "preview-payroll-by-checkid", "x-fern-sdk-group-name": "preview", "x-fern-sdk-method-name": "createPayrollByCheckid", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "checks"], "properties": { "companyID": { "type": "string", "description": "The ID of the Company" }, "checks": { "type": "array", "description": "The ID of the Employee Check. This endpoint can accept an array of employeeCheckIDs", "items": { "type": "string" } } } }, "examples": { "Request Example": { "value": { "companyID": "h0c56cc41q1040ac8a3322342a3bbb462", "checks": [ "c614c5ff59d7cc22eae4c9442f315", "22cdbd897e3345a55c3fa22b1712be52", "3942348bd453410485cd783ef1ce8391" ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "status": 200, "success": true, "data": { "job_id": "232c21f1-cc24-4664-8420-393d0acd21351", "status": "pending", "request_body": { "companyID": "h0c56cc41q1040ac8a3322342a3bbb462", "checks": [ "c614c5ff59d7cc22eae4c9442f315", "22cdbd897e3345a55c3fa22b1712be52", "3942348bd453410485cd783ef1ce8391" ], "test_mode": false, "job_type": "preview-checks", "has_live_key": true }, "created_at": "2023-05-04T19:29:39.134Z" } } } }, "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 200, "default": 0 }, "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "232c21f1-cc24-4664-8420-393d0acd21351" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "companyID": { "type": "string", "example": "h0c56cc41q1040ac8a3322342a3bbb462" }, "checks": { "type": "array", "items": { "type": "string", "example": "c614c5ff59d7cc22eae4c9442f315" } }, "test_mode": { "type": "boolean", "example": false, "default": true }, "job_type": { "type": "string", "example": "preview-checks" }, "has_live_key": { "type": "boolean", "example": true, "default": true } } }, "created_at": { "type": "string", "example": "2023-05-04T19:29:39.134Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee Check with this check ID does not exist", "code": 43 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee Check with this check ID does not exist" }, "code": { "type": "integer", "example": 43, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/preview/checkDate": { "post": { "summary": "Preview Payroll by Check Date", "description": "", "operationId": "preview-payroll-by-check-date", "x-fern-sdk-group-name": "preview", "x-fern-sdk-method-name": "createPayrollByCheckDate", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "check_date"], "properties": { "companyID": { "type": "string", "description": "ID of the Company" }, "check_date": { "type": "string", "description": "The date on which the check was created" } } }, "examples": { "Request Example": { "value": { "companyID": "fcce6cc41440ac8a33e13223bbb462", "check_date": "2023-04-29T18:21:28.951Z" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "status": 200, "success": true, "data": { "job_id": "0bc12668-9f1a-4fb6-b1c7-044d23fb678f", "status": "pending", "request_body": { "companyID": "fcce6cc41440ac8a33e13223bbb462", "check_date": "2023-04-29T18:21:28.951Z", "test_mode": false }, "created_at": "2023-05-04T19:49:31.064Z" } } } }, "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 200, "default": 0 }, "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "0bc12668-9f1a-4fb6-b1c7-044d23fb678f" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "companyID": { "type": "string", "example": "fcce6cc41440ac8a33e13223bbb462" }, "check_date": { "type": "string", "example": "2023-04-29T18:21:28.951Z" }, "test_mode": { "type": "boolean", "example": false, "default": true } } }, "created_at": { "type": "string", "example": "2023-05-04T19:49:31.064Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Invalid check date", "code": 74 } ] } } } } } } }, "deprecated": false } }, "/preview/checkData": { "post": { "summary": "Preview Check Data", "description": "", "operationId": "preview-check-data", "x-fern-sdk-group-name": "preview", "x-fern-sdk-method-name": "createCheckData", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "employeeID", "reportingPeriodID", "check_date", "shifts" ], "properties": { "companyID": { "type": "string", "description": "The ID of the Company" }, "employeeID": { "type": "string", "description": "The ID of the employee" }, "reportingPeriodID": { "type": "string", "description": "ID of the reporting period" }, "check_date": { "type": "string", "description": "Check date for this employee", "format": "date" }, "approval_required": { "type": "boolean", "description": "Determine if approval is required for the check, defaults to false", "default": false }, "metadata": { "type": "object", "description": "Custom object you can attach to the employee check object. This is useful for storing additional information about the object in a custom, structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata. [Metadata](ref:metadata)", "properties": {} }, "deductions": { "type": "object", "description": "Adds a Deduction to this hypothetical Employee Check, using a Deduction Template, for a Company. Accepts both check-scoped Deduction Templates and employee Deduction Templates. This endpoint never loads an existing check, so every deduction you want reflected in the preview must be listed here.", "required": ["deductionTemplateID"], "properties": { "employer_contribution": { "type": "object", "description": "Employer contribution for the deduction", "properties": { "value": { "type": "number", "description": "Value of Employer contribution", "format": "float" }, "contribution_type": { "type": "string", "description": "Type of contribution (Accepts: dollars, percentage)" } } }, "employee_contribution": { "type": "object", "description": "Employee contribution for the deduction", "properties": { "override_type": { "type": "string", "description": "Override type (Accepts: final, overridable, needs_input)" }, "contribution_type": { "type": "string", "description": "Type of contribution (Accepts: dollars, percentage)" }, "value": { "type": "number", "description": "The Value of the employee contribution", "format": "float" } } }, "deductionTemplateID": { "type": "string", "description": "ID of the deduction template. Accepts a 24-character check-scoped deduction template ID (from `/deductionTemplate`) or a 32-character employee deduction template ID (from `/employee-deduction-templates`). Employee deduction templates apply with their own saved contribution, so `employee_contribution` and `employer_contribution` are optional overrides. A template is ignored if it is archived, is outside its effective date range on `check_date`, or is a Zeal-managed garnishment (already applied automatically)." } } }, "shifts": { "type": "array", "description": "Array of shift objects. The set of shifts attached to this employee check describe the work done and the earnings owed to this employee. You can only create shifts by creating an employee check (through this endpoint). However, you can edit and delete shifts that are still pending. Also supports various earning components as objects. See [Shift Object](ref:shift-object) for more information.", "items": { "properties": { "time": { "type": "string", "description": "ISO-8601 indicating when the shift was completed", "format": "date-time" }, "hourly": { "type": "object", "required": ["hours"], "properties": { "hours": { "type": "number", "description": "Number of regular hours worked in this shift", "default": 0, "format": "float" }, "wage": { "type": "number", "description": "Wage for this employee. If not provided, Zeal uses employee's default_wage", "default": 0, "format": "float" }, "custom_name": { "type": "string", "description": "Custom name to be attached to an earning component" } } } }, "required": ["time"], "type": "object" } }, "flsa_ot_recommendation": { "type": "boolean", "default": false } } }, "examples": { "Request Example": { "value": { "companyID": "232414e556443cvc34558vv", "employeeID": "3412eee0494585vvrt39485", "reportingPeriodID": "5b3948753ere93484c", "check_date": "2023-12-24", "shifts": [ { "time": "2023-11-15", "flat": { "hours": 80, "amount": 1125 } }, { "time": "2023-11-15", "flat": { "hours": 80, "amount": 375 } }, { "time": "2023-11-15", "flat": { "hours": 80, "amount": 500 } } ], "deductions": [ { "deductionTemplateID": "5b35348948753ere93484c", "employee_contribution": { "value": 100, "contribution_type": "dollars" }, "employer_contribution": { "override_type": "", "value": 8 } } ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "success": true, "result": { "checks": [ { "gross_pay": "2000.00", "net_pay": "1452.98", "employer_taxes": "368.31", "employee_taxes": "447.02", "employee_deductions": "100.00", "employer_deductions": "8.00", "taxes": [ { "name": "Federal Income Tax", "codename": "FIT", "amount": "149.58", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Social Security", "codename": "FICA_SocialSecurity_EE", "amount": "124.00", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Social Security", "codename": "FICA_SocialSecurity_ER", "amount": "124.00", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "Medicare", "codename": "FICA_Medicare_EE", "amount": "29.00", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Medicare", "codename": "FICA_Medicare_ER", "amount": "29.00", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "Medicare Additional", "codename": "FICA_MedicareAdditional_EE", "amount": "0.00", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Federal Unemployment Tax", "codename": "FUTA", "amount": "12.00", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "State Unemployment Tax", "codename": "SUTA_NY", "amount": "196.51", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "State Income Tax", "codename": "SIT_NY", "amount": "80.69", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "New York - New York City Income Tax", "codename": "LIT_NY_NYC", "amount": "63.75", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "New York - Metropolitan Commuter Transportation Mobility Tax", "codename": "FEE_NY_MCTMT", "amount": "6.80", "paidBy": "EMPLOYER_LIABILITY" } ], "deductions": [ { "deduction_type": "401k", "employee_calculated_contribution": "100.00", "employer_calculated_contribution": "8.00" } ], "accruals": [ { "policyID": "35b143b7c5b53634aa29655", "policyType": "sick_leave", "policyCode": "test-sick-leave-policy", "policyName": "Test Sick Leave Policy", "accrued": 1.33, "usage": 3, "balance": 49.11 } ] } ], "total_employer_taxes": "368.31", "total_employee_taxes": "447.02", "total_employee_deductions": "100.00", "total_employer_deductions": "8.00" } } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "result": { "type": "object", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "gross_pay": { "type": "string", "example": "2000.00" }, "net_pay": { "type": "string", "example": "1452.98" }, "employer_taxes": { "type": "string", "example": "368.31" }, "employee_taxes": { "type": "string", "example": "447.02" }, "employee_deductions": { "type": "string", "example": "100.00" }, "employer_deductions": { "type": "string", "example": "8.00" }, "taxes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Federal Income Tax" }, "codename": { "type": "string", "example": "FIT" }, "amount": { "type": "string", "example": "149.58" }, "paidBy": { "type": "string", "example": "EMPLOYEE_WITHHOLDING" } } } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "deduction_type": { "type": "string", "example": "401k" }, "employee_calculated_contribution": { "type": "string", "example": "100.00" }, "employer_calculated_contribution": { "type": "string", "example": "8.00" } } } } } } }, "total_employer_taxes": { "type": "string", "example": "368.31" }, "total_employee_taxes": { "type": "string", "example": "447.02" }, "total_employee_deductions": { "type": "string", "example": "100.00" }, "total_employer_deductions": { "type": "string", "example": "8.00" } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Reporting Period with this ID does not exist", "status": 400, "code": 10 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Reporting Period with this ID does not exist" }, "status": { "type": "integer", "example": 400, "default": 0 }, "code": { "type": "integer", "example": 10, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/preview": { "get": { "summary": "Get Preview", "description": "", "operationId": "get-preview", "x-fern-sdk-group-name": "preview", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "job_id", "in": "query", "description": "The job_id of the Payroll Preview generated by the [Preview Payroll by CheckID](ref:preview-payroll-by-checkid) or [Preview Payroll by Check Date](ref:preview-payroll-by-check-date) endpoints", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "status": 200, "success": true, "data": { "job_id": "8a60333360ff-36ef-47a8-a6e4-f4d7351da9ee", "status": "complete", "code": 200, "created_at": "2023-04-12T14:56:23.366Z", "request_body": { "checks": [ "b97eecccece0f22a0a9423d9a47543b8fa8b680", "a6212a51d83442eee244df8bf9852b289c8d818", "8c8vereww22er22e340a72144152aaa8e894782d2292", "629c59c913zzezz7941ecbbcc55vvc1afd1912c" ], "companyID": "eee343432243434c59c913c59c913", "test_mode": true, "job_type": "preview-checks", "has_live_key": null }, "payload": { "success": true, "result": { "checks": [ { "employeeCheckID": "b97eecccece0f22a0a9423d9a47543b8fa8b680", "gross_pay": "1360.00", "net_pay": "1097.94", "employer_taxes": "198.81", "employee_taxes": "162.06", "employee_deductions": "100.00", "employer_deductions": "0.00", "taxes": [ { "name": "Federal Income Tax", "codename": "FIT", "amount": "20.58", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Social Security", "codename": "FICA_SocialSecurity_EE", "amount": "84.32", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Social Security", "codename": "FICA_SocialSecurity_ER", "amount": "84.32", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "Medicare", "codename": "FICA_Medicare_EE", "amount": "19.72", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Medicare", "codename": "FICA_Medicare_ER", "amount": "19.72", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "Medicare Additional", "codename": "FICA_MedicareAdditional_EE", "amount": "0.00", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Federal Unemployment Tax", "codename": "FUTA", "amount": "8.16", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "State Unemployment Tax", "codename": "SUTA_CA", "amount": "84.32", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "State Income Tax", "codename": "SIT_AZ", "amount": "25.20", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "California Temporary Disability Voluntary Plan Assesesement", "codename": "SDI_CA_ER_VP", "amount": "2.29", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "California Temporary Disability Insurance Tax", "codename": "SDI_CA_EE", "amount": "12.24", "paidBy": "EMPLOYEE_WITHHOLDING" } ], "deductions": [ { "deduction_type": "401k", "employee_calculated_contribution": "100.00", "employer_calculated_contribution": "0.00" } ], "accruals": [ { "policyID": "35b143b7c5b53634aa29655", "policyType": "sick_leave", "policyCode": "test-sick-leave-policy", "policyName": "Test Sick Leave Policy", "accrued": 1.33, "usage": 3, "balance": 49.11 } ], "flsa_ot_transformed": false }, { "employeeCheckID": "a6212a51d83442eee242224df8bf9852b289c8d818", "gross_pay": "1500.00", "net_pay": "1121.15", "employer_taxes": "148.35", "employee_taxes": "378.85", "employee_deductions": "0.00", "employer_deductions": "0.00", "taxes": [ { "name": "Federal Income Tax", "codename": "FIT", "amount": "181.16", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Social Security", "codename": "FICA_SocialSecurity_EE", "amount": "93.00", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Social Security", "codename": "FICA_SocialSecurity_ER", "amount": "93.00", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "Medicare", "codename": "FICA_Medicare_EE", "amount": "21.75", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Medicare", "codename": "FICA_Medicare_ER", "amount": "21.75", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "Medicare Additional", "codename": "FICA_MedicareAdditional_EE", "amount": "0.00", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Federal Unemployment Tax", "codename": "FUTA", "amount": "3.60", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "State Unemployment Tax", "codename": "SUTA_AK", "amount": "30.00", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "State Unemployment Tax", "codename": "SUI_AK", "amount": "8.40", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "State Income Tax", "codename": "SIT_CA", "amount": "74.54", "paidBy": "EMPLOYEE_WITHHOLDING" } ], "deductions": [], "accruals": [], "flsa_ot_transformed": true }, { "employeeCheckID": "8c8ver22ewwere340a72144152aaa8e894782d2292", "gross_pay": "301.00", "net_pay": "248.13", "employer_taxes": "41.66", "employee_taxes": "24.37", "employee_deductions": "28.50", "employer_deductions": "0.00", "taxes": [ { "name": "Federal Income Tax", "codename": "FIT", "amount": "0.00", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Social Security", "codename": "FICA_SocialSecurity_EE", "amount": "17.67", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Social Security", "codename": "FICA_SocialSecurity_ER", "amount": "17.67", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "Medicare", "codename": "FICA_Medicare_EE", "amount": "4.13", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Medicare", "codename": "FICA_Medicare_ER", "amount": "4.13", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "Medicare Additional", "codename": "FICA_MedicareAdditional_EE", "amount": "0.00", "paidBy": "EMPLOYEE_WITHHOLDING" }, { "name": "Federal Unemployment Tax", "codename": "FUTA", "amount": "1.71", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "State Unemployment Tax", "codename": "SUTA_CA", "amount": "17.67", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "California Temporary Disability Voluntary Plan Assesesement", "codename": "SDI_CA_ER_VP", "amount": "0.48", "paidBy": "EMPLOYER_LIABILITY" }, { "name": "California Temporary Disability Insurance Tax", "codename": "SDI_CA_EE", "amount": "2.57", "paidBy": "EMPLOYEE_WITHHOLDING" } ], "deductions": [ { "deduction_type": "401k", "employee_calculated_contribution": "28.50", "employer_calculated_contribution": "0.00" } ], "accruals": [ { "policyID": "35b143b7c5b53634aa29655", "policyType": "sick_leave", "policyCode": "test-sick-leave-policy", "policyName": "Test Sick Leave Policy", "accrued": 3.33, "usage": 6, "balance": 51.11 } ], "flsa_ot_transformed": false }, { "employeeCheckID": "629c59c91223zzezz7941ecbbcc55vvc1afd1912c", "gross_pay": "0.00", "net_pay": "0.00", "employer_taxes": "0.00", "employee_taxes": "0.00", "employee_deductions": "0.00", "employer_deductions": "0.00", "taxes": [], "deductions": [ { "deduction_type": "401k", "employee_calculated_contribution": "28.50", "employer_calculated_contribution": "0.00" } ], "accruals": [ { "policyID": "35b143b7c5b53634aa29655", "policyType": "sick_leave", "policyCode": "test-sick-leave-policy", "policyName": "Test Sick Leave Policy", "accrued": 2, "usage": 7, "balance": 60.9 } ], "flsa_ot_transformed": false } ], "total_flsa_transformed": 1, "total_employer_taxes": "388.82", "total_employee_taxes": "565.28", "total_employee_deductions": "128.50", "total_employer_deductions": "0.00" } } } } } }, "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 200, "default": 0 }, "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "8a60333360ff-36ef-47a8-a6e4-f4d7351da9ee" }, "status": { "type": "string", "example": "complete" }, "code": { "type": "integer", "example": 200, "default": 0 }, "created_at": { "type": "string", "example": "2023-04-12T14:56:23.366Z" }, "request_body": { "type": "object", "properties": { "checks": { "type": "array", "items": { "type": "string", "example": "b97eecccece0f22a0a9423d9a47543b8fa8b680" } }, "companyID": { "type": "string", "example": "eee343432243434c59c913c59c913" }, "test_mode": { "type": "boolean", "example": true, "default": true }, "job_type": { "type": "string", "example": "preview-checks" }, "has_live_key": {} } }, "payload": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "result": { "type": "object", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "employeeCheckID": { "type": "string", "example": "b97eecccece0f22a0a9423d9a47543b8fa8b680" }, "gross_pay": { "type": "string", "example": "1360.00" }, "net_pay": { "type": "string", "example": "1097.94" }, "employer_taxes": { "type": "string", "example": "198.81" }, "employee_taxes": { "type": "string", "example": "162.06" }, "employee_deductions": { "type": "string", "example": "100.00" }, "employer_deductions": { "type": "string", "example": "0.00" }, "taxes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Federal Income Tax" }, "codename": { "type": "string", "example": "FIT" }, "amount": { "type": "string", "example": "20.58" }, "paidBy": { "type": "string", "example": "EMPLOYEE_WITHHOLDING" } } } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "deduction_type": { "type": "string", "example": "401k" }, "employee_calculated_contribution": { "type": "string", "example": "100.00" }, "employer_calculated_contribution": { "type": "string", "example": "0.00" } } } }, "flsa_ot_transformed": { "type": "boolean", "example": false, "default": true } } } }, "total_flsa_transformed": { "type": "integer", "example": 1, "default": 0 }, "total_employer_taxes": { "type": "string", "example": "388.82" }, "total_employee_taxes": { "type": "string", "example": "565.28" }, "total_employee_deductions": { "type": "string", "example": "128.50" }, "total_employer_deductions": { "type": "string", "example": "0.00" } } } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee Check for this employee and check date already exists", "code": 32 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee Check for this employee and check date already exists" }, "code": { "type": "integer", "example": 32, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/preview/availableDate": { "get": { "summary": "Get Next Available Check/Pay Date", "description": "", "operationId": "get-preview-available-date", "x-fern-sdk-group-name": "preview", "x-fern-sdk-method-name": "getAvailableDate", "parameters": [ { "name": "companyID", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "speed", "in": "query", "description": "The Zeal speed parameter", "required": true, "schema": { "type": "string" } }, { "name": "disbursement_method", "in": "query", "description": "The Zeal disbursement method parameter", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": { "date": "2024-08-13" }, "success": true, "testMode": true } } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "date": { "type": "string", "example": "2024-08-13" } } }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/minimumWageRules": { "get": { "summary": "Get Minimum Wage Rules", "description": "Fetches Minimum Wage Rules for a specified Work Location.", "operationId": "get-minimum-wage-rules", "x-fern-sdk-group-name": "minimumWageRules", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "workLocationID", "in": "query", "description": "ID of the Work Location.", "required": true, "schema": { "type": "string" } }, { "name": "companyID", "in": "query", "description": "ID of the Company.", "required": true, "schema": { "type": "string" } }, { "name": "effectiveDate", "in": "query", "description": "Effective date of the minimum wage rules, defaults to today's date if empty.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": [ { "jurisdiction": "California", "effectiveDate": "2024-01-01", "rate": "$16.00" }, { "jurisdiction": "Los Angeles, CA", "effectiveDate": "2024-07-01", "rate": "$17.28" } ], "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "jurisdiction": { "type": "string", "example": "California" }, "effectiveDate": { "type": "string", "example": "2024-01-01" }, "rate": { "type": "string", "example": "$16.00" } } } }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } }, "/accrualPolicy": { "post": { "summary": "Create Accrual Policy", "description": "", "operationId": "create-accrual-policy", "x-fern-sdk-group-name": "accrualPolicy", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "policy_code", "policy_type", "accrual_rate_hours", "accrual_period_hours", "include_doubletime", "include_overtime" ], "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "policy_code": { "type": "string", "description": "Unique code to assign to this policy" }, "policy_type": { "type": "string", "description": "Type of the accrual policy (accepts: pto, sick_leave, or custom)" }, "policy_name": { "type": "string", "description": "Custom name that can be assigned for the policy" }, "policy_effective_date": { "type": "string", "description": "The effective start date of the policy", "format": "date" }, "accrual_rate_hours": { "type": "number", "description": "The rate at which employees will accrue hours", "format": "float" }, "accrual_period_hours": { "type": "number", "description": "The number of hours employees need to work to accrue accrual_rate_hours", "format": "float" }, "immediate_balance": { "type": "number", "description": "The initial or immediate hour balance of policy", "format": "float" }, "include_doubletime": { "type": "boolean", "description": "Include if doubletime work is eligible for hour accrual" }, "include_overtime": { "type": "boolean", "description": "Include if overtime work is eligible for hour accrual" }, "accrual_waiting_period": { "type": "number", "description": "The number of hours the employees need to work before they are eligible to begin accruing time for policy", "format": "float" }, "accrual_cap": { "type": "number", "description": "The maximum number of hours an employee can accrue within a policy year. Once this limit is reached, no additional hours will accrue until the next accrual period or `rollover_date`.", "format": "float" }, "rollover_cap": { "type": "number", "description": "The maximum number of unused hours an employee is allowed to carry over from one policy year to the next on the specified rollover date.", "format": "float" }, "rollover_date": { "type": "string", "description": "Required if user passes a value for `rollover_cap` or `accrual_cap`. Month-day in MM-DD format (e.g. 01-01)." }, "balance_cap": { "type": "number", "description": "The maximum balance an employee is allowed to hold under this policy", "format": "float" } } }, "examples": { "Request Example": { "value": { "companyID": "123er534efrerwwe3444e", "policy_code": "001", "policy_type": "pto", "policy_name": "test name", "policy_effective_date": "2023-03-01", "accrual_rate_hours": 10, "accrual_period_hours": 40, "immediate_balance": 0, "include_doubletime": true, "include_overtime": true, "accrual_waiting_period": 0, "accrual_cap": 40, "rollover_cap": 40, "rollover_date": "01-01" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "123er534efrerwwe3444e", "policy_type": "pto", "policy_name": "test name", "policy_code": "001", "policy_effective_date": "2023-03-20", "accrual_rate_hours": 0.5, "accrual_period_hours": 10, "immediate_balance": 10, "include_doubletime": false, "include_overtime": false, "accrual_waiting_period": 28, "accrual_cap": 50, "rollover_cap": 20, "rollover_date": "05-01", "policy_status": "live", "balance_cap": 50 } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "123er534efrerwwe3444e" }, "policy_type": { "type": "string", "example": "pto" }, "policy_name": { "type": "string", "example": "test name" }, "policy_code": { "type": "string", "example": "001" }, "policy_effective_date": { "type": "string", "example": "2023-03-20" }, "accrual_rate_hours": { "type": "number", "example": 0.5, "default": 0 }, "accrual_period_hours": { "type": "integer", "example": 10, "default": 0 }, "immediate_balance": { "type": "integer", "example": 10, "default": 0 }, "include_doubletime": { "type": "boolean", "example": false, "default": true }, "include_overtime": { "type": "boolean", "example": false, "default": true }, "accrual_waiting_period": { "type": "integer", "example": 28, "default": 0 }, "accrual_cap": { "type": "integer", "example": 50, "default": 0 }, "rollover_cap": { "type": "integer", "example": 20, "default": 0 }, "rollover_date": { "type": "string", "example": "05-01" }, "policy_status": { "type": "string", "example": "live" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "error": true, "message": "No company with this companyID exists.", "timestamp": "2023-03-21T19:13:18Z" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "error": { "type": "boolean", "example": true, "default": true }, "message": { "type": "string", "example": "No company with this companyID exists." }, "timestamp": { "type": "string", "example": "2023-03-21T19:13:18Z" } } } } } } }, "deprecated": false }, "patch": { "summary": "Update Accrual Policy", "description": "", "operationId": "update-accrual-policy", "x-fern-sdk-group-name": "accrualPolicy", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "policy_code"], "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "policy_code": { "type": "string", "description": "Unique code assigned to the policy" }, "policy_type": { "type": "string", "description": "Type of the accrual policy (accepts: pto, sick_leave, or custom)" }, "policy_effective_date": { "type": "string", "description": "The effective start date of the policy", "format": "date" }, "accrual_rate_hours": { "type": "number", "description": "The rate at which employees will accrue hours", "format": "float" }, "accrual_period_hours": { "type": "number", "description": "The number of hours employees need to work to accrue accrual_rate_hours", "format": "float" }, "immediate_balance": { "type": "number", "description": "The initial or immediate hour balance of policy", "format": "float" }, "include_doubletime": { "type": "boolean", "description": "Include if doubletime work is eligible for hour accrual" }, "include_overtime": { "type": "boolean", "description": "Include if overtime work is eligible for hour accrual" }, "accrual_waiting_period": { "type": "number", "description": "The number of hours the employees need to work before they are eligible to begin accruing time for policy", "format": "float" }, "accrual_cap": { "type": "number", "description": "Max hours an employee can accrue in one calendar year", "format": "float" }, "rollover_cap": { "type": "number", "description": "Max hours an employee can rollover from one year to the next year, on specified rollover date", "format": "float" }, "rollover_date": { "type": "string", "description": "Required if user passes a value for rollover_cap. Month-day in MM-DD format (e.g. 01-01)." }, "policy_status": { "type": "string", "description": "The status of the policy (accepts live or terminated)" }, "include_flat": { "type": "boolean", "description": "Include if flat earning component is eligible for accrual" }, "balance_cap": { "type": "number", "format": "float", "description": "The maximum balance an employee is allowed to hold under this policy" } } }, "examples": { "Request Example": { "value": { "companyID": "123er534efrerwwe3444e", "policy_code": "001", "policy_type": "pto", "policy_name": "Updated name", "policy_effective_date": "2023-03-01", "accrual_rate_hours": 10, "accrual_period_hours": 40, "immediate_balance": 50, "include_doubletime": true, "include_overtime": true, "accrual_waiting_period": 0, "accrual_cap": 50, "rollover_cap": 90, "rollover_date": "01-01", "policy_status": "live" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "123er534efrerwwe3444e", "policy_code": "001", "policy_type": "pto", "policy_name": "Updated name", "policy_effective_date": "2023-03-01", "accrual_rate_hours": 10, "accrual_period_hours": 40, "immediate_balance": 50, "include_doubletime": true, "include_overtime": true, "accrual_waiting_period": 0, "accrual_cap": 100, "rollover_cap": 90, "rollover_date": "01-01", "policy_status": "live", "balance_cap": 100 } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "123er534efrerwwe3444e" }, "policy_code": { "type": "string", "example": "001" }, "policy_type": { "type": "string", "example": "pto" }, "policy_name": { "type": "string", "example": "Updated name" }, "policy_effective_date": { "type": "string", "example": "2023-03-01" }, "accrual_rate_hours": { "type": "integer", "example": 10, "default": 0 }, "accrual_period_hours": { "type": "integer", "example": 40, "default": 0 }, "immediate_balance": { "type": "integer", "example": 50, "default": 0 }, "include_doubletime": { "type": "boolean", "example": true, "default": true }, "include_overtime": { "type": "boolean", "example": true, "default": true }, "accrual_waiting_period": { "type": "integer", "example": 0, "default": 0 }, "accrual_cap": { "type": "integer", "example": 50, "default": 0 }, "rollover_cap": { "type": "integer", "example": 90, "default": 0 }, "rollover_date": { "type": "string", "example": "01-01" }, "policy_status": { "type": "string", "example": "live" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "error": true, "message": "Accrual policy with this policy code not found", "timestamp": "2023-03-21T19:13:18Z" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "error": { "type": "boolean", "example": true, "default": true }, "message": { "type": "string", "example": "Accrual policy with this policy code not found" }, "timestamp": { "type": "string", "example": "2023-03-21T19:13:18Z" } } } } } } }, "deprecated": false }, "get": { "summary": "Get Accrual Policy", "description": "", "operationId": "get-accrual-policy", "x-fern-sdk-group-name": "accrualPolicy", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "ID of the company, will return all company's accrual policies if solely passed", "required": true, "schema": { "type": "string" } }, { "name": "policy_code", "in": "query", "description": "Unique code assigned to a policy", "schema": { "type": "string" } }, { "name": "policy_status", "in": "query", "description": "Status of the policy (accepts live or terminated)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "234eeeee53534tererec", "policy_type": "pto", "policy_name": "test name", "policy_code": "001", "policy_effective_date": "2023-03-01", "accrual_rate_hours": 10, "accrual_period_hours": 40, "immediate_balance": 0, "include_doubletime": true, "include_overtime": true, "accrual_waiting_period": 0, "accrual_cap": 60, "rollover_cap": 40, "rollover_date": "01-01", "policy_status": "live", "balance_cap": 60 } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "234eeeee53534tererec" }, "policy_type": { "type": "string", "example": "pto" }, "policy_name": { "type": "string", "example": "test name" }, "policy_code": { "type": "string", "example": "001" }, "policy_effective_date": { "type": "string", "example": "2023-03-01" }, "accrual_rate_hours": { "type": "integer", "example": 10, "default": 0 }, "accrual_period_hours": { "type": "integer", "example": 40, "default": 0 }, "immediate_balance": { "type": "integer", "example": 0, "default": 0 }, "include_doubletime": { "type": "boolean", "example": true, "default": true }, "include_overtime": { "type": "boolean", "example": true, "default": true }, "accrual_waiting_period": { "type": "integer", "example": 0, "default": 0 }, "accrual_cap": { "type": "integer", "example": 40, "default": 0 }, "rollover_cap": { "type": "integer", "example": 40, "default": 0 }, "rollover_date": { "type": "string", "example": "01-01" }, "policy_status": { "type": "string", "example": "live" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "error": true, "message": "Accrual policy with this policy code not found", "timestamp": "2023-03-27T17:24:35Z" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "error": { "type": "boolean", "example": true, "default": true }, "message": { "type": "string", "example": "Accrual policy with this policy code not found" }, "timestamp": { "type": "string", "example": "2023-03-27T17:24:35Z" } } } } } } }, "deprecated": false } }, "/sickTimeCompliance": { "get": { "summary": "Get Sick Time Compliance Rules", "description": "", "operationId": "get-sick-time-compliance", "x-fern-sdk-group-name": "sickTimeCompliance", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "state", "in": "query", "description": "State jurisdiction acronym", "required": true, "schema": { "type": "string" } }, { "name": "city", "in": "query", "description": "Name of city", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "state": "CA", "isSickLeaveMandatory": true, "accrualRateHours": [ { "employerSize": "All", "rule": 0.0333 } ], "maxAccrualHours": [ { "employerSize": "All", "rule": 80 } ], "rolloverCap": [ { "employerSize": "All", "rule": 80 } ], "payStatementRequired": true, "notes": "Must have at least 24 hours by 120th calendar day of employment" }, { "state": "CA", "city": "Oakland", "isSickLeaveMandatory": true, "accrualRateHours": [ { "employerSize": "1-9 Employees", "rule": 0.0333 }, { "employerSize": "10+ Employees", "rule": 0.0333 } ], "maxAccrualHours": [ { "employerSize": "1-9 Employees", "rule": 40 }, { "employerSize": "10+ Employees", "rule": 72 } ], "rolloverCap": [ { "employerSize": "1-9 Employees", "rule": 40 }, { "employerSize": "10+ Employees", "rule": 72 } ], "payStatementRequired": true } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string", "example": "CA" }, "isSickLeaveMandatory": { "type": "boolean", "example": true, "default": true }, "accrualRateHours": { "type": "array", "items": { "type": "object", "properties": { "employerSize": { "type": "string", "example": "All" }, "rule": { "type": "number", "example": 0.0333, "default": 0 } } } }, "maxAccrualHours": { "type": "array", "items": { "type": "object", "properties": { "employerSize": { "type": "string", "example": "All" }, "rule": { "type": "integer", "example": 80, "default": 0 } } } }, "rolloverCap": { "type": "array", "items": { "type": "object", "properties": { "employerSize": { "type": "string", "example": "All" }, "rule": { "type": "integer", "example": 80, "default": 0 } } } }, "payStatementRequired": { "type": "boolean", "example": true, "default": true }, "notes": { "type": "string", "example": "Must have at least 24 hours by 120th calendar day of employment" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "error": true, "message": "Accrual policy with this policy code not found", "timestamp": "2023-03-27T17:24:35Z" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "error": { "type": "boolean", "example": true, "default": true }, "message": { "type": "string", "example": "Accrual policy with this policy code not found" }, "timestamp": { "type": "string", "example": "2023-03-27T17:24:35Z" } } } } } } }, "deprecated": false } }, "/accrualPolicyEmployees": { "post": { "summary": "Add/Remove Employees to Accrual Policy", "description": "", "operationId": "add-employees-to-accrual-policy", "x-fern-sdk-group-name": "accrualPolicy", "x-fern-sdk-method-name": "addOrRemoveEmployees", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "policy_code"], "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "policy_code": { "type": "string", "description": "Unique code assigned to a policy" }, "add_employees": { "type": "array", "description": "Adds an array of employeeIDs to be assigned to the respective policy", "items": { "type": "string" } }, "remove_employees": { "type": "array", "description": "Removes employees from accrual policy (accepts array of employeeIDs)", "items": { "type": "string" } } } }, "examples": { "Request Example": { "value": { "companyID": "cc3344747eee494857rrc9458nb3948", "policy_code": "001", "add_employees": ["3343eree4394785ec3334cc"], "remove_employees": [] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "companyID": "cc3344747eee494857rrc9458nb3948", "policy_code": "001", "add_employees": ["3343eree4394785ec3334cc"], "remove_employees": [] } } }, "schema": { "type": "object", "properties": { "companyID": { "type": "string", "example": "cc3344747eee494857rrc9458nb3948" }, "policy_code": { "type": "string", "example": "001" }, "add_employees": { "type": "array", "items": { "type": "string", "example": "3343eree4394785ec3334cc" } }, "remove_employees": { "type": "array" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "error": true, "message": "This employee is not onboarded.", "timestamp": "2023-03-27T17:24:35Z" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "error": { "type": "boolean", "example": true, "default": true }, "message": { "type": "string", "example": "This employee is not onboarded." }, "timestamp": { "type": "string", "example": "2023-03-27T17:24:35Z" } } } } } } }, "deprecated": false } }, "/accrualBalance": { "patch": { "summary": "Update Accrual Balance", "description": "", "operationId": "update-accrual-balance", "x-fern-sdk-group-name": "accrualBalance", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "policy_code"], "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "policy_code": { "type": "string", "description": "Unique code assigned to a policy" }, "employees": { "type": "array", "description": "Array of objects of employees and corresponding accrual balances to be updated", "items": { "properties": { "employeeID": { "type": "string", "description": "ID of the employee" }, "accrual_balance": { "type": "number", "description": "Accrual balance to be updated", "format": "float" } }, "required": ["employeeID", "accrual_balance"], "type": "object" } } } }, "examples": { "Request Example": { "value": { "companyID": "cc3344747eee494857rrc9458nb3948", "policy_code": "001", "employees": [ { "employeeID": "3578439f85h4", "accrual_balance": 40 }, { "employeeID": "y54vy54y5b4y", "accrual_balance": 35 } ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "2hw67sd8900fd7hw78fdfhaej", "accrualPolicies": [ { "policy_code": "001", "employeeID": "ccee4542323errr34345223", "policy_type": "pto", "policy_name": "executive_pto", "accrual_balance": "20.00", "accrual_rate_unit": "hours", "policy_status": "live" } ] } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "2hw67sd8900fd7hw78fdfhaej" }, "accrualPolicies": { "type": "array", "items": { "type": "object", "properties": { "policy_code": { "type": "string", "example": "001" }, "employeeID": { "type": "string", "example": "ccee4542323errr34345223" }, "policy_type": { "type": "string", "example": "pto" }, "policy_name": { "type": "string", "example": "executive_pto" }, "accrual_balance": { "type": "string", "example": "20.00" }, "accrual_rate_unit": { "type": "string", "example": "hours" }, "policy_status": { "type": "string", "example": "live" } } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "error": true, "message": "Accrual policy with this policy code not found", "timestamp": "2023-03-27T17:24:35Z" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "error": { "type": "boolean", "example": true, "default": true }, "message": { "type": "string", "example": "Accrual policy with this policy code not found" }, "timestamp": { "type": "string", "example": "2023-03-27T17:24:35Z" } } } } } } }, "deprecated": false }, "get": { "summary": "Get Accrual Balance", "description": "", "operationId": "get-accrual-balance", "x-fern-sdk-group-name": "accrualBalance", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "ID of the company", "required": true, "schema": { "type": "string" } }, { "name": "policy_code", "in": "query", "description": "Filter by the unique code assigned to a policy", "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "description": "Filter by the employee assigned to a policy", "schema": { "type": "string" } }, { "name": "policy_status", "in": "query", "description": "Filter by status of the policy (accepts live or terminated)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "companyID": "2hw67sd8900fd7hw78fdfhaej", "accrualPolicies": [ { "policy_code": "001", "employeeID": "ccee4542323errr34345223", "policy_type": "pto", "policy_name": "executive_pto", "accrual_balance": 20, "accrual_rate_unit": "hours", "policy_status": "live" } ] } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "companyID": { "type": "string", "example": "2hw67sd8900fd7hw78fdfhaej" }, "accrualPolicies": { "type": "array", "items": { "type": "object", "properties": { "policy_code": { "type": "string", "example": "001" }, "employeeID": { "type": "string", "example": "ccee4542323errr34345223" }, "policy_type": { "type": "string", "example": "pto" }, "policy_name": { "type": "string", "example": "executive_pto" }, "accrual_balance": { "type": "integer", "example": 20, "default": 0 }, "accrual_rate_unit": { "type": "string", "example": "hours" }, "policy_status": { "type": "string", "example": "live" } } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "error": true, "message": "Accrual policy with this policy code not found", "timestamp": "2023-03-27T17:24:35Z" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "error": { "type": "boolean", "example": true, "default": true }, "message": { "type": "string", "example": "Accrual policy with this policy code not found" }, "timestamp": { "type": "string", "example": "2023-03-27T17:24:35Z" } } } } } } }, "deprecated": false } }, "/accrualPolicy/{policyCode}/usage": { "post": { "summary": "Create Accrual Policy Usage", "description": "Manage usage amounts for employees based on specific accrual policies within a company", "operationId": "post-accrual-policy-usage", "x-fern-sdk-group-name": "accrualPolicy", "x-fern-sdk-method-name": "addUsage", "parameters": [ { "name": "policyCode", "in": "path", "description": "The unique identifier for the accrual policy under which the usage is being applied", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employees"], "properties": { "companyID": { "type": "string", "description": "The unique identifier for the company." }, "employees": { "type": "array", "description": "A list of employees for whom usage is being applied. Each object in the array should have the following properties.", "items": { "properties": { "employeeID": { "type": "string", "description": "The unique identifier for the employee" }, "start_date": { "type": "string", "description": "The start date of the usage period in YYYY-MM-DD format" }, "end_date": { "type": "string", "description": "The end date of the usage period in YYYY-MM-DD format" }, "amount": { "type": "integer", "description": "The amount of usage being applied. A positive number adds to the employee's usage", "format": "int32" }, "correction": { "type": "boolean", "description": "When set to true, this field indicates that the usage is a correction. Corrections adjust the employee's balance by storing the amount as a negative usage" } }, "required": ["employeeID", "start_date", "end_date"], "type": "object" } } } }, "examples": { "Request Example": { "value": { "companyID": "6181b78dba43479c8dc23f046b32bc28", "employees": [ { "employeeID": "66c7738bbabb2213d7628c02", "start_date": "2024-12-10", "end_date": "2024-12-11", "amount": 4 } ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": [ { "companyID": "6181b78dba43479c8dc23f046b32bc28", "policyID": "66c8cb269d0072479db7c7e", "employeeID": "66c7738bbabb2213d7628c02", "correction": false, "amount": 4, "start_date": "2024-12-10", "end_date": "2024-12-11" } ], "success": true, "testMode": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Accrual policy with this policy code not found", "code": 109, "status": 404, "correlationId": "fedfd6fd-c689-40d1-8d80-f9e3c4efceba" } ], "testMode": true } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Accrual policy with this policy code not found" }, "code": { "type": "integer", "example": 109, "default": 0 }, "status": { "type": "integer", "example": 404, "default": 0 }, "correlationId": { "type": "string", "example": "fedfd6fd-c689-40d1-8d80-f9e3c4efceba" } } } }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/accrualBalance/history": { "post": { "summary": "Accrual Balance History", "description": "View accrual balance history specific filters within a company", "operationId": "accrual-balance-history", "x-fern-sdk-group-name": "accrualBalance", "x-fern-sdk-method-name": "getHistory", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "policyCode", "employeeIDs", "endDate" ], "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "policyCode": { "type": "string", "description": "The unique identifier for the accrual policy under which the usage is being applied" }, "employeeIDs": { "type": "array", "description": "IDs of any employees you would like to see accrual balance history for", "items": { "type": "string" } }, "endDate": { "type": "string", "format": "date" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": [ { "employeeID": "66722ff005a48848507d75d9", "policyName": "sick_leave", "totalAccrued": "7.45", "totalBalance": "21.64", "totalUsage": "17.00", "history": [ { "reportingPeriodID": "6580ce4a3808d60023b4e17d", "checks": ["36cd1ff3857d4e9585aa18e93c6e62e2"], "balance": "26.29", "accrued": "2.61", "usage": "0.00" }, { "reportingPeriodID": "67080ab04a7fcc706be57598", "checks": ["24006fc9fb0f405f96304964f3a5e9f3"], "balance": "11.59", "accrued": "2.29", "usage": "17.00" }, { "reportingPeriodID": "67080ab04a7fcc706be575a6", "checks": ["8edb64ca204a4ad5b33a83acf9e248c5"], "balance": "21.64", "accrued": "2.55", "usage": "0.00" } ] } ], "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "employeeID": { "type": "string", "example": "66722ff005a48848507d75d9" }, "policyName": { "type": "string", "example": "sick_leave" }, "totalAccrued": { "type": "string", "example": "7.45" }, "totalBalance": { "type": "string", "example": "21.64" }, "totalUsage": { "type": "string", "example": "17.00" }, "history": { "type": "array", "items": { "type": "object", "properties": { "reportingPeriodID": { "type": "string", "example": "6580ce4a3808d60023b4e17d" }, "checks": { "type": "array", "items": { "type": "string", "example": "36cd1ff3857d4e9585aa18e93c6e62e2" } }, "balance": { "type": "string", "example": "26.29" }, "accrued": { "type": "string", "example": "2.61" }, "usage": { "type": "string", "example": "0.00" } } } } } } }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Invalid", "code": 13, "status": 400, "correlationId": "3b3f6226-db6a-4de1-889c-e3f3b00ceb09", "params": { "fields": ["employeeIDs[0]"] } } ], "testMode": true } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid" }, "code": { "type": "integer", "example": 13, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "3b3f6226-db6a-4de1-889c-e3f3b00ceb09" }, "params": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string", "example": "employeeIDs[0]" } } } } } } }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/preview/checks/ot": { "post": { "summary": "Preview Overtime Checks", "description": "", "operationId": "preview-overtime-checks", "x-fern-sdk-group-name": "preview", "x-fern-sdk-method-name": "createOvertimeChecks", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "checks"], "properties": { "companyID": { "type": "string", "description": "The ID of the Company" }, "checks": { "type": "array", "description": "Array of employeeCheckIDs", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "status": 200, "success": true, "data": { "job_id": "232c21f1-cc24-4664-8420-393d0acd21351", "status": "pending", "request_body": { "companyID": "h0c56cc41q1040ac8a3322342a3bbb462", "checks": [ "c614c5ff59d7cc22eae4c9442f315", "22cdbd897e3345a55c3fa22b1712be52", "3942348bd453410485cd783ef1ce8391" ], "test_mode": false, "job_type": "preview-checks-flsa" }, "created_at": "2022-05-04T19:29:39.134Z" } } } }, "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 200, "default": 0 }, "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "232c21f1-cc24-4664-8420-393d0acd21351" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "companyID": { "type": "string", "example": "h0c56cc41q1040ac8a3322342a3bbb462" }, "checks": { "type": "array", "items": { "type": "string", "example": "c614c5ff59d7cc22eae4c9442f315" } }, "test_mode": { "type": "boolean", "example": false, "default": true }, "job_type": { "type": "string", "example": "preview-checks-flsa" } } }, "created_at": { "type": "string", "example": "2022-05-04T19:29:39.134Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "curl", "code": { "companyID": "h0c56cc41q1040ac8a3322342a3bbb462", "checks": [ "c614c5ff59d7cc22eae4c9442f315", "22cdbd897e3345a55c3fa22b1712be52", "3942348bd453410485cd783ef1ce8391" ] } } ], "samples-languages": ["curl"] } } }, "/contractors": { "post": { "summary": "Create Contractor", "description": "", "operationId": "create-contractor", "x-fern-sdk-group-name": "contractors", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "new_contractors"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "new_contractors": { "type": "array", "description": "Array of [Contractor Objects](ref:contractor-object)", "items": { "properties": { "email": { "type": "string", "description": "Email of Contractor" }, "working_state": { "type": "string", "description": "State that the Contractor is working in" }, "first_name": { "type": "string", "description": "First Name of Contractor" }, "middle_name": { "type": "string", "description": "Middle Name of Contractor" }, "last_name": { "type": "string", "description": "Last Name of Contractor" }, "ssn": { "type": "string", "description": "The contractor's social security number" }, "dob": { "type": "string", "description": "Date of birth of the contractor" }, "phone_number": { "type": "string", "description": "" }, "type": { "type": "string", "description": "Holds one of the following values: `individual_sole_proprietor`, `c_corporation`, `s_corporation`, `partnership`, `trust_estate`, `llc`, `other`. If not provided, Zeal will ask for this information during onboarding", "enum": [ "individual_sole_proprietor", "c_corporation", "s_corporation", "partnership", "trust_estate", "llc", "other" ] }, "llc_tax_classification": { "type": "string", "description": "The tax classification of the LLC. Holds one of the following values: `c_corporation`, `s_corporation`, `partnership`. Only applicable if `type` is `llc`.", "enum": [ "c_corporation", "s_corporation", "partnership" ] }, "tin_type": { "type": "string", "description": "The TIN type of the contractor. Holds one of the following values: `ssn`, `ein`. Only applicable if `type` is `individual_sole_proprietor`. If `ein` is passed, then the `ein` parameter will be required.", "enum": ["ssn", "ein"] }, "ein": { "type": "string", "description": "EIN of the contractor. **(Not applicable if `type` is `individual_sole_proprietor` , unless the `tin_type` is `ein`)**" }, "business_name": { "type": "string", "description": "Business Name of the contractor. **(Not applicable if `type` is `individual_sole_proprietor` )**" }, "address": { "type": "string" }, "address_line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "onboarded": { "type": "string", "description": "Set to true to onboard contractor. Error will be returned if not all required fields are present to complete onboarding." } }, "required": [ "email", "working_state", "first_name", "last_name" ], "type": "object" } } } }, "examples": { "Request Example": { "value": { "companyID": "1weertirur238eec39482", "new_contractors": [ { "email": "erlich@zeal.com", "working_state": "CA", "first_name": "Erlich", "last_name": "Bachman", "type": "s_corporation", "business_name": "Aviato", "ein": "098765432", "dob": "1998-05-05" } ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "contractorID": "c9f1e2a47d3b4f8a9c2e1a6b8d4f3e21", "companyID": "a7e3c91f4b2d8f5e9c6a1d0b4e8f2c73", "onboarded": true, "type": "c_corporation", "tin_type": null, "first_name": "erlich", "middle_name": "null", "last_name": "bachman", "email": "erlich@zeal.com", "dob": "1998-05-05", "phone_number": "4154645367", "ein": "12-3456789", "business_name": "Monster Cookies", "address": "320 Pancake Hollow Road", "address_line2": "null", "city": "Highland", "state": "NY", "zip": "12528", "employment_status": "live", "external_id": "123", "paycard_requested": false, "paycard_enabled": false, "kyc_status": "approved", "ssn_verification_status": "approved", "instant_pay_enabled": true } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "contractorID": { "type": "string", "example": "1234567890" }, "companyID": { "type": "string", "example": "1b5n28nrideucd24" }, "onboarded": { "type": "boolean", "example": false, "default": true }, "email": { "type": "string", "example": "erlich@zeal.com" }, "working_state": { "type": "string", "example": "CA" }, "first_name": { "type": "string", "example": "erlich" }, "middle_name": { "type": "string", "example": "null" }, "last_name": { "type": "string", "example": "bachman" }, "type": { "type": "string", "example": "llc" }, "dob": { "type": "string", "example": "1998-05-05" }, "business_name": { "type": "string", "example": "Aviato" }, "ein": { "type": "string", "example": "098765432" }, "ssn": { "type": "string", "example": "null" }, "address": { "type": "string", "example": "null" }, "address_line2": { "type": "string", "example": "null" }, "city": { "type": "string", "example": "null" }, "state": { "type": "string", "example": "null" }, "zip": { "type": "string", "example": "null" }, "llc_tax_classification": { "type": "string", "example": "partnership" }, "employment_status": { "type": "string", "example": "live" }, "external_id": { "type": "string", "example": "245667" }, "paycard_requested": { "type": "boolean", "example": false, "default": true }, "paycard_enabled": { "type": "boolean", "example": false, "default": true }, "kyc_status": { "type": "string", "example": "approved" }, "ssn_verification_status": { "type": "string", "example": "approved" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Incorrect Type: expected one of individual_sole_proprietor, c_corporation, s_corporation, partnership, trust_estate, llc, other", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Incorrect Type: expected one of individual_sole_proprietor, c_corporation, s_corporation, partnership, trust_estate, llc, other" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false }, "patch": { "summary": "Update Contractor Information", "description": "", "operationId": "update-contractor-information", "x-fern-sdk-group-name": "contractors", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "contractor"], "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "contractor": { "type": "object", "description": "Contractor Object", "required": ["contractorID"], "properties": { "contractorID": { "type": "string", "description": "ID of the contractor" }, "first_name": { "type": "string", "description": "First name of the Contractor" }, "last_name": { "type": "string", "description": "Last name of the Contractor" }, "dob": { "type": "string", "description": "Date of birth of the Contractor", "format": "date" }, "business_name": { "type": "string", "description": "Business Name of Contractor (only accepted if type == \"business\")" }, "ssn": { "type": "string", "description": "SSN of the Contractor" }, "email": { "type": "string", "description": "Email address of the Contractor" }, "address": { "type": "string", "description": "Residential Street Address of Contractor" }, "address_line2": { "type": "string", "description": "Residential Street Address Line 2 of Contractor" }, "city": { "type": "string", "description": "Residential City of Contractor" }, "state": { "type": "string", "description": "Residential State of Contractor" }, "zip": { "type": "string", "description": "Residential Zip of Contractor" }, "start_date": { "type": "string", "description": "The starting date of the Contractor" } } } } }, "examples": { "Request Example": { "value": { "contractorID": "123456789", "companyID": "1b5n28nrideucd24", "type": "partnership", "first_name": "erlich", "middle_name": "null", "last_name": "bachman", "email": "erlichbachman2@zeal.com", "ssn": "123456789", "ein": "null", "business_name": "null", "address": "320 Pancake Hollow Road", "city": "Highland", "state": "NY", "zip": "12528", "dob": "1998-05-05" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "contractorID": "c9f1e2a47d3b4f8a9c2e1a6b8d4f3e21", "companyID": "a7e3c91f4b2d8f5e9c6a1d0b4e8f2c73", "onboarded": true, "type": "c_corporation", "tin_type": null, "first_name": "erlich", "middle_name": "null", "last_name": "bachman", "email": "erlich@zeal.com", "dob": "1998-05-05", "phone_number": "4154645367", "ein": "12-3456789", "business_name": "Monster Cookies", "address": "320 Pancake Hollow Road", "address_line2": "null", "city": "Highland", "state": "NY", "zip": "12528", "employment_status": "live", "external_id": "123", "paycard_requested": false, "paycard_enabled": false, "kyc_status": "approved", "ssn_verification_status": "approved", "instant_pay_enabled": true } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No contractorID in the body/query of the request", "code": 35 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No contractorID in the body/query of the request" }, "code": { "type": "integer", "example": 35, "default": 0 } } } } } } } } } }, "deprecated": false }, "get": { "summary": "Get Contractor Information", "description": "Request key information from The Contractor Object", "operationId": "retrieve-contractor-information", "x-fern-sdk-group-name": "contractors", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of employer", "required": true, "schema": { "type": "string" } }, { "name": "contractorID", "in": "query", "description": "ID of Contractor", "required": false, "schema": { "type": "string" } }, { "name": "onboarded", "in": "query", "description": "Filter by Contractor onboarded status", "required": false, "schema": { "type": "boolean" } }, { "name": "employment_status", "in": "query", "description": "Filter by Contractor employment status", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter by Contractor type", "required": false, "schema": { "type": "string", "enum": ["business", "individual"] } }, { "name": "email", "in": "query", "description": "Filter by Contractor email", "required": false, "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "description": "Filter by Contractor external ID", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "contractorID": "1234567890", "companyID": "1b5n28nrideucd24", "onboarded": true, "type": "partnership", "first_name": "erlich", "middle_name": "null", "last_name": "bachman", "email": "erlichbachman2@zeal.com", "working_state": "MA", "ssn": "123456789", "ein": "null", "business_name": "null", "address": "320 Pancake Hollow Road", "city": "Highland", "state": "NY", "zip": "12528", "employment_status": "live", "external_id": "1234", "paycard_requested": false, "paycard_enabled": false, "kyc_status": "approved", "ssn_verification_status": "approved" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "contractorID": { "type": "string", "example": "1234567890" }, "companyID": { "type": "string", "example": "1b5n28nrideucd24" }, "onboarded": { "type": "boolean", "example": true, "default": true }, "type": { "type": "string", "example": "partnership" }, "first_name": { "type": "string", "example": "erlich" }, "middle_name": { "type": "string", "example": "null" }, "last_name": { "type": "string", "example": "bachman" }, "email": { "type": "string", "example": "erlichbachman2@zeal.com" }, "working_state": { "type": "string", "example": "MA" }, "ssn": { "type": "string", "example": "123456789" }, "ein": { "type": "string", "example": "null" }, "business_name": { "type": "string", "example": "null" }, "address": { "type": "string", "example": "320 Pancake Hollow Road" }, "city": { "type": "string", "example": "Highland" }, "state": { "type": "string", "example": "NY" }, "zip": { "type": "string", "example": "12528" }, "employment_status": { "type": "string", "example": "live" }, "external_id": { "type": "string", "example": "1234" }, "paycard_requested": { "type": "boolean", "example": false, "default": true }, "paycard_enabled": { "type": "boolean", "example": false, "default": true }, "kyc_status": { "type": "string", "example": "approved" }, "ssn_verification_status": { "type": "string", "example": "approved" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Contractor ID is not formatted correctly", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor ID is not formatted correctly" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/contractors/id": { "post": { "summary": "Upload Contractor Government ID", "description": "", "operationId": "upload-contractor-government-id", "x-fern-sdk-group-name": "contractors", "x-fern-sdk-method-name": "uploadGovernmentId", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "contractorID", "companyID", "id_type", "id_base64" ], "properties": { "contractorID": { "type": "string", "description": "ID of the Contractor" }, "companyID": { "type": "string", "description": "ID of the Company" }, "id_type": { "type": "string", "description": "type of the ID to be uploaded, current options are drivers_license, social_security_card and passport", "enum": [ "drivers_license", "social_security_card", "passport" ] }, "id_base64": { "type": "string", "description": "base64 image of the ID to be uploaded" } } }, "examples": { "Request Example": { "value": { "contractorID": "618036cbee0d53002343911b", "companyID": "fc23jk12bae46aa8a082f3577eacfa", "id_type": "passport", "id_base64": "iVBORw23goAAAANSUhEUgAAAtsAAABdCAYAAAB0Bq" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "_id": "627d2581aa61ff002824264e" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "_id": { "type": "string", "example": "627d2581aa61ff002824264e" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "id_type 'pasport' is not valid, it must be one of: drivers_license, passport", "code": 47 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "id_type 'pasport' is not valid, it must be one of: drivers_license, passport" }, "code": { "type": "integer", "example": 47, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/contractors/paycard": { "post": { "summary": "Create Paycard Enrollment Link (Early Access)", "description": "", "operationId": "create-paycard-enrollment-link-contractor", "x-fern-sdk-group-name": "contractors", "x-fern-sdk-method-name": "createPaycardEnrollmentLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "contractorID"], "properties": { "companyID": { "type": "string", "description": "ID of the Employee being updated" }, "contractorID": { "type": "string", "description": "ID of the Contractor" }, "send_to_worker": { "type": "boolean", "description": "If true, notification email will be sent to contractor", "default": false } } }, "examples": { "Request Example": { "value": { "companyID": "3f5c2afcc5ea40c87a2c8f3f7e5a1cb1", "contractorID": "d2fc3a5fe5c34ca08a38f5f7b1a2eb39" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": "https://payroll.your-domain.com/contractor-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ", "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://payroll.your-domain.com/contractor-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ" }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23, "status": 400, "correlationId": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } ], "success": false, "testMode": true } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/contractors/available_pay": { "post": { "summary": "Create Available Pay Enrollment Link (Early Access)", "description": "", "operationId": "create-available-pay-enrollment-link-contractor", "x-fern-sdk-group-name": "contractors", "x-fern-sdk-method-name": "postAvailablePay", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "contractorID"], "properties": { "companyID": { "type": "string", "description": "ID of the Employee being updated" }, "contractorID": { "type": "string", "description": "ID of the Contractor" }, "send_to_worker": { "type": "boolean", "description": "If true, notification email will be sent to contractor", "default": false } } }, "examples": { "Request Example": { "value": { "companyID": "3f5c2afcc5ea40c87a2c8f3f7e5a1cb1", "contractorID": "d2fc3a5fe5c34ca08a38f5f7b1a2eb39" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": "https://payroll.your-domain.com/contractor-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ", "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://payroll.your-domain.com/contractor-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ" }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23, "status": 400, "correlationId": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } ], "success": false, "testMode": true } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/employees/bank_information": { "post": { "summary": "Create Bank Account Collection Link", "description": "", "operationId": "create-bank-account-link", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "createBankAccountLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "employeeID"], "properties": { "companyID": { "type": "string", "description": "ID of the Employee being updated" }, "employeeID": { "type": "string", "description": "ID of the Employee being updated" }, "send_to_worker": { "type": "boolean", "description": "If true, notification email will be sent to employee", "default": false } } }, "examples": { "Request Example": { "value": { "companyID": "3f5c2afcc5ea40c87a2c8f3f7e5a1cb1", "employeeID": "c2fc3a5fe5c74ca08a38f5f7b1a2ec15" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "data": "https://payroll.your-domain.com/employee-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ", "success": true, "testMode": false } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://payroll.your-domain.com/employee-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ" }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "errors": [ { "message": "Employee with this employeeID does not exist", "code": 23, "status": 400, "correlationId": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } ], "success": false, "testMode": true } } }, "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 23, "default": 0 }, "status": { "type": "integer", "example": 400, "default": 0 }, "correlationId": { "type": "string", "example": "e9b73fdf-1f57-4e33-9f73-8bce7e7182b1" } } } }, "success": { "type": "boolean", "example": false, "default": true }, "testMode": { "type": "boolean", "example": true, "default": true } } } } } } }, "deprecated": false } }, "/contractors/onboard": { "post": { "summary": "Generate Contractor Onboarding Link", "description": "Generate a secure onboarding link for a contractor.", "operationId": "get-contractor-onboarding-link", "x-fern-sdk-group-name": "contractors", "x-fern-sdk-method-name": "getOnboardingLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "contractorID"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "contractorID": { "type": "string", "description": "ID of Contractor" }, "contractor_acct": { "type": "boolean", "description": "If false, the contractor account information (username and password) collection step of onboarding will be left out.", "default": false }, "survey": { "type": "boolean", "description": "If false, the contractor survey step will be left out (Early Access)", "default": false }, "id_scan": { "type": "boolean", "description": "If false, the ID collection step of contractor onboarding will be left out.", "default": false }, "payment_method_required": { "type": "boolean", "description": "If false, the onboarding worker will be able to skip the bank account collection section of onboarding", "default": false }, "paycard": { "type": "boolean", "description": "If false, the paycard enrollment screen will be left out. NOTE: Only applicable for Paycards (Early Access)", "default": false }, "instant_pay": { "type": "boolean", "description": "If false, the instant pay enrollment screen will be left out. NOTE: Only applicable for Instant Pay (Early Access)" } } }, "examples": { "Request Example": { "value": { "companyID": "eeeee434343553413eccc34534", "contractorID": "874759t85785745748e3847", "scan_id": true } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": "https://payroll.your-domain.com/contractoronboarding/10983755744920193854758300657020834" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "string", "example": "https://payroll.your-domain.com/contractoronboarding/10983755744920193854758300657020834" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No contractorID in the body/query of the request", "code": 35 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No contractorID in the body/query of the request" }, "code": { "type": "integer", "example": 35, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/contractorPayment": { "post": { "summary": "Create Contractor Payment", "description": "", "operationId": "create-contractor-payment", "x-fern-sdk-group-name": "contractorPayment", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "contractorID", "pay_date"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "contractorID": { "type": "string", "description": "ID of Contractor that needs to be paid out" }, "approval_required": { "type": "boolean", "description": "Set to `true` if this payment requires manual approval by the employer. Otherwise, by default, Zeal will automatically process the payment two business days before the `pay_date`", "default": false }, "pay_date": { "type": "string", "description": "Pay date for this payment. Formatted as a date in ISO-8601 format (YYYY-MM-DD). If the pay_date falls on a weekend/bank holiday or the current time is after 2 PM two days before the given pay_date, please correct the date and resubmit. We will not roll forward the pay_date automatically", "format": "date" }, "amount": { "type": "number", "description": "Amount that needs to be paid out. Only required if no payment items are present.", "format": "float" }, "payment_items": { "type": "array", "description": "Array of payment item objects. If payment items are present, `amount` is not required. ", "items": { "properties": {}, "type": "object" } }, "speed": { "type": "string", "description": "Accepts `two_day`, `one_day`, `one_day_no_reserve`, `zero_day`,`zero_day_no_reserve` or `instant` as values (**Early Access**)", "enum": [ "two_day", "one_day", "one_day_no_reserve", "zero_day", "instant", "zero_day_no_reserve" ] }, "type": { "type": "string", "description": "Type of payment. Only `regular` payments are reported on a contractor's Form 1099-NEC.", "default": "regular", "enum": ["regular", "reimbursement"] }, "disbursement": { "type": "object", "description": "The disbursement for the how payment will be made. Defaults to `direct_deposit` if left empty.", "properties": { "method": { "type": "string", "description": "The method of disbursement. There are 6 options: `direct_deposit` (Zeal will make a direct deposit to the contractor's bank account using Next Day ACH), `direct_deposit_same_day` (Zeal will make a direct deposit to the contractor's bank account using Same Day ACH), `physical_check` (Zeal will send a physical check to the employee's home address on file), `prepaid` (Zeal will *not* disburse the net pay), `paycard` (Zeal will instantly transfer funds to the existing paycard), and `instant_pay` (Zeal will send funds to the existing worker's Instant Pay wallet)" } }, "required": ["method"] }, "customerAccountID": { "type": "string", "description": "ID of Customer Account associated with this Contractor Payment" }, "apply_contractor_deductions": { "type": "boolean", "description": "Applies a deduction to this check for each contractor deduction template that is effective at the time of the pay date for the contractor. **Note: Only applicable when payment_items is provided**" }, "metadata": { "type": "object", "description": "Custom metadata object. ", "default": "false", "properties": { "example_metadata": { "type": "string" } } } } }, "examples": { "Request Example": { "value": { "approval_required": false, "contractorID": "62350595e7f1222323b3b824", "companyID": "24b5b29f05234840b119c34c1358940c", "pay_date": "2023-07-25", "amount": 21, "disbursement": { "method": "prepaid" }, "metadata": { "example": "example" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "contractorPaymentID": "0987654321", "status": "pending", "disbursement_status": "pending", "first_name": "erlich", "middle_name": null, "last_name": "bachman", "companyID": "1b5n28nrideucd24", "contractorID": "123456789", "approval_required": false, "approved": false, "pay_date": "2023-10-01", "amount": "100", "triggered": false, "triggered_at": null, "customerAccountID": null, "payment_items": [], "metadata": { "example": "example" } } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "contractorPaymentID": { "type": "string", "example": "0987654321" }, "status": { "type": "string", "example": "pending" }, "disbursement_status": { "type": "string", "example": "pending" }, "first_name": { "type": "string", "example": "erlich" }, "middle_name": {}, "last_name": { "type": "string", "example": "bachman" }, "companyID": { "type": "string", "example": "1b5n28nrideucd24" }, "contractorID": { "type": "string", "example": "123456789" }, "approval_required": { "type": "boolean", "example": false, "default": true }, "approved": { "type": "boolean", "example": false, "default": true }, "pay_date": { "type": "string", "example": "2023-10-01" }, "amount": { "type": "string", "example": "100" }, "triggered": { "type": "boolean", "example": false, "default": true }, "triggered_at": {}, "customerAccountID": {}, "metadata": { "type": "object", "properties": { "example": { "type": "string", "example": "example" } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Contractor Payment for this contractor and pay date already exists.", "code": 81 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor Payment for this contractor and pay date already exists." }, "code": { "type": "integer", "example": 81, "default": 0 } } } } } } } } } } }, "patch": { "summary": "Update Contractor Payment", "description": "", "operationId": "update-contractor-payment", "x-fern-sdk-group-name": "contractorPayment", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "contractorPaymentID"], "properties": { "companyID": { "type": "string", "description": "companyID of the company" }, "contractorPaymentID": { "type": "string", "description": "ID of the contractor payment to be updated" }, "contractorID": { "type": "string", "description": "ID of the contractor" }, "approval_required": { "type": "boolean", "description": "Boolean determining if approval is required for a contractor payment" }, "approved": { "type": "boolean", "description": "Boolean determining if contractor payment is approved or not" }, "pay_date": { "type": "string", "description": "Pay date of the contractor payment", "format": "date" }, "amount": { "type": "integer", "description": "Pay amount of the contractor payment", "format": "int32" }, "disbursement": { "type": "object", "description": "Disbursement pay object", "required": ["method"], "properties": { "method": { "type": "string", "description": "The method of disbursement. There are 6 options: `direct_deposit` (Zeal will make a direct deposit to the contractor's bank account using Next Day ACH), `direct_deposit_same_day` (Zeal will make a direct deposit to the contractor's bank account using Same Day ACH), `physical_check` (Zeal will send a physical check to the employee's home address on file), `prepaid` (Zeal will *not* disburse the net pay), `paycard` (Zeal will instantly transfer funds to the existing paycard), and `instant_pay` (Zeal will send funds to the existing worker's Instant Pay wallet)", "enum": [ "direct_deposit", "direct_deposit_same_day", "physical_check", "prepaid", "paycard" ] } } }, "type": { "type": "string", "description": "Type of payment. Only `regular` payments are reported on a contractor's Form 1099-NEC.", "enum": ["regular", "reimbursement"] }, "metadata": { "type": "object", "description": "Custom metadata object", "properties": {} }, "customerAccountID": { "type": "string", "description": "ID of Customer Account associated with Contractor Payment" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "contractorPaymentID": "6sd3382d4232390024d3f627", "disbursement": { "method": "direct_deposit" }, "status": "pending", "approval_required": true, "approved": true, "contractorID": "6283dqqe2391cc2a00257e2342", "companyID": "fc2323ccbae46aa8a083347715bcfa", "first_name": "Erlich", "last_name": "Bachman", "amount": 200, "pay_date": "2023-07-22", "triggered": false, "triggered_at": null, "customerAccountID": null, "metadata": { "example": "example" } } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "contractorPaymentID": { "type": "string", "example": "6sd3382d4232390024d3f627" }, "disbursement": { "type": "object", "properties": { "method": { "type": "string", "example": "direct_deposit" } } }, "status": { "type": "string", "example": "pending" }, "approval_required": { "type": "boolean", "example": true, "default": true }, "approved": { "type": "boolean", "example": true, "default": true }, "contractorID": { "type": "string", "example": "6283dqqe2391cc2a00257e2342" }, "companyID": { "type": "string", "example": "fc2323ccbae46aa8a083347715bcfa" }, "first_name": { "type": "string", "example": "Erlich" }, "last_name": { "type": "string", "example": "Bachman" }, "amount": { "type": "integer", "example": 200, "default": 0 }, "pay_date": { "type": "string", "example": "2023-07-22" }, "triggered": { "type": "boolean", "example": false, "default": true }, "triggered_at": {}, "customerAccountID": {}, "metadata": { "type": "object", "properties": { "example": { "type": "string", "example": "example" } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Contractor Payment with this payment ID does not exist", "code": 46 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor Payment with this payment ID does not exist" }, "code": { "type": "integer", "example": 46, "default": 0 } } } } } } } } } }, "deprecated": false }, "get": { "summary": "Get Contractor Payments", "description": "", "operationId": "retrieve-contractor-payments", "x-fern-sdk-group-name": "contractorPayment", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of the employer", "required": true, "schema": { "type": "string" } }, { "name": "contractorPaymentID", "in": "query", "description": "ID of the contractor payment to retrieve. When present, the endpoint returns that single payment and list filters (`contractorID`, `status`, `paymentGroupID`) are ignored.", "schema": { "type": "string" } }, { "name": "contractorID", "in": "query", "description": "When listing payments (omit `contractorPaymentID`), filter to this contractor. Ignored when `contractorPaymentID` is present.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status of contractor payment. Provide one of the following statuses: `pending`, `pre-processed`, `processed`", "schema": { "type": "string", "enum": ["pending", "pre-processed", "processed"] } }, { "name": "paymentGroupID", "in": "query", "description": "Filter by contractor payment group", "schema": { "type": "string" } }, { "name": "start_at", "in": "query", "description": "The pagination cursor to start at", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limit the amount of data returned", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "List of pending payments": { "summary": "Pending payments have no paymentGroupID yet", "value": { "success": true, "data": [ { "contractorPaymentID": "24ce6cb4144bac8a33e13223b2b462", "status": "pending", "disbursement_status": "pending", "first_name": "erlich", "middle_name": "null", "last_name": "bachman", "companyID": "fcce6cc41440ac8a33e13223bbb462", "contractorID": "cbce6cc414403c8a33e43223bbb469", "approval_required": false, "approved": false, "pay_date": "2023-10-01", "amount": 100, "triggered": false, "triggered_at": null, "customerAccountID": null, "metadata": { "example": "example" } } ], "meta": { "next": "https://api.zeal.com/contractorPayment?startAt=24ce6cb4144bac8a33e13223b2b4b&limit=10", "previous": null } } }, "Single payment after pre-process": { "summary": "paymentGroupID is present after the payment is grouped", "value": { "success": true, "data": { "contractorPaymentID": "24ce6cb4144bac8a33e13223b2b462", "status": "pre-processed", "disbursement_status": "pending", "first_name": "erlich", "middle_name": "null", "last_name": "bachman", "companyID": "fcce6cc41440ac8a33e13223bbb462", "contractorID": "cbce6cc414403c8a33e43223bbb469", "approval_required": false, "approved": false, "pay_date": "2023-10-01", "amount": 100, "paymentGroupID": "8808c9c05afd407393d25b8de7f55a23", "triggered": false, "triggered_at": null, "customerAccountID": null, "metadata": { "example": "example" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee or Contractor ID is not formatted correctly", "code": 17 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee or Contractor ID is not formatted correctly" }, "code": { "type": "integer", "example": 17, "default": 0 } } } } } } } } } }, "deprecated": false }, "delete": { "summary": "Delete Contractor Payment", "description": "", "operationId": "delete-contractor-payment", "x-fern-sdk-group-name": "contractorPayment", "x-fern-sdk-method-name": "delete", "parameters": [ { "name": "companyID", "in": "query", "description": "ID of the company", "required": true, "schema": { "type": "string" } }, { "name": "contractorPaymentID", "in": "query", "description": "ID of the corresponding contractor payment", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "message": "Contractor Payment(s) deleted" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor Payment(s) deleted" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Contractor Payment with this payment ID does not exist.", "code": 46 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor Payment with this payment ID does not exist." }, "code": { "type": "integer", "example": 46, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/contractorPayment/trigger": { "post": { "summary": "Trigger Disbursement", "description": "", "operationId": "trigger-disbursement-contractor-payment", "x-fern-sdk-group-name": "contractorPayment", "x-fern-sdk-method-name": "triggerDisbursement", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "contractorPaymentID"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "contractorPaymentID": { "type": "string", "description": "ID of Contractor Payment that you wish to disburse the amounts for" } } }, "examples": { "Request Example": { "value": { "companyID": "24b5b29f05234840b119c34c1358940c", "contractorPaymentID": "62350595e7f1222323b3b824" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "contractorPaymentID": "0987654321", "status": "pending", "disbursement_status": "pending", "first_name": "erlich", "middle_name": null, "last_name": "bachman", "companyID": "1b5n28nrideucd24", "contractorID": "123456789", "approval_required": false, "approved": false, "pay_date": "2023-10-01", "amount": "100", "triggered": true, "customerAccountID": null, "triggered_at": "2025-03-04T23:18:09Z", "metadata": { "example": "example" } } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "contractorPaymentID": { "type": "string", "example": "0987654321" }, "status": { "type": "string", "example": "pending" }, "disbursement_status": { "type": "string", "example": "pending" }, "first_name": { "type": "string", "example": "erlich" }, "middle_name": {}, "last_name": { "type": "string", "example": "bachman" }, "companyID": { "type": "string", "example": "1b5n28nrideucd24" }, "contractorID": { "type": "string", "example": "123456789" }, "approval_required": { "type": "boolean", "example": false, "default": true }, "approved": { "type": "boolean", "example": false, "default": true }, "pay_date": { "type": "string", "example": "2023-10-01" }, "amount": { "type": "string", "example": "100" }, "triggered": { "type": "boolean", "example": true, "default": true }, "customerAccountID": {}, "triggered_at": { "type": "string", "example": "2025-03-04T23:18:09Z" }, "metadata": { "type": "object", "properties": { "example": { "type": "string", "example": "example" } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Contractor Payment for this contractor and pay date already exists.", "code": 81 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor Payment for this contractor and pay date already exists." }, "code": { "type": "integer", "example": 81, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reports/payroll-journal": { "post": { "summary": "Create Payroll Journal Report", "description": "Create a payroll journal report.", "operationId": "create-payroll-journal-report", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "createPayrollJournal", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "start_date", "end_date", "companyID", "media_type" ], "properties": { "start_date": { "type": "string", "description": "The first check date this report should retrieve checks for. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "end_date": { "type": "string", "description": "The last check date this report should retrieve checks for. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "companyID": { "type": "string", "description": "Zeal Company ID" }, "media_type": { "type": "string", "description": "The type of format this report can be downloaded as. Payroll Journals currently support \"csv\" and \"pdf\".", "enum": ["csv", "pdf"] }, "include_migrated": { "type": "boolean", "description": "Include migrated data in the report" }, "with_preview_data": { "type": "boolean", "description": "Include preview data in the report (if `media_type` = `csv` only)" } } }, "examples": { "Request Example": { "value": { "start_date": "2022-01-01", "end_date": "2022-03-28", "companyID": "fc235f012bae46aa8a082f357715bcfa", "media_type": "csv", "include_migrated": false } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "job_id": "76f8a4e0-f2a0-4dc0-9a1c-215e083de5eb", "status": "pending", "request_body": { "start_date": "2022-01-01", "end_date": "2022-03-28", "company_id": "fc235f012bae46aa8a082f357715bcfa", "media_type": "csv", "include_migrated": false, "has_live_key": true, "report_format": "payroll_journal" }, "created_at": "2023-12-25T18:52:43.138Z" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "76f8a4e0-f2a0-4dc0-9a1c-215e083de5eb" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "start_date": { "type": "string", "example": "2022-01-01" }, "end_date": { "type": "string", "example": "2022-03-28" }, "company_id": { "type": "string", "example": "fc235f012bae46aa8a082f357715bcfa" }, "media_type": { "type": "string", "example": "csv" }, "include_migrated": { "type": "boolean", "example": false, "default": true }, "has_live_key": { "type": "boolean", "example": true, "default": true }, "report_format": { "type": "string", "example": "payroll_journal" } } }, "created_at": { "type": "string", "example": "2023-12-25T18:52:43.138Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reports/custom-payroll-journal": { "post": { "summary": "Create Custom Payroll Journal Report", "description": "Create a custom payroll journal report.", "operationId": "create-a-custom-payroll-journal", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "createCustomPayrollJournal", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "media_type", "start_date", "end_date" ], "properties": { "companyID": { "type": "string", "description": "Zeal Company ID" }, "media_type": { "type": "string", "description": "The type of format this report can be downloaded as. Payroll Journals currently support \"csv\" and \"pdf\".", "enum": ["csv", "pdf"] }, "start_date": { "type": "string", "description": "The first check date this report should retrieve checks for. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "end_date": { "type": "string", "description": "The last check date this report should retrieve checks for. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "fields": { "type": "object", "description": "Optional fields and parameters for Custom Payroll Journal", "properties": { "employee_taxes": { "type": "boolean", "description": "Boolean to include employee taxes in the Custom Payroll Journal report" }, "employer_taxes": { "type": "boolean", "description": "Boolean to include employer taxes in the Custom Payroll Journal report" }, "deductions": { "type": "boolean", "description": "Boolean to include deductions in the Custom Payroll Journal report" }, "net_pay": { "type": "boolean", "description": "Boolean to include employee's net pay" }, "earnings": { "type": "boolean", "description": "Boolean to include employee's earnings" }, "disbursement": { "type": "boolean", "description": "Boolean to include disbursement" }, "gross_pay": { "type": "boolean", "description": "Boolean to include employee's gross pay" }, "employer_check_id": { "type": "boolean", "description": "Boolean to include employer check ID" } } }, "customer_account_ids": { "type": "array", "description": "Filter by customer account(s) (Early Access)", "items": { "type": "string" } } } }, "examples": { "Request Example": { "value": { "start_date": "2022-03-22", "end_date": "2022-04-10", "companyID": "24b5b29f07924840b119c34c1358940c", "media_type": "pdf", "fields": { "employee_taxes": false, "employer_taxes": false, "deductions": false, "net_pay": false, "earnings": false, "disbursement": false, "gross_pay": false } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "job_id": "7282b13f-254f-4eb9-bt88-24f429be6aa0", "status": "pending", "request_body": { "start_date": "2022-03-22", "end_date": "2022-04-10", "companyID": "24b5b29f07924840b119c34c1358940c", "media_type": "pdf", "fields": { "employee_taxes": false, "employer_taxes": false, "deductions": false, "net_pay": false, "earnings": false, "disbursement": false, "gross_pay": false }, "has_live_key": true, "report_format": "custom_payroll_journal" }, "created_at": "2023-12-18T22:15:08.977Z" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "7282b13f-254f-4eb9-bt88-24f429be6aa0" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "start_date": { "type": "string", "example": "03-22-2022" }, "end_date": { "type": "string", "example": "04-10-2022" }, "companyID": { "type": "string", "example": "24b5b29f07924840b119c34c1358940c" }, "media_type": { "type": "string", "example": "pdf" }, "fields": { "type": "object", "properties": { "employee_taxes": { "type": "boolean", "example": false, "default": true }, "employer_taxes": { "type": "boolean", "example": false, "default": true }, "deductions": { "type": "boolean", "example": false, "default": true }, "net_pay": { "type": "boolean", "example": false, "default": true }, "earnings": { "type": "boolean", "example": false, "default": true }, "disbursement": { "type": "boolean", "example": false, "default": true }, "gross_pay": { "type": "boolean", "example": false, "default": true } } }, "has_live_key": { "type": "boolean", "example": true, "default": true }, "report_format": { "type": "string", "example": "custom_payroll_journal" } } }, "created_at": { "type": "string", "example": "2023-12-18T22:15:08.977Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reports/worker-summary": { "post": { "summary": "Create Worker Summary Report", "description": "Create a worker summary report.", "operationId": "create-a-worker-summary-report", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "createWorkerSummary", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "worker_type", "media_type"], "properties": { "companyID": { "type": "string", "description": "Zeal Company ID" }, "worker_type": { "type": "string", "description": "Type of worker this report can be downloaded for. Accepted values are \"employee\" and \"contractor\".", "enum": ["employee", "contractor"] }, "media_type": { "type": "string", "description": "The type of format this report can be downloaded as. Worker Summary Report currently support \"csv\" and \"pdf\".", "enum": ["csv", "pdf"] }, "active_workers": { "type": "boolean", "description": "Determine whether the worker summary report returns terminated workers" } } }, "examples": { "Request Example": { "value": { "companyID": "fc235f012bae46aa8a082f357715bcfa", "worker_type": "employee", "media_type": "csv", "active_workers": true } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "job_id": "707ce36e-2267-2088-9fc4-c34d57c69c72", "status": "pending", "request_body": { "companyID": "24bsb29f07924840b119c34c1358940c", "worker_type": "employee", "media_type": "pdf", "active_workers": true, "has_live_key": true, "report_format": "worker_summary" }, "created_at": "2023-12-29T18:21:28.951Z" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "707ce36e-2267-2088-9fc4-c34d57c69c72" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "companyID": { "type": "string", "example": "24bsb29f07924840b119c34c1358940c" }, "worker_type": { "type": "string", "example": "employee" }, "media_type": { "type": "string", "example": "pdf" }, "active_workers": { "type": "boolean", "example": true, "default": true }, "has_live_key": { "type": "boolean", "example": true, "default": true }, "report_format": { "type": "string", "example": "worker_summary" } } }, "created_at": { "type": "string", "example": "2023-12-29T18:21:28.951Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reports/cash-requirements": { "post": { "summary": "Create Cash Requirements Report", "description": "Create a cash requirements report", "operationId": "create-a-cash-requirements-report", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "createCashRequirements", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "check_date", "media_type"], "properties": { "companyID": { "type": "string", "description": "Zeal Company ID" }, "check_date": { "type": "string", "description": "Check date this report is requested for. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "media_type": { "type": "string", "description": "The type of format this report can be downloaded as. Cash Requirement reports currently only support \"pdf\".", "default": "pdf" }, "customer_account_ids": { "type": "array", "description": "Filter by customer account(s) (Early Access)", "items": { "type": "string" } } } }, "examples": { "Request Example": { "value": { "companyID": "fc235f012bae46aa8a082f357715bcfa", "check_date": "2023-12-22", "media_type": "pdf" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "job_id": "cd4bbf73-e141-42bd-a331-5845c994ebe1", "status": "pending", "request_body": { "company_id": "fc235f012bae46aa8a082f357715bcfa", "check_date": "2022-01-22", "media_type": "pdf", "has_live_key": true, "report_format": "cash_requirements" }, "created_at": "2023-12-25T16:48:36.802Z" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "cd4bbf73-e141-42bd-a331-5845c994ebe1" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "company_id": { "type": "string", "example": "fc235f012bae46aa8a082f357715bcfa" }, "check_date": { "type": "string", "example": "2022-01-22" }, "media_type": { "type": "string", "example": "pdf" }, "has_live_key": { "type": "boolean", "example": true, "default": true }, "report_format": { "type": "string", "example": "cash_requirements" } } }, "created_at": { "type": "string", "example": "2023-12-25T16:48:36.802Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reports/payment-summary": { "post": { "summary": "Create Payment Summary Report", "description": "Create a payment summary report.", "operationId": "create-a-payment-summary-report", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "createPaymentSummary", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "pay_start_date", "pay_end_date", "companyID", "media_type" ], "properties": { "pay_start_date": { "type": "string", "description": "The first payment date this report should retrieve payments for. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "pay_end_date": { "type": "string", "description": "The last payment date this report should retrieve payments for. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "companyID": { "type": "string", "description": "Zeal Company ID" }, "media_type": { "type": "string", "description": "The type of format this report can be downloaded as. Payment Summaries currently support \"csv\" and \"pdf\".", "enum": ["csv", "pdf"] }, "include_intl_contractors": { "type": "boolean", "description": "Include international contractors in this report" } } }, "examples": { "Request Example": { "value": { "pay_start_date": "2023-12-01", "pay_end_date": "2023-12-28", "companyID": "fc235f012bae46aa8a082f357715bcfa", "media_type": "pdf" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "job_id": "76f8a4e0-f2a0-4dc0-9a1c-215e083de5eb", "status": "pending", "request_body": { "start_date": "2022-01-01", "end_date": "2022-03-28", "company_id": "fc235f012bae46aa8a082f357715bcfa", "media_type": "pdf", "has_live_key": true, "report_format": "payment_summary" }, "created_at": "2023-12-25T18:52:43.138Z" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "76f8a4e0-f2a0-4dc0-9a1c-215e083de5eb" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "start_date": { "type": "string", "example": "2022-01-01" }, "end_date": { "type": "string", "example": "2022-03-28" }, "company_id": { "type": "string", "example": "fc235f012bae46aa8a082f357715bcfa" }, "media_type": { "type": "string", "example": "pdf" }, "has_live_key": { "type": "boolean", "example": true, "default": true }, "report_format": { "type": "string", "example": "payment_summary" } } }, "created_at": { "type": "string", "example": "2023-12-25T18:52:43.138Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No start date found in query of request", "code": 19 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No start date found in query of request" }, "code": { "type": "integer", "example": 19, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reports/labor-allocation": { "post": { "summary": "Create Labor Allocation Report", "description": "Create a labor allocation report.", "operationId": "create-a-labor-allocation-report", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "createLaborAllocation", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "start_date", "end_date", "companyID", "media_type" ], "properties": { "start_date": { "type": "string", "description": "Start date of Labor data. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "end_date": { "type": "string", "description": "End date of Labor data. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "companyID": { "type": "string", "description": "ID of the company for report" }, "media_type": { "type": "string", "description": "Type of file the report will be (csv is the only supported file)", "default": "csv" }, "customer_account_ids": { "type": "array", "description": "Filter by customer account(s) (Early Access)", "items": { "type": "string" } }, "include_migrated": { "type": "boolean", "description": "Include migrated data in the report" } } }, "examples": { "Request Example": { "value": { "start_date": "2023-12-01", "end_date": "2024-12-20", "companyID": "24b5b29f07924230b119c34c1358940c", "media_type": "csv", "include_migrated": false } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "job_id": "c33bbb6d-b6cf-45bt-891d-aa94743f2d97", "status": "pending", "request_body": { "start_date": "2023-12-01", "end_date": "2023-12-20", "companyID": "24b5b23f07924820b119c34c1358940c", "media_type": "csv", "include_migrated": false, "has_live_key": true, "report_format": "labor_allocation" }, "created_at": "2023-12-21T22:08:16.596Z" } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reports/paystub": { "post": { "summary": "Create Paystub Report", "description": "Create paystub report.", "operationId": "create-paystub-report", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "createPaystub", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "start_date", "end_date", "media_type" ], "properties": { "companyID": { "type": "string", "description": "ID of the Company" }, "start_date": { "type": "string", "description": "Start date of the dates that span the Paystub Report. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "end_date": { "type": "string", "description": "End date of the dates that span the Paystub Report (will default to today's date if left blank). Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "media_type": { "type": "string", "description": "The media type of the report, only PDF is supported", "default": "pdf" } } }, "examples": { "Request Example": { "value": { "companyID": "0f2341ee141040acea333e132a3ccb462", "start_date": "2023-12-20", "end_date": "2023-12-06", "media_type": "pdf" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "job_id": "3088e25-115d-4c47-2224-05gh47843f0f", "status": "pending", "request_body": { "companyID": "0f2341ee141040acea333e132a3ccb462", "start_date": "2023-12-20", "end_date": "2023-12=06", "media_type": "pdf", "has_live_key": true, "report_format": "paystub" }, "created_at": "2023-12-06T18:05:13.175Z" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "3088e25-115d-4c47-2224-05gh47843f0f" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "companyID": { "type": "string", "example": "0f2341ee141040acea333e132a3ccb462" }, "start_date": { "type": "string", "example": "2023-12-20" }, "end_date": { "type": "string", "example": "2023-12=06" }, "media_type": { "type": "string", "example": "pdf" }, "has_live_key": { "type": "boolean", "example": true, "default": true }, "report_format": { "type": "string", "example": "paystub" } } }, "created_at": { "type": "string", "example": "2023-12-06T18:05:13.175Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reports/ytd": { "post": { "summary": "Create Year to Date Report", "description": "Create a year-to-date report.", "operationId": "year-to-date-report", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "createYearToDate", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "year", "media_type"], "properties": { "companyID": { "type": "string", "description": "The ID of the company" }, "employeeID": { "type": "array", "description": "Array of employee IDs to grab YTD data for. If this field is omitted, or an empty array is provided, then the report will include all employees", "items": { "type": "string" } }, "year": { "type": "string", "description": "The year to query for the report" }, "media_type": { "type": "string", "description": "The media_type of the report", "default": "json", "enum": ["json", "csv"] }, "include_migrated": { "type": "boolean", "description": "Include migrated data in the report", "default": "false" } } }, "examples": { "Request Example": { "value": { "companyID": "fcc26cc444450ac8a33ry32a3z34462", "employeeID": [ "6266y546eyecc34458aef1", "6556fabfcf2eab26e23331" ], "year": "2023", "media_type": "json" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "job_id": "4a25e61a9-9bd2-4445-ba70-f3e874d772d2", "status": "pending", "request_body": { "companyID": "fcc26cc444450ac8a33ry32a3z34462", "employeeID": [ "6266y546eyecc34458aef1", "6556fabfcf2eab26e23331" ], "year": "2023", "media_type": "json", "has_live_key": true, "job_type": "reports", "report_format": "ytd" }, "created_at": "2023-12-07T16:25:35.575Z" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "4a25e61a9-9bd2-4445-ba70-f3e874d772d2" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "companyID": { "type": "string", "example": "fcc26cc444450ac8a33ry32a3z34462" }, "employeeID": { "type": "array", "items": { "type": "string", "example": "6266y546eyecc34458aef1" } }, "year": { "type": "string", "example": "2023" }, "media_type": { "type": "string", "example": "json" }, "has_live_key": { "type": "boolean", "example": true, "default": true }, "job_type": { "type": "string", "example": "reports" }, "report_format": { "type": "string", "example": "ytd" } } }, "created_at": { "type": "string", "example": "2023-12-07T16:25:35.575Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Date is not a valid date", "code": 44 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Date is not a valid date" }, "code": { "type": "integer", "example": 44, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reports/qtd": { "post": { "summary": "Create Quarter to Date Report", "description": "Create a quarter to date report.", "operationId": "quarter-to-date-report", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "createQuarterToDate", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "quarter", "media_type"], "properties": { "companyID": { "type": "string", "description": "The ID of the company" }, "employeeID": { "type": "array", "description": "Array of employee IDs to grab QTD data for", "items": { "type": "string" } }, "quarter": { "type": "string", "description": "The quarter to grab QTD data for (options are q1, q2, q3, and q4)" }, "media_type": { "type": "string", "description": "The media_type of the report, currently only supporting json", "default": "json" } } }, "examples": { "Request Example": { "value": { "companyID": "fcc26cc444450ac8a33ry32a3z34462", "employeeID": [ "6266y546eyecc34458aef1", "6556fabfcf2eab26e23331" ], "quarter": "q1", "media_type": "json" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "job_id": "e560b4e3-71a5-49cb-aedc-8e8yy3db81a", "status": "pending", "request_body": { "companyID": "fcc26cc444450ac8a33ry32a3z34462", "employeeID": [ "6266y546eyecc34458aef1", "6556fabfcf2eab26e23331" ], "quarter": "q1", "media_type": "json", "has_live_key": true, "job_type": "reports", "report_format": "qtd" }, "created_at": "2023-12-07T18:49:28.679Z" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "e560b4e3-71a5-49cb-aedc-8e8yy3db81a" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "companyID": { "type": "string", "example": "fcc26cc444450ac8a33ry32a3z34462" }, "employeeID": { "type": "array", "items": { "type": "string", "example": "6266y546eyecc34458aef1" } }, "quarter": { "type": "string", "example": "q1" }, "media_type": { "type": "string", "example": "json" }, "has_live_key": { "type": "boolean", "example": true, "default": true }, "job_type": { "type": "string", "example": "reports" }, "report_format": { "type": "string", "example": "qtd" } } }, "created_at": { "type": "string", "example": "2023-12-07T18:49:28.679Z" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee or Contractor ID is not formatted correctly", "code": 72 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee or Contractor ID is not formatted correctly" }, "code": { "type": "integer", "example": 72, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reports/deductions-summary": { "post": { "summary": "Create Deduction Summary Report", "description": "Create a summary report outlining deductions within a given timeframe", "operationId": "create-deduction-summary-report", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "createDeductionSummary", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "media_type", "start_date", "end_date" ], "properties": { "companyID": { "type": "string", "description": "ID of the company." }, "media_type": { "type": "string", "description": "The type of format this report can be downloaded as. Deduction Summary currently only supports \"csv\".", "default": "csv" }, "start_date": { "type": "string", "description": "The start check date this report should retrieve deductions for. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "end_date": { "type": "string", "description": "The end check date this report should retrieve deductions for. Date should be in ISO-8601 format (YYYY-MM-DD).", "format": "date" }, "customer_account_ids": { "type": "array", "description": "Filter by customer account(s) (Early Access)", "items": { "type": "string" } } } }, "examples": { "Request Example": { "value": { "companyID": "f3cc3ec1fb1e144bd39504ue80cf3e20612", "media_type": "csv", "start_date": "2024-04-01", "end_date": "2024-05-30" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "job_id": "7282b13f-254f-4eb9-bt88-24f429be6aa0", "status": "pending", "request_body": { "companyID": "f3cc3ec1fb1e144bd39504ue80cf3e20612", "media_type": "csv", "start_date": "2024-04-01", "end_date": "2024-05-30" }, "has_live_key": true, "report_format": "deductions-summary" }, "created_at": "2024-12-18T22:15:08.977Z" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "7282b13f-254f-4eb9-bt88-24f429be6aa0" }, "status": { "type": "string", "example": "pending" }, "request_body": { "type": "object", "properties": { "companyID": { "type": "string", "example": "f3cc3ec1fb1e144bd39504ue80cf3e20612" }, "media_type": { "type": "string", "example": "csv" }, "start_date": { "type": "string", "example": "2024-04-01" }, "end_date": { "type": "string", "example": "2024-05-30" } } }, "has_live_key": { "type": "boolean", "example": true, "default": true }, "report_format": { "type": "string", "example": "deductions-summary" } } }, "created_at": { "type": "string", "example": "2024-12-18T22:15:08.977Z" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/reports": { "get": { "summary": "Get Job Status", "description": "Get status for a job.", "operationId": "get-job-status", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "job_id", "in": "query", "description": "Job ID returned in the POST response for whatever report was created.", "required": true, "schema": { "type": "string" } }, { "name": "companyID", "in": "query", "description": "Zeal Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "job_id": "7g88a4e0-f2a0-4dc0-9a1c-215e083de5eb", "status": "complete", "created_at": "2023-12-25T18:52:43.138Z", "request_body": { "start_date": "2023-12-01", "end_date": "2023-12-09", "company_id": "fc235f012bae46aa8a082f357715bcfa", "media_type": "csv", "has_live_key": true, "report_format": "payroll_journal" }, "payload": "https://api.zeal.com/reports/downloads/7g88a4e0-f2a0-4dc0-9a1c-215e083de5eb" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "example": "7g88a4e0-f2a0-4dc0-9a1c-215e083de5eb" }, "status": { "type": "string", "example": "complete" }, "created_at": { "type": "string", "example": "2023-12-25T18:52:43.138Z" }, "request_body": { "type": "object", "properties": { "start_date": { "type": "string", "example": "2023-12-01" }, "end_date": { "type": "string", "example": "2023-12-09" }, "company_id": { "type": "string", "example": "fc235f012bae46aa8a082f357715bcfa" }, "media_type": { "type": "string", "example": "csv" }, "has_live_key": { "type": "boolean", "example": true, "default": true }, "report_format": { "type": "string", "example": "payroll_journal" } } }, "payload": { "type": "string", "example": "https://api.zeal.com/reports/downloads/7g88a4e0-f2a0-4dc0-9a1c-215e083de5eb" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Must provide a valid companyID", "code": 50 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Must provide a valid companyID" }, "code": { "type": "integer", "example": 50, "default": 0 } } } } } } } } } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": {}, "examples": { "Request Example": { "value": { "job_id": "76f8a4e0-f2a0-4dc0-9a1c-215e083de5eb", "companyID": "fc235f012bae46aa8a082f357715bcfa" } } } } } } } }, "/reports/downloads": { "get": { "summary": "Get Report Download", "description": "Download a report.", "operationId": "retrieve-report-download", "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "download", "parameters": [ { "name": "job_id", "in": "query", "description": "Job ID returned in the POST response for whichever report was created.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "payload": "https://api.zeal.com/reports/downloads/76f8a4e0-f2a0-4dc0-9a1c-215e083de5eb" } } }, "schema": { "type": "object", "properties": { "payload": { "type": "string", "example": "https://api.zeal.com/reports/downloads/76f8a4e0-f2a0-4dc0-9a1c-215e083de5eb" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Object(s) is missing required fields or have improperly formatted data", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Object(s) is missing required fields or have improperly formatted data" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": {}, "examples": { "Request Example": { "value": { "job_id": "76f8a4e0-f2a0-4dc0-9a1c-215e083de5eb" } } } } } } } }, "/documents": { "get": { "summary": "Get Documents", "description": "Fetch tax/payroll documents such as tax returns and W-2s for an employer/employee.", "operationId": "get-documents", "x-fern-sdk-group-name": "documents", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Filter by id of employee or contractor to get documents for the given worker", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, " data": [ { "companyID": "1b5n28nrideucd24", "type": "W2", "description": "2024 Wage and Tax Statement (Form W2)", "id": "1234567891", "link": "https://test-documents.s3.amazonaws.com/1cccxx344ideucd24-2023-W2-1234567890-document" }, { "companyID": "1b5n28nrideucd24", "type": "W2", "description": "2023 Wage and Tax Statement (Form W2)", "id": "1234567892", "link": "https://test-documents.s3.amazonaws.com/1cccc8nr4ideucd24-2023-W2-1234567890-document" }, { "companyID": "1b5n28nrideucd24", "type": "W2C", "description": "2022 Corrected Wage and Tax Statement (Form W2C)", "id": "1234567893", "link": "https://test-documents.s3.amazonaws.com/1b5n24444eucd24-2022-W2C-1234567890-document" }, { "companyID": "1b5n28nrideucd24", "type": "W2", "description": "2021 Wage and Tax Statement (Form W2)", "id": "1234567894", "link": "https://test-documents.s3.amazonaws.com/1b5n28n5455eucd24-2021-W2-1234567890-document" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, " data": { "type": "array", "items": { "type": "object", "properties": { "companyID": { "type": "string", "example": "1b5n28nrideucd24" }, "type": { "type": "string", "example": "W2" }, "description": { "type": "string", "example": "2024 Wage and Tax Statement (Form W2)" }, "id": { "type": "string", "example": "1234567891" }, "link": { "type": "string", "example": "https://test-documents.s3.amazonaws.com/1cccxx344ideucd24-2023-W2-1234567890-document" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee with this employeeID does not exist", "code": 4 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee with this employeeID does not exist" }, "code": { "type": "integer", "example": 4, "default": 0 } } } } } } } } } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": {}, "examples": { "Request Example": { "value": { "companyID": "qtvyuwbdiknd" } } } } } } } }, "/internationalContractors": { "post": { "summary": "Create International Contractors", "description": "Create an international contractor.", "operationId": "create-international-contractors", "x-fern-sdk-group-name": "internationalContractors", "x-fern-sdk-method-name": "create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID"], "properties": { "companyID": { "type": "string", "description": "Company ID of Employer" }, "new_international_contractors": { "type": "array", "description": "Array of [International Contractor Objects](ref:international-contractor-object)", "items": { "properties": { "email": { "type": "string", "description": "Email address of the International Contractor" }, "onboarded": { "type": "boolean" }, "start_date": { "type": "string" }, "tax_rate": { "type": "number", "format": "float" }, "employment_status": { "type": "string", "default": "live", "enum": ["live", "leave", "terminated"] } }, "required": ["email", "tax_rate"], "type": "object" } } } }, "examples": { "Request Example": { "value": { "companyID": "24b5b29f07924840b119c34c", "new_international_contractors": [ { "email": "erlich@aviato.com", "tax_rate": 30, "onboarded": "false", "employment_status": "live", "start_date": "2023-08-20" }, { "email": "richard@piedpiper.com", "tax_rate": 20, "onboarded": "true", "employment_status": "terminated", "start_date": "2023-08-20" } ] } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "intlContractorID": "b6bda6912c434b8295de48fe2f0f3663", "email": "erlich@aviato.com", "companyID": "24b5b29f07924840b119c34c1358940c", "onboarded": false, "start_date": "2023-08-20", "employment_status": "live", "tax_rate": 30 }, { "intlContractorID": "1dbfd16619494e59bd9627735d576c78", "email": "richard@piedpiper.com", "companyID": "24b5b29f07924840b119c34c1358940c", "onboarded": true, "start_date": "2023-08-20", "employment_status": "terminated", "tax_rate": 20 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "intlContractorID": { "type": "string", "example": "b6bda6912c434b8295de48fe2f0f3663" }, "email": { "type": "string", "example": "erlich@aviato.com" }, "companyID": { "type": "string", "example": "24b5b29f07924840b119c34c1358940c" }, "onboarded": { "type": "boolean", "example": false, "default": true }, "start_date": { "type": "string", "example": "2023-08-20" }, "employment_status": { "type": "string", "example": "live" }, "tax_rate": { "type": "integer", "example": 30, "default": 0 } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Email must be valid", "code": 97 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Email must be valid" }, "code": { "type": "integer", "example": 97, "default": 0 } } } } } } } } } }, "deprecated": false }, "patch": { "summary": "Update International Contractor", "description": "Update an international contractor.", "operationId": "update-international-contractor", "x-fern-sdk-group-name": "internationalContractors", "x-fern-sdk-method-name": "update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID"], "properties": { "companyID": { "type": "string", "description": "Company ID of Employer" }, "international_contractor": { "type": "object", "description": "International Contractor Object", "required": ["intlContractorID"], "properties": { "intlContractorID": { "type": "string", "description": "ID of the international contractor" }, "email": { "type": "string", "description": "Email of the international contractor" }, "onboarded": { "type": "boolean" }, "start_date": { "type": "string", "description": "Start date of the international contractor" }, "tax_rate": { "type": "number", "description": "The percentage that the company intends to withhold from each payment to an international contractor", "format": "float" }, "employment_status": { "type": "string", "description": "Employment status of the international contractor", "default": "live", "enum": ["live", "leave", "terminated"] } } } } }, "examples": { "Request Example": { "value": { "companyID": "24b5b29f07924840b119c34c1358940c", "international_contractor": { "intlContractorID": "b6bda6912c434b8295de48fe2f0f3663", "email": "erlich+bachman@aviato.com", "tax_rate": "50", "onboarded": "true", "start_date": "2023-12-20" } } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "intlContractorID": "b6bda6912c434b8295de48fe2f0f3663", "email": "erlich+bachman@aviato.com", "companyID": "24b5b29f07924840b119c34c1358940c", "onboarded": true, "start_date": "2023-12-20", "employment_status": "live", "tax_rate": "50" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "intlContractorID": { "type": "string", "example": "b6bda6912c434b8295de48fe2f0f3663" }, "email": { "type": "string", "example": "erlich+bachman@aviato.com" }, "companyID": { "type": "string", "example": "24b5b29f07924840b119c34c1358940c" }, "onboarded": { "type": "boolean", "example": true, "default": true }, "start_date": { "type": "string", "example": "2023-12-20" }, "employment_status": { "type": "string", "example": "live" }, "tax_rate": { "type": "string", "example": "50" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Company with this companyID does not exist", "code": 13 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Company with this companyID does not exist" }, "code": { "type": "integer", "example": 13, "default": 0 } } } } } } } } } }, "deprecated": false }, "get": { "summary": "Get International Contractor Information", "description": "Get international contractors for a company or a specific contractor.", "operationId": "get-international-contractor", "x-fern-sdk-group-name": "internationalContractors", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of employer", "required": true, "schema": { "type": "string" } }, { "name": "intlContractorID", "in": "query", "description": "ID of the International Contractor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "intlContractorID": "b6bda6912c434b8295de48fe2f0f3663", "email": "erlich+bachman@aviato.com", "companyID": "24b5ee4973cc984lejjz9c34c1358940c", "onboarded": true, "start_date": "2023-12-20", "employment_status": "live", "tax_rate": "50" } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "intlContractorID": { "type": "string", "example": "b6bda6912c434b8295de48fe2f0f3663" }, "email": { "type": "string", "example": "erlich+bachman@aviato.com" }, "companyID": { "type": "string", "example": "24b5ee4973cc984lejjz9c34c1358940c" }, "onboarded": { "type": "boolean", "example": true, "default": true }, "start_date": { "type": "string", "example": "2023-12-20" }, "employment_status": { "type": "string", "example": "live" }, "tax_rate": { "type": "string", "example": "50" } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Contractor with this contractorID does not exist", "code": 73 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor with this contractorID does not exist" }, "code": { "type": "integer", "example": 73, "default": 0 } } } } } } } } } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": {}, "examples": { "Request Example": { "value": { "intlContractorID": "b6bda6912c434b8295de48fe2f0f3663", "companyID": "24b5ee4973cc984lejjz9c34c1358940c" } } } } } } } }, "/internationalContractors/onboard": { "post": { "summary": "Generate International Contractor Onboarding Link", "description": "Generate a secure onboarding link for an international contractor.", "operationId": "generate-international-contractor-onboarding-link", "x-fern-sdk-group-name": "internationalContractors", "x-fern-sdk-method-name": "generateOnboardingLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "intlContractorID"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "intlContractorID": { "type": "string", "description": "ID of the International Contractor" } } }, "examples": { "Request Example": { "value": { "intlContractorID": "b6bda6912c434b8295de48fe2f0f3663", "companyID": "24b5b29f0334eec3840b119c34c1358940c" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": "https://payroll.your-domain.com/intlcontractoronboarding/10983755744920193854758300657020834" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "string", "example": "https://payroll.your-domain.com/intlcontractoronboarding/10983755744920193854758300657020834" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "No contractorID in the body/query of the request", "code": 35 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "No contractorID in the body/query of the request" }, "code": { "type": "integer", "example": 35, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/internationalContractors/payment": { "post": { "summary": "Create International Contractor Payment", "description": "Create an international contractor payment record.", "operationId": "create-international-contractor-payment", "x-fern-sdk-group-name": "internationalContractors", "x-fern-sdk-method-name": "createPayment", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "intlContractorID", "pay_date", "gross_amount" ], "properties": { "companyID": { "type": "string" }, "intlContractorID": { "type": "string", "description": "ID of the International Contractor" }, "pay_date": { "type": "string", "description": "The date on which the contractor should receive the payment", "format": "date" }, "gross_amount": { "type": "number", "description": "The gross amount of the payment", "format": "double" } } }, "examples": { "Request Example": { "value": { "companyID": "789456123", "intlContractorID": "123456789", "gross_amount": "100", "pay_date": "2023-09-26" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "intlContractorPaymentID": "123456", "companyID": "789456123", "intlContractorID": "123456789", "pay_date": "2023-09-30", "gross_amount": "100", "taxes_amount": "50", "net_amount": "50" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "intlContractorPaymentID": { "type": "string", "example": "123456" }, "companyID": { "type": "string", "example": "789456123" }, "intlContractorID": { "type": "string", "example": "123456789" }, "pay_date": { "type": "string", "example": "2023-09-30" }, "gross_amount": { "type": "string", "example": "100" }, "taxes_amount": { "type": "string", "example": "50" }, "net_amount": { "type": "string", "example": "50" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Date must not be in the past", "code": 45 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Date must not be in the past" }, "code": { "type": "integer", "example": 45, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/contractors/id_upload_link": { "post": { "summary": "Create Contractor ID Verification Link", "description": "Creates a shareable link for contractors to submit their ID verification information when they receive an id_verification_required status.", "operationId": "create-id-verification-link", "x-fern-sdk-group-name": "contractors", "x-fern-sdk-method-name": "createIdVerificationLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["companyID", "contractorID", "document_type"], "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "contractorID": { "type": "string", "description": "ID of the contractor requiring ID information" }, "send_to_worker": { "type": "boolean", "description": "Whether to automatically send the verification link to the worker", "default": false }, "document_type": { "type": "array", "items": { "type": "string" }, "description": "The documents you want to collect using this link. Can include: `government_photo_id`, `passport`, `social_security_card`, and `other`" } } }, "examples": { "Request Example": { "value": { "companyID": "company_123", "contractorID": "contractor_456", "send_to_worker": false } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": "https://verification-link-url" } } }, "schema": { "type": "object", "properties": { "data": { "type": "string", "example": "https://verification-link-url" }, "success": { "type": "boolean", "example": true, "default": true }, "testMode": { "type": "boolean", "example": false, "default": true } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false, "security": [] } }, "/employees/id_upload_link": { "post": { "description": "", "operationId": "post_employeesid_upload_link", "x-fern-sdk-group-name": "employees", "x-fern-sdk-method-name": "createIdVerificationLink", "responses": { "200": { "description": "", "content": { "application/json": { "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": "https://verification-link-url" } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "companyID": { "type": "string", "description": "ID of the company" }, "employeeID": { "type": "string", "description": "ID of the employee requiring information" }, "send_to_worker": { "type": "boolean", "description": "Whether to automatically send the verification link to the worker" }, "document_type": { "type": "array", "items": { "type": "string" }, "description": "The documents you want to collect using this link. Can include: `government_photo_id`, `passport`, `social_security_card`, and `other`" } }, "type": "object", "required": ["companyID", "employeeID", "document_type"] } } } }, "security": [] } }, "/contractors/instant-pay": { "post": { "description": "", "operationId": "post_contractorsinstant-pay", "x-fern-sdk-group-name": "contractors", "x-fern-sdk-method-name": "createInstantPayEnrollmentLink", "responses": { "200": { "description": "", "content": { "application/json": { "examples": { "New Example": { "summary": "New Example", "value": "" }, "New Example 1": { "summary": "New Example 1", "value": { "data": "https://payroll.your-domain.com/contractor-information?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImMxOTgwMjY0ZmMyMjNhODkwYWZhZTgzYzkxYmQyZDQzOGVmMmFkMGRhZTc1MWZkZWEzNjYwYzNlNTU2YjEzOTYifQ", "success": true, "testMode": false } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "companyID": { "type": "string", "description": "ID of the Company" }, "contractorID": { "type": "string", "description": "ID of the Contractor" }, "send_to_worker": { "type": "string", "description": "If true, notification email will be sent to contractor" } }, "type": "object", "required": ["companyID", "contractorID"] } } } } } }, "/attributes": { "get": { "description": "", "operationId": "get_attributes", "x-fern-sdk-group-name": "attributes", "x-fern-sdk-method-name": "list", "responses": { "200": { "description": "", "content": { "application/json": { "examples": { "New Example": { "summary": "New Example", "value": { "data": [ { "companyID": "dcb3bd9403ad41c98bbc2b4d54d88a44", "attributeID": "9ecd856e-8b3c-4337-a633-0dcadf2a8fc4", "type": "options", "name": "T-shirt size", "label": "T-shirt size", "description": "", "options": [ { "value": "S", "name": "S" }, { "value": "M", "name": "M" }, { "value": "L", "name": "L" }, { "value": "XL", "name": "XL" } ], "value": "XL", "defaultValue": " " }, { "companyID": "dcb3bd9403ad41c98bbc2b4d54d88a44", "attributeID": "694eb6b0-6441-4150-88a2-5bd0fae84171", "type": "boolean", "name": "Acknowledge", "label": "Agree", "description": "", "value": "false", "defaultValue": false }, { "companyID": "dcb3bd9403ad41c98bbc2b4d54d88a44", "attributeID": "c3267432-fa46-4fd8-b9b7-9b0d53552562", "type": "string", "name": "test text", "label": "test text", "description": "", "constraints": { "minLength": 5, "maxLength": 10, "pattern": null }, "value": " ", "defaultValue": " " } ], "success": true, "testMode": false } } } } } } }, "parameters": [ { "in": "query", "name": "companyID", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "employeeID", "schema": { "type": "string" } }, { "in": "query", "name": "contractorID", "schema": { "type": "string" } } ], "security": [ { "sec0": [] } ] }, "patch": { "description": "", "operationId": "patch_attributes", "x-fern-sdk-group-name": "attributes", "x-fern-sdk-method-name": "update", "responses": { "200": { "description": "", "content": { "application/json": { "examples": { "New Example": { "summary": "New Example", "value": { "data": [ { "companyID": "6cb3b69463ad41c986bc2b6d64d68a46", "attributeID": "9ecd856e8b3c4337a6330dcadf2a8fc4", "type": "options", "name": "T-shirt size", "label": "T-shirt size", "description": "", "options": [ { "value": "S", "name": "S" }, { "value": "M", "name": "M" }, { "value": "L", "name": "L" }, { "value": "XL", "name": "XL" } ], "value": "XS", "defaultValue": " " }, { "companyID": "6cb3b69463ad41c986bc2b6d64d68a46", "attributeID": "694eb6b06441415088a25bd0fae84171", "type": "boolean", "name": "Acknowledge", "label": "Agree", "description": "", "value": "false", "defaultValue": false }, { "companyID": "6cb3b69463ad41c986bc2b6d64d68a46", "attributeID": "c3267432fa464fd8b9b79b0d53552562", "type": "string", "name": "test text", "label": "test text", "description": "", "constraints": { "minLength": 5, "maxLength": 10, "pattern": null }, "value": " ", "defaultValue": " " } ], "success": true, "testMode": false } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "companyID": { "type": "string", "description": "ID of company" }, "attributes": { "type": "array", "items": { "properties": { "attributeID": { "type": "string", "description": "ID of attribute" }, "value": { "type": "string", "description": "Set the value of this attribute for this worker" } }, "type": "object", "required": ["attributeID", "value"] } }, "employeeID": { "type": "string" }, "contractorID": { "type": "string" } }, "type": "object", "required": ["companyID", "attributes"] } } } }, "x-readme": { "samples-languages": ["shell"] }, "security": [ { "sec0": [] } ] } }, "/employeeCheck/trigger": { "post": { "description": "", "operationId": "post_employee-checktrigger", "x-fern-sdk-group-name": "employeeCheck", "x-fern-sdk-method-name": "triggerDisbursement", "responses": { "200": { "description": "", "content": { "application/json": { "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": { "employeeCheckID": "987234657", "employerCheckID": "123456789", "status": "processed", "is_salary": false, "employeeID": "0987654321", "companyID": "123456789", "check_date": "2020-01-07", "approval_required": false, "approved": false, "metadata": {}, "triggered": true, "triggered_at": "2025-03-04T23:18:09Z", "disbursement": { "method": "direct_deposit" }, "disbursement_status": "settled", "first_name": "peter", "last_name": "gregory", "reportingPeriodID": "01739fc4cfd84c2e93dba5e802d1dda1", "gross_pay": 40, "net_pay": 26.82, "total_employee_taxes": 13.18, "total_employer_taxes": 2.8, "taxes": [ { "name": "Employee Medicare Tax", "paidBy": "EMPLOYEE_WITHHOLDING", "amount": 1.16 } ], "deductions": [], "shifts": [ { "shiftID": "4712c99283304b7b989179aae36b4590", "employeeID": "1234567890", "time": "2019-12-13T04:00:00Z", "hourly": { "hours": 2, "wage": 20 }, "overtime": { "hours": 2.5, "wage": 30 } } ] } } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "employeeCheckID": { "type": "string", "description": "ID of Employee Check that you wish to disburse the net pay for" } }, "type": "object", "required": ["companyID", "employeeCheckID"] } } } } } }, "/orders": { "post": { "description": "", "operationId": "post_orders", "x-fern-sdk-group-name": "orders", "x-fern-sdk-method-name": "create", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "description": "Contains Order object" }, "testMode": { "type": "boolean" } } }, "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": { "orderID": "2133eed229b8419ba2f22dc059bd4452", "companyID": "dcb3bd9403ad41c98bbc2b4d54d88a44", "customerAccountID": "23b9ada702984edeb1496c1cb95abc8c", "businessCardID": "a3b9a22bc2184e1eb149611cb9869484", "status": "pending", "memo": "October 15 Event Staffing", "order_total": 4500, "contractor_payments": [ "fb0a4c3367b948c6b4db812d46a3fbe4", "a2f19b6dffb04a46a93988ff6dcefc2b", "4d92cfdd42234f6ea71f3d5acff52c20" ], "flat": 2000, "approval_required": true, "approved": false, "submitted_at": null, "order_link": "https://app.zeal.com/orders/2133eed229b8419ba2f22dc059bd4452", "payment_receipt": null }, "testMode": false } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "ID of company" }, "customerAccountID": { "type": "string", "description": "ID of Customer Account" }, "contractor_payments": { "type": "array", "items": { "type": "string" }, "description": "Array of Contractor Payment IDs" }, "flat": { "type": "number", "format": "float", "description": "A flat dollar amount to include in the Order" }, "approval_required": { "type": "boolean", "description": "Whether an approval is required" }, "approved": { "type": "boolean", "description": "Whether this order is approved" }, "memo": { "type": "string", "description": "Optional memo field that can be used as a descriptor field" } }, "required": ["companyID", "customerAccountID"] } } } } }, "get": { "description": "", "operationId": "post_orders-1", "x-fern-sdk-group-name": "orders", "x-fern-sdk-method-name": "list", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "description": "Contains Order objects", "items": { "properties": {}, "type": "object" } }, "testMode": { "type": "boolean" } } }, "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": [ { "orderID": "2133eed229b8419ba2f22dc059bd4452", "companyID": "dcb3bd9403ad41c98bbc2b4d54d88a44", "customerAccountID": "23b9ada702984edeb1496c1cb95abc8c", "businessCardID": "a3b9a22bc2184e1eb149611cb9869484", "status": "pending", "memo": "October 15 Event Staffing", "order_total": 4500, "contractor_payments": [ "fb0a4c3367b948c6b4db812d46a3fbe4", "a2f19b6dffb04a46a93988ff6dcefc2b", "4d92cfdd42234f6ea71f3d5acff52c20" ], "flat": 2000, "approval_required": true, "approved": false, "submitted_at": null, "order_link": "https://app.zeal.com/orders/2133eed229b8419ba2f22dc059bd4452", "payment_receipt": null } ], "testMode": false } } } } } } }, "parameters": [ { "in": "query", "name": "companyID", "schema": { "type": "string" }, "required": true, "description": "ID of company" }, { "in": "query", "name": "customerAccountID", "schema": { "type": "string" }, "description": "ID of Customer Account" }, { "in": "query", "name": "orderID", "schema": { "type": "string" }, "description": "ID of order" }, { "in": "query", "name": "status", "schema": { "type": "string" }, "description": "Status of order" } ], "summary": "Copy of " } }, "/orders/submit": { "post": { "description": "", "operationId": "post_orders-2", "x-fern-sdk-group-name": "orders", "x-fern-sdk-method-name": "submit", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "description": "Contains Order object" }, "testMode": { "type": "boolean" } } }, "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": { "orderID": "2133eed229b8419ba2f22dc059bd4452", "companyID": "dcb3bd9403ad41c98bbc2b4d54d88a44", "customerAccountID": "23b9ada702984edeb1496c1cb95abc8c", "businessCardID": "a3b9a22bc2184e1eb149611cb9869484", "status": "processing", "memo": "October 15 Event Staffing", "order_total": 4500, "contractor_payments": [ "fb0a4c3367b948c6b4db812d46a3fbe4", "a2f19b6dffb04a46a93988ff6dcefc2b", "4d92cfdd42234f6ea71f3d5acff52c20" ], "flat": 2000, "approval_required": true, "approved": true, "submitted_at": "2025-01-21T21:29:42Z", "order_link": "https://app.zeal.com/orders/2133eed229b8419ba2f22dc059bd4452", "payment_receipt": null }, "testMode": false } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "ID of company" }, "orderID": { "type": "string", "description": "ID of order to submit" } }, "required": ["companyID", "orderID"] } } } }, "summary": "Copy of " } }, "/business-cards": { "patch": { "description": "", "operationId": "post_orders-3", "x-fern-sdk-group-name": "businessCards", "x-fern-sdk-method-name": "update", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "description": "Contains business card object" }, "testMode": { "type": "boolean" } } }, "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": { "businessCardID": "3f7b912e56b84e5a8b8b5cfb7f61b1cc", "customerAccountID": "72c8f8aa0a4f4f25b3bfc3b0a0a4e4f1", "companyID": "4f3c8e7f0d4c489a92df124aef6d6578", "status": "active", "last_four": "4242", "expiration_date": "10/2027", "card_company": "VISA", "auto_charge": false }, "testMode": false } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "ID of company" }, "businessCardID": { "type": "string", "description": "ID of business card to be updated" }, "auto_charge": { "type": "boolean", "description": "Whether the card is set to be autocharged by default" } }, "required": ["companyID", "businessCardID"] } } } }, "summary": "Copy of " } }, "/service-types": { "get": { "description": "", "operationId": "get-service-types", "x-fern-sdk-group-name": "serviceTypes", "x-fern-sdk-method-name": "get", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "description": "Contains Service Type objects", "items": { "properties": {}, "type": "object" } }, "testMode": { "type": "boolean" } } }, "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": [ { "serviceTypeID": "afa75f83b5cc441fb4d42f33789b7747", "companyID": "fc235f012bae46aa8a082f357715bcfa", "customerAccountID": null, "name": "Software Engineer", "external_id": "GD-008", "description": "Full stack software development", "rate_type": "rate_based", "rate_unit": "hour", "rate_default_amount": 62.5, "bill_rate_default_amount": 108.29, "status": "active", "gl_code": "4300-ENG", "service_category": "Engineering" }, { "serviceTypeID": "b2c86g94c6dd552gc5e53g44890c8858", "companyID": "fc235f012bae46aa8a082f357715bcfa", "customerAccountID": null, "name": "Project Management", "external_id": "PM-001", "description": "Project management services", "default_amount": 500, "rate_type": "flat_fee", "bill_default_amount": 750, "status": "active", "gl_code": "4100-PM", "service_category": "Management" } ], "meta": { "next": "https://api.zeal.com/service-types?companyID=fc235f012bae46aa8a082f357715bcfa&start_at=eyJmIjoibmFtZSIsInYiOiJTb2Z0d2FyZSBFbmdpbmVlciIsImkiOiI2OTQxNzU1NzlhOTAyMDgwYjE1YWYxZWEifQ%3D%3D", "previous": null, "totalCount": 2 }, "testMode": false } } } } } } }, "parameters": [ { "in": "query", "name": "companyID", "schema": { "type": "string" }, "required": true, "description": "ID of company" }, { "in": "query", "name": "serviceTypeID", "schema": { "type": "string" }, "description": "", "required": false }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "" }, { "in": "query", "name": "start_at", "schema": { "type": "string" }, "description": "" } ], "summary": "Copy of Copy of " } }, "/contractor-deduction-templates": { "post": { "description": "", "operationId": "post_service-types-1-1", "x-fern-sdk-group-name": "contractorDeductionTemplates", "x-fern-sdk-method-name": "create", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "description": "Contains Contractor Deduction Template object" }, "testMode": { "type": "boolean" } } }, "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": { "deductionTemplateID": "48ffb95239326ca8713eadb2", "companyID": "fc235f012bae46aa8a082f357715bcfa", "contractorID": "669fe6216d9eff8ca4c9f0de", "custom_name": "Child Support - John Doe", "deduction_type": "garnishments", "deduction_credit": false, "effective_start_date": "2025-01-01", "effective_end_date": null, "external_id": null, "contractor_contribution_amount": 500, "contractor_contribution_percentage": null, "agency_name": "State Child Support Agency", "agency_address": "123 Main St, City, State 12345", "case_id": "CS-2025-001", "order_number": null } } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor with this contractorID does not exist" }, "code": { "type": "integer", "example": 73, "default": 0 } } } } } }, "examples": { "Bad Request": { "summary": "Bad Request", "value": { "success": false, "errors": [ { "message": "Contractor with this contractorID does not exist", "code": 73 } ] } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "ID of company" }, "contractorID": { "type": "string", "description": "ID of contractor" }, "custom_name": { "type": "string", "description": "Human-readable name for the deduction template" }, "deduction_type": { "type": "string", "description": "Type of deduction. `garnishment` is deprecated and will no longer be accepted after October 15, 2026. Use POST /garnishments instead.", "enum": ["garnishment", "miscellaneous"], "x-enumDescriptions": { "garnishment": "Deprecated. Use POST /garnishments instead. Sunset October 15, 2026." } }, "effective_start_date": { "type": "string", "description": "Date the template should start become effective" }, "effective_end_date": { "type": "string", "description": "Date the template should become ineffective" }, "external_id": { "type": "string", "description": "" }, "contractor_contribution_amount": { "type": "number", "description": "Default dollar amount to be contributed by the contractor for deductions", "format": "float" }, "contractor_contribution_percentage": { "type": "number", "format": "float", "description": "Default percentage of contractor's pay to be contributed by the contractor for deductions" }, "agency_name": { "type": "string", "description": "Address of the agency for a court order (Garnishment only)" }, "agency_address": { "type": "string", "description": "Name of the agency for a court order (Garnishment only)" }, "case_id": { "type": "string", "description": "Case ID of a court order (Garnishment only)" }, "order_number": { "type": "string", "description": "Order number of a court order (Garnishment only)" } }, "required": [ "companyID", "contractorID", "custom_name", "deduction_type", "effective_start_date" ] } } } }, "summary": "Create Contractor Deduction Template", "x-internal": true }, "patch": { "description": "", "operationId": "post_service-types-1-1-1", "x-fern-sdk-group-name": "contractorDeductionTemplates", "x-fern-sdk-method-name": "update", "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "description": "Contains Contractor Deduction Template object" }, "testMode": { "type": "boolean" } } }, "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": { "deductionTemplateID": "48ffb95239326ca8713eadb2", "companyID": "fc235f012bae46aa8a082f357715bcfa", "contractorID": "669fe6216d9eff8ca4c9f0de", "custom_name": "Child Support - John Doe", "deduction_type": "garnishments", "deduction_credit": false, "effective_start_date": "2025-01-01", "effective_end_date": null, "external_id": null, "contractor_contribution_amount": 500, "contractor_contribution_percentage": null, "agency_name": "State Child Support Agency", "agency_address": "123 Main St, City, State 12345", "case_id": "CS-2025-001", "order_number": null } } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor deduction template not found." }, "code": { "type": "integer", "example": 135, "default": 0 } } } } } }, "examples": { "Not Found": { "summary": "Not Found", "value": { "success": false, "errors": [ { "message": "Contractor deduction template not found.", "code": 135 } ] } } } } }, "description": "Not Found" } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deductionTemplateID": { "type": "string", "description": "ID of contractor" }, "companyID": { "type": "string", "description": "ID of company" }, "custom_name": { "type": "string", "description": "Human-readable name for the deduction template" }, "contractor_contribution_amount": { "type": "number", "description": "Default dollar amount to be contributed by the contractor for deductions", "format": "float" }, "contractor_contribution_percentage": { "type": "number", "format": "float", "description": "Default percentage of contactor's pay to be contributed by the contractor for deductions" }, "effective_start_date": { "type": "string", "description": "Date the template should start become effective" }, "effective_end_date": { "type": "string", "description": "Date the template should become ineffective" }, "agency_name": { "type": "string", "description": "Address of the agency for a court order (Garnishment only)" }, "agency_address": { "type": "string", "description": "Name of the agency for a court order (Garnishment only)" }, "case_id": { "type": "string", "description": "Case ID of a court order (Garnishment only)" }, "order_number": { "type": "string", "description": "Order number of a court order (Garnishment only)" }, "external_id": { "type": "string", "description": "" } }, "required": ["companyID", "deductionTemplateID"] } } } }, "summary": "Update Contractor Deduction Template", "x-internal": true }, "delete": { "summary": "Delete Contractor Deduction Template", "description": "", "operationId": "delete-contractor-payment-1", "x-fern-sdk-group-name": "contractorDeductionTemplates", "x-fern-sdk-method-name": "delete", "parameters": [ { "name": "companyID", "in": "query", "description": "ID of the company", "required": true, "schema": { "type": "string" } }, { "name": "deductionTemplateID", "in": "query", "description": "ID of the corresponding deduction template", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "message": "Contractor deduction template deleted." } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor Payment(s) deleted" } } } } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor deduction template not found." }, "code": { "type": "integer", "example": 135, "default": 0 } } } } } }, "examples": { "Not Found": { "summary": "Not Found", "value": { "success": false, "errors": [ { "message": "Contractor deduction template not found.", "code": 135 } ] } } } } }, "description": "Not Found" } } }, "get": { "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "OK": { "summary": "OK", "value": { "success": true, "data": [ { "deductionTemplateID": "48ffb95239326ca8713eadb2", "companyID": "fc235f012bae46aa8a082f357715bcfa", "contractorID": "669fe6216d9eff8ca4c9f0de", "custom_name": "Child Support - John Doe", "deduction_type": "garnishments", "deduction_credit": false, "effective_start_date": "2025-01-01", "effective_end_date": null, "external_id": null, "employee_contribution_amount": 500, "employee_contribution_percentage": null, "employer_contribution_amount": null, "employer_contribution_percentage": null, "agency_name": "State Child Support Agency", "agency_address": "123 Main St, City, State 12345", "case_id": "CS-2025-001", "order_number": null } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "description": "Contains a list of matching Contractor Deduction Template objects", "items": { "properties": {}, "type": "object" } }, "testMode": { "type": "boolean" } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Contractor deduction template not found." }, "code": { "type": "integer", "example": 135, "default": 0 } } } } } }, "examples": { "Not Found": { "summary": "Not Found", "value": { "success": false, "errors": [ { "message": "Contractor deduction template not found.", "code": 135 } ] } } } } }, "description": "Not Found" } }, "parameters": [ { "in": "query", "name": "companyID", "schema": { "type": "string" }, "required": true, "description": "ID of company" }, { "in": "query", "name": "contractorID", "schema": { "type": "string" }, "description": "ID of contractor" }, { "in": "query", "name": "deduction_type", "schema": { "type": "string", "enum": ["miscellaneous", "garnishment"] } } ], "summary": "Get Contractor Deduction Templates", "operationId": "get_contractor-deduction-templates", "x-fern-sdk-group-name": "contractorDeductionTemplates", "x-fern-sdk-method-name": "list" } }, "/service-type": { "post": { "description": "", "operationId": "post_service-types-1-2", "x-fern-sdk-group-name": "serviceTypes", "x-fern-sdk-method-name": "create", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "description": "Contains Payment Item object" }, "testMode": { "type": "boolean" } } }, "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": { "serviceTypeID": "afa75f83b5cc441fb4d42f33789b7747", "companyID": "fc235f012bae46aa8a082f357715bcfa", "customerAccountID": null, "name": "Software Engineer", "external_id": "GD-008", "description": "Full stack software development", "rate_type": "rate_based", "rate_unit": "hour", "rate_default_amount": 62.5, "bill_rate_default_amount": 108.29, "status": "active", "gl_code": "4300-ENG", "service_category": "Engineering" }, "testMode": false } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "ID of company" }, "name": { "type": "string", "description": "" }, "rate_type": { "type": "string", "description": "", "enum": ["flat_fee", "rate_based"] }, "default_amount": { "type": "number", "description": "Required only if `rate_type` is `flat_fee`", "format": "float" }, "rate_unit": { "type": "string", "description": "Required only if `rate_type` is `rate_based`", "enum": ["hour", "project", "piece"] }, "rate_default_amount": { "type": "number", "description": "Required only if `rate_type` is `rate_based`", "format": "float" }, "customerAccountID": { "type": "string", "description": "" }, "description": { "type": "string", "description": "" }, "external_id": { "type": "string", "description": "" }, "gl_code": { "type": "string", "description": "" }, "service_category": { "type": "string" }, "bill_rate_default_amount": { "type": "string", "description": "Applicable only if `rate_type` is `rate_based`" }, "bill_default_amount": { "type": "string", "description": "Required only if `rate_type` is `flat_fee`" } }, "required": ["companyID", "name", "rate_type"] } } } }, "summary": "Copy of Copy of Copy of " } }, "/payment-items": { "post": { "description": "", "operationId": "post_service-types-1", "x-fern-sdk-group-name": "paymentItems", "x-fern-sdk-method-name": "create", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "description": "Contains Payment Item object" }, "testMode": { "type": "boolean" } } }, "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": { "paymentItemID": "0083fb3bae9d4915adc133c6d6548f89", "companyID": "fc235f012bae46aa8a082f357715bcfa", "contractorID": "669fe6216d9eff8ca4c9f0de", "contractorPaymentID": "68ffb95239326ca8713eadb1", "work_info": { "work_description": "Construction development work", "service_date": "2025-10-15T00:00:00.000Z" }, "payment_type": "hourly", "quantity": 25, "rate": 100, "bill_rate": 175, "metadata": { "jobID": "19834673", "description": "Piecework pay" } }, "testMode": false } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "ID of company" }, "contractorID": { "type": "string", "description": "ID of contractor" }, "contractorPaymentID": { "type": "string", "description": "ID of contractor payment that this payment item will be added to" }, "work_info": { "type": "object", "description": "", "properties": { "work_description": { "type": "string", "description": "Custom description of payment item" }, "service_date": { "type": "string", "description": "Datetime (ISO 8601) of when service was completed" } } }, "earning_type": { "type": "string", "description": "", "enum": [ "hourly", "per_unit", "flat_fee", "expense_reimbursement", "bonus" ] }, "quantity": { "type": "number", "description": "Only required if `earning_type` is `hourly` or `per_unit`", "format": "float" }, "rate": { "type": "number", "description": "Only applicable if `earning_type` is `hourly` or `per_unit`", "format": "float" }, "bill_rate": { "type": "number", "description": "Only applicable if `earning_type` is `hourly` or `per_unit`", "format": "float" }, "gross_amount": { "type": "number", "format": "float", "description": "Only applicable if `earning_type` is `flat_fee`, `expense_reimbursement`, or `bonus`" }, "bill_amount": { "type": "number", "description": "Only applicable if `earning_type` is `flat_fee`, `expense_reimbursement`, or `bonus`", "format": "float" }, "metadata": { "type": "object", "description": "Custom object you can attach to the payment item. Useful for storing additional information in a custom, structured format. Zeal does not use this object. Do not store sensitive information. Posting `metadata` replaces the whole object.", "additionalProperties": true } }, "required": ["companyID", "contractorID", "contractorPaymentID"] } } } }, "summary": "Create Payment Item" }, "get": { "summary": "Get Payment Items", "description": "Retrieve a payment item by paymentItemID, or list payment items for the authenticated company.", "operationId": "get-payment-items", "parameters": [ { "name": "paymentItemID", "in": "query", "required": false, "description": "ID of the payment item to retrieve. When present, the endpoint returns that single payment item and list filters are ignored.", "schema": { "type": "string" } }, { "name": "contractorID", "in": "query", "required": false, "description": "When listing payment items (omit `paymentItemID`), filter to this contractor. Ignored when `paymentItemID` is present.", "schema": { "type": "string" } }, { "name": "contractorPaymentID", "in": "query", "required": false, "description": "When listing payment items (omit `paymentItemID`), filter to this contractor payment. Ignored when `paymentItemID` is present.", "schema": { "type": "string" } }, { "name": "serviceTypeID", "in": "query", "required": false, "description": "When listing payment items (omit `paymentItemID`), filter to items whose `work_info.serviceTypeID` matches this value. Ignored when `paymentItemID` is present.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of payment items returned per page. Minimum 1, maximum 100. Defaults to 25. Ignored when `paymentItemID` is present.", "schema": { "type": "number", "minimum": 1, "maximum": 100 } }, { "name": "start_at", "in": "query", "required": false, "description": "The pagination cursor to start at. Ignored when `paymentItemID` is present.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Field to sort by when listing. Defaults to `_id`. Ignored when `paymentItemID` is present.", "schema": { "type": "string" } }, { "name": "sort_direction", "in": "query", "required": false, "description": "Sort direction when listing. Defaults to `desc`. Ignored when `paymentItemID` is present.", "schema": { "type": "string", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "testMode": { "type": "boolean" }, "data": { "description": "A Payment Item object, or an array of Payment Item objects when listing" }, "meta": { "type": "object", "description": "Present when listing (`paymentItemID` omitted). Contains `next`, `previous`, and `totalCount`." } } }, "examples": { "Retrieve one payment item": { "summary": "Retrieve one payment item", "value": { "success": true, "testMode": false, "data": { "paymentItemID": "0083fb3bae9d4915adc133c6d6548f89", "companyID": "fc235f012bae46aa8a082f357715bcfa", "contractorID": "669fe6216d9eff8ca4c9f0de", "contractorPaymentID": "68ffb95239326ca8713eadb1", "work_info": { "work_description": "Construction development work", "service_date": "2025-10-15T00:00:00.000Z" }, "earning_type": "hourly", "category": "regular", "quantity": 25, "rate": 100, "rate_unit": "hour", "bill_rate": 175, "metadata": { "jobID": "19834673", "description": "Piecework pay" } } } }, "List payment items": { "summary": "List payment items", "value": { "success": true, "testMode": false, "data": [ { "paymentItemID": "0083fb3bae9d4915adc133c6d6548f89", "companyID": "fc235f012bae46aa8a082f357715bcfa", "contractorID": "669fe6216d9eff8ca4c9f0de", "contractorPaymentID": "68ffb95239326ca8713eadb1", "work_info": { "work_description": "Construction development work", "service_date": "2025-10-15T00:00:00.000Z" }, "earning_type": "hourly", "category": "regular", "quantity": 25, "rate": 100, "rate_unit": "hour", "bill_rate": 175, "metadata": { "jobID": "19834673", "description": "Piecework pay" } } ], "meta": { "next": null, "previous": null, "totalCount": 1 } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } }, "examples": { "Not Found": { "summary": "Not Found", "value": { "success": false, "errors": [ { "message": "Payment item not found", "code": 135 } ] } } } } } } } }, "patch": { "description": "", "operationId": "post_service-types-1-3", "x-fern-sdk-group-name": "paymentItems", "x-fern-sdk-method-name": "update", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "description": "Contains Payment Item object" }, "testMode": { "type": "boolean" } } }, "examples": { "New Example": { "summary": "New Example", "value": { "success": true, "data": { "paymentItemID": "0083fb3bae9d4915adc133c6d6548f89", "companyID": "fc235f012bae46aa8a082f357715bcfa", "contractorID": "669fe6216d9eff8ca4c9f0de", "contractorPaymentID": "68ffb95239326ca8713eadb1", "work_info": { "work_description": "Construction development work", "service_date": "2025-10-15T00:00:00.000Z" }, "payment_type": "hourly", "quantity": 25, "rate": 100, "bill_rate": 175, "metadata": { "jobID": "19834673", "description": "Piecework pay" } }, "testMode": false } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "ID of company" }, "paymentItemID": { "type": "string", "description": "ID of payment item" }, "contractorPaymentID": { "type": "string", "description": "ID of contractor payment that this payment item will be added to" }, "work_info": { "type": "object", "description": "", "properties": { "work_description": { "type": "string", "description": "Custom description of payment item" }, "service_date": { "type": "string", "description": "Datetime (ISO 8601) of when service was completed" } } }, "earning_type": { "type": "string", "description": "**Note: `earning_type` cannot be changed from rate-based to fixed amount or vice versa.**", "enum": [ "hourly", "per_unit", "flat_fee", "expense_reimbursement", "bonus" ] }, "quantity": { "type": "number", "description": "Only required if `earning_type` is `hourly` or `per_unit`", "format": "float" }, "rate": { "type": "number", "description": "Only required if `earning_type` is `hourly` or `per_unit`", "format": "float" }, "bill_rate": { "type": "number", "description": "Only applicable if `earning_type` is `hourly` or `per_unit`", "format": "float" }, "gross_amount": { "type": "number", "format": "float", "description": "Only required if `earning_type` is `flat_fee`, `expense_reimbursement`, or `bonus`" }, "bill_amount": { "type": "string", "description": "Only applicable if `earning_type` is `flat_fee`, `expense_reimbursement`, or `bonus`" }, "metadata": { "type": "object", "description": "Custom object you can attach to the payment item. Useful for storing additional information in a custom, structured format. Zeal does not use this object. Do not store sensitive information. Posting `metadata` replaces the whole object.", "additionalProperties": true } }, "required": ["companyID", "paymentItemID"] } } } }, "summary": "Update Payment Item" }, "delete": { "summary": "Delete Payment Item", "description": "Delete a payment item by paymentItemID. The parent contractor payment must have status pending.", "operationId": "delete-payment-item", "parameters": [ { "name": "paymentItemID", "in": "query", "required": true, "description": "ID of the payment item to delete", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Payment item deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "testMode": { "type": "boolean" } } }, "examples": { "Result": { "summary": "Result", "value": { "success": true, "testMode": false } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } }, "examples": { "Bad Request": { "summary": "Bad Request", "value": { "success": false, "errors": [ { "message": "Payment item cannot be deleted when contractor payment status is processed. Only pending payments can be modified.", "code": 13 } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } }, "examples": { "Not Found": { "summary": "Not Found", "value": { "success": false, "errors": [ { "message": "Payment item not found", "code": 135 } ] } } } } } } } } }, "/paymentLink": { "get": { "summary": "Get Contractor Payment Link", "description": "Fetches an expirable link that displays an employee paystub.", "operationId": "get-paystub-link-1", "x-fern-sdk-group-name": "paymentLink", "x-fern-sdk-method-name": "get", "parameters": [ { "name": "companyID", "in": "query", "description": "Company ID of employer", "required": true, "schema": { "type": "string" } }, { "name": "contractorPaymentID", "in": "query", "description": "ID of Contractor Payment", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "allow_retry", "schema": { "type": "boolean", "default": "false" }, "description": "Boolean flag to allow the worker to retry a returned transaction on this contractor payment" } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": "https://payroll.yourdomain.com/payment?accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC..." } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "string", "example": "https://payroll.yourdomain.com/public/paystub/" } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Employee Check with this ID does not exist", "code": 17 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "default": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Employee Check with this ID does not exist" }, "code": { "type": "integer", "example": 17, "default": 0 } } } } } } } } } }, "deprecated": false } }, "/contractors/setOnboardedStatusToTrue": { "post": { "description": "Set onboarded status to true if the contractor has all legally required information.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contractorID": { "type": "string", "description": "ID of the Contractor being updated" }, "companyID": { "type": "string", "description": "ID of the Employer that the Contractor belongs to" } }, "required": ["contractorID", "companyID"] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "Onboarded Contractor Object" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "contractors", "x-fern-sdk-method-name": "setOnboardedStatusToTrue" } }, "/reports/kyc-summary": { "post": { "description": "Create a report containing KYC flagged workers by company.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "ID of the Company" }, "employment_status": { "type": "string", "description": "Filters the report by workers' employment status", "enum": ["live", "leave", "terminated"] }, "kyc_status": { "type": "string", "description": "Filters the report by KYC status", "enum": ["all", "failed", "approved"] }, "media_type": { "type": "string", "description": "The media type of the report", "default": "csv" } }, "required": ["companyID", "employment_status", "media_type"] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "job_id for the KYC Summary Report" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "reports", "x-fern-sdk-method-name": "createKycSummary" } }, "/employee-deduction-templates": { "post": { "description": "Creates a new deduction template for an employee.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "ID of the company related to this template" }, "employeeID": { "type": "string", "description": "ID of the employee related to this template" }, "custom_name": { "type": "string", "description": "Human-readable name for the deduction template" }, "deduction_type": { "type": "string", "description": "Type of deduction. `garnishment` is deprecated and will no longer be accepted after October 15, 2026. Use POST /garnishments instead.", "enum": [ "401k", "403b", "dependent_care_benefit", "employer_sponsored_health_coverage", "garnishment", "hsa", "miscellaneous", "roth_401k", "roth_ira", "section_125", "simple_ira" ], "x-enumDescriptions": { "garnishment": "Deprecated. Use POST /garnishments instead. Sunset October 15, 2026." } }, "effective_start_date": { "type": "string", "description": "Date the template should start becoming effective", "format": "date" }, "effective_end_date": { "type": "string", "description": "Date the template should become ineffective", "format": "date" }, "employee_contribution_amount": { "type": "number", "description": "Default dollar amount contributed by the employee for deductions" }, "employee_contribution_percentage": { "type": "number", "description": "Default percentage of employee's pay contributed by the employee for deductions" }, "employer_contribution_amount": { "type": "number", "description": "Default dollar amount contributed by the employer for deductions" }, "employer_contribution_percentage": { "type": "number", "description": "Default percentage of employee's pay contributed by the employer for deductions" }, "hsa_type": { "type": "string", "description": "Contribution limit type for the template (HSA only)", "enum": ["family", "individual"] }, "agency_address": { "type": "string", "description": "Name of the agency for a court order (Garnishment only)" }, "agency_name": { "type": "string", "description": "Address of the agency for a court order (Garnishment only)" }, "case_id": { "type": "string", "description": "Case ID of a court order (Garnishment only)" }, "order_number": { "type": "string", "description": "Order number of a court order (Garnishment only)" }, "external_id": { "type": "string", "description": "ID in an external system related to the template" } }, "required": [ "companyID", "employeeID", "custom_name", "deduction_type", "effective_start_date" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "The created Employee Deduction Template object" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "employeeDeductionTemplates", "x-fern-sdk-method-name": "create" }, "get": { "description": "Returns a paginated array of Employee Deduction Template objects matching the supplied filters.", "parameters": [ { "name": "limit", "in": "query", "description": "The number of deduction templates returned per page", "required": false, "schema": { "type": "number" } }, { "name": "start_at", "in": "query", "description": "The deductionTemplateID of the template to start the paginated results on", "required": false, "schema": { "type": "string" } }, { "name": "companyID", "in": "query", "description": "Matches all templates under the company with this ID", "required": false, "schema": { "type": "string" } }, { "name": "employeeID", "in": "query", "description": "Matches all templates under the employee with this ID", "required": false, "schema": { "type": "string" } }, { "name": "agency_address", "in": "query", "description": "Matches templates with this agency address", "required": false, "schema": { "type": "string" } }, { "name": "agency_name", "in": "query", "description": "Matches templates with this agency name", "required": false, "schema": { "type": "string" } }, { "name": "case_id", "in": "query", "description": "Matches templates with this case ID", "required": false, "schema": { "type": "string" } }, { "name": "custom_name", "in": "query", "description": "Matches templates with this custom name", "required": false, "schema": { "type": "string" } }, { "name": "deduction_type", "in": "query", "description": "Matches templates with this deduction type", "required": false, "schema": { "type": "string" } }, { "name": "effective_start_date", "in": "query", "description": "Matches templates with this effective start date", "required": false, "schema": { "type": "string" } }, { "name": "effective_end_date", "in": "query", "description": "Matches templates with this effective end date", "required": false, "schema": { "type": "string" } }, { "name": "employee_contribution_amount", "in": "query", "description": "Matches templates with this employee contribution amount", "required": false, "schema": { "type": "number" } }, { "name": "employee_contribution_percentage", "in": "query", "description": "Matches templates with this employee contribution percentage", "required": false, "schema": { "type": "number" } }, { "name": "employer_contribution_amount", "in": "query", "description": "Matches templates with this employer contribution amount", "required": false, "schema": { "type": "number" } }, { "name": "employer_contribution_percentage", "in": "query", "description": "Matches templates with this employer contribution percentage", "required": false, "schema": { "type": "number" } }, { "name": "external_id", "in": "query", "description": "Matches templates with this external ID", "required": false, "schema": { "type": "string" } }, { "name": "hsa_type", "in": "query", "description": "Matches templates with this HSA contribution type", "required": false, "schema": { "type": "string" } }, { "name": "order_number", "in": "query", "description": "Matches templates with this order number", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "description": "Array of Employee Deduction Template objects" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "employeeDeductionTemplates", "x-fern-sdk-method-name": "list" } }, "/employee-deduction-templates/{deductionTemplateID}": { "get": { "description": "Returns a single Employee Deduction Template object identified by its deductionTemplateID.", "parameters": [ { "name": "deductionTemplateID", "in": "path", "description": "ID of this template", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "The Employee Deduction Template object" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "employeeDeductionTemplates", "x-fern-sdk-method-name": "get" }, "patch": { "description": "Updates an existing Employee Deduction Template.", "parameters": [ { "name": "deductionTemplateID", "in": "path", "description": "ID of this template", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deductionTemplateID": { "type": "string", "description": "ID of the template to update" }, "custom_name": { "type": "string", "description": "Human-readable name for the deduction template" }, "effective_start_date": { "type": "string", "description": "Date the template should start become effective", "format": "date" }, "effective_end_date": { "type": "string", "description": "Date the template should become ineffective", "format": "date" }, "employee_contribution_amount": { "type": "number", "description": "Default dollar amount to be contributed by the employee for deductions" }, "employee_contribution_percentage": { "type": "number", "description": "Default percentage of employee's pay to be contributed by the employee for deductions" }, "employer_contribution_amount": { "type": "number", "description": "Default dollar amount to be contributed by the employer for deductions" }, "employer_contribution_percentage": { "type": "number", "description": "Default percentage of employee's pay to be contributed by the employer for deductions" }, "hsa_type": { "type": "string", "description": "Contribution limit type for the template (HSA only)", "enum": ["family", "individual"] }, "agency_address": { "type": "string", "description": "Name of the agency for a court order (Garnishment only)" }, "agency_name": { "type": "string", "description": "Address of the agency for a court order (Garnishment only)" }, "case_id": { "type": "string", "description": "Case ID of a court order (Garnishment only)" }, "order_number": { "type": "string", "description": "Order number of a court order (Garnishment only)" }, "external_id": { "type": "string", "description": "ID in an external system related to the template" } }, "required": [] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "The updated Employee Deduction Template object" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "employeeDeductionTemplates", "x-fern-sdk-method-name": "update" }, "delete": { "description": "Deletes an existing Employee Deduction Template identified by its deductionTemplateID.", "parameters": [ { "name": "deductionTemplateID", "in": "path", "description": "ID of this template", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "employeeDeductionTemplates", "x-fern-sdk-method-name": "delete" } }, "/paperwork/templates": { "post": { "description": "Gets one or more Paperwork Template(s) by companyID or various filters.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "Unique identifier for Zeal company" }, "paperwork_type": { "type": "string", "description": "Type of paperwork form", "enum": ["W4", "I9", "W9", "CustomPaperwork"] }, "worker_type": { "type": "string", "description": "Type of worker the form is applicable to", "enum": ["Employee", "Contractor", "All"] }, "jurisdictions": { "type": "object", "description": "Filter for jurisdictions where the form is applicable" }, "effective_date": { "type": "string", "description": "Effective date for template retrieval", "format": "date" }, "archive_date": { "type": "string", "description": "Archive date for template retrieval", "format": "date" } }, "required": ["companyID"] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "description": "Filtered array of Paperwork Template object(s)" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "paperwork", "x-fern-sdk-method-name": "createTemplates" } }, "/paperwork/templates/{templateID}": { "get": { "description": "Fetches a specified Paperwork Template by templateID.", "parameters": [ { "name": "templateID", "in": "path", "description": "Unique identifier for the paperwork template", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "Fetched Paperwork Template object" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "paperwork", "x-fern-sdk-method-name": "getTemplates" } }, "/paperwork/submissions": { "post": { "description": "Gets one or more Paperwork Submission(s) by companyID or various filters.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyID": { "type": "string", "description": "Unique identifier for the company" }, "jurisdiction_filter": { "type": "object", "description": "Filter for jurisdictions to include or exclude" }, "worker_filter": { "type": "object", "description": "Filter for workers to include or exclude" } }, "required": ["companyID"] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "description": "Filtered array of Paperwork Submission object(s)" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "paperwork", "x-fern-sdk-method-name": "createSubmissions" }, "put": { "description": "Create a Paperwork Submission(s) for an employee or contractor from a Paperwork Template.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "templateID": { "type": "string", "description": "Unique identifier for the paperwork template" }, "worker_type": { "type": "string", "description": "Type of worker (Employee or Contractor)", "enum": ["Employee", "Contractor"] }, "companyID": { "type": "string", "description": "Unique identifier for the company" }, "employeeID": { "type": "string", "description": "Unique identifier for the employee. Nullable if the worker type is contractor" }, "contractorID": { "type": "string", "description": "Unique identifier for the contractor. Nullable if the worker type is employee" }, "fields": { "type": "object", "description": "Additional fields for the paperwork submission" } }, "required": ["templateID", "worker_type", "companyID", "fields"] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "Object of Paperwork Submission object(s)" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "paperwork", "x-fern-sdk-method-name": "updateSubmissions" } }, "/paperwork/submissions/{submissionID}": { "get": { "description": "Gets a specific Paperwork Submission(s) by its submissionID.", "parameters": [ { "name": "submissionID", "in": "path", "description": "Unique identifier for the paperwork submission", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "Object of Paperwork Submission object(s)" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "paperwork", "x-fern-sdk-method-name": "getSubmissions" } }, "/garnishments": { "post": { "summary": "Create Garnishment", "description": "Creates a garnishment for an employee or contractor. Provide either simple caps (cap_amount and/or cap_percentage) or an advanced withholding_schedule (not both). withholding_schedule is employee-only; contractors have no pay frequency and must use simple caps. A withholding_schedule must tile $0.00 to infinity per pay frequency with no gaps or overlaps, and at least one bracket must withhold.", "operationId": "create-garnishment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "workerID", "workerType", "garnishment_type", "effective_start_date", "agency_name", "agency_address", "case_id", "order_number" ], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "workerID": { "type": "string", "description": "Employee or contractor ID" }, "workerType": { "type": "string", "enum": ["employee", "contractor"], "description": "Whether the worker is an employee or contractor. withholding_schedule is supported for employees only." }, "garnishment_type": { "type": "string", "enum": [ "child_support", "federal_tax_levy", "state_tax_levy", "creditor", "student_loan", "other" ], "description": "Type of garnishment order" }, "priority": { "type": "integer", "minimum": 0, "description": "Optional. Prefer omitting `priority` unless you need a custom withholding order.\nWhen omitted, Zeal applies a federal-baseline default by `garnishment_type` (lower numbers are withheld first):\n`child_support`=10,\n`federal_tax_levy`=20,\n`state_tax_levy`=30,\n`student_loan`=40,\n`creditor`=50,\n`other`=60.\nDefaults are spaced by 10 so you can insert an override between two types without renumbering everything." }, "total_amount_owed": { "type": "number", "minimum": 0, "description": "Total balance owed in dollars. Omit for open-ended orders. When set, must be greater than or equal to total_amount_withheld." }, "total_amount_withheld": { "type": "number", "minimum": 0, "description": "Optional. Amount already withheld before this garnishment was created, in dollars (for example when migrating an existing order). Defaults to 0. When total_amount_owed is set, it must be greater than or equal to total_amount_withheld." }, "effective_start_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) when withholding begins" }, "effective_end_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) when withholding ends. Must be after effective_start_date." }, "agency_name": { "type": "string", "description": "Name of the collecting agency" }, "agency_address": { "type": "string", "description": "Address of the collecting agency" }, "cap_amount": { "type": "number", "minimum": 0, "description": "Per-paycheck maximum withhold amount in dollars. At least one of cap_amount, cap_percentage, or withholding_schedule is required. Mutually exclusive with withholding_schedule." }, "cap_percentage": { "type": "number", "minimum": 0, "maximum": 100, "description": "Per-paycheck maximum withhold percentage (0-100). At least one of cap_amount, cap_percentage, or withholding_schedule is required. Mutually exclusive with withholding_schedule." }, "garnishment_state": { "type": "string", "description": "US state code (2-letter) associated with the order" }, "case_id": { "type": "string", "description": "Court/agency case identifier" }, "order_number": { "type": "string", "description": "Court/agency order number" }, "custom_name": { "type": "string", "description": "Optional display name for this garnishment" }, "external_id": { "type": "string", "description": "Optional external identifier for your own systems" }, "withholding_schedule": { "$ref": "#/components/schemas/WithholdingSchedule" } } }, "examples": { "Simple caps": { "value": { "companyID": "1eeec343485723ee58afef12", "workerID": "674759a85785745748e3847a", "workerType": "contractor", "garnishment_type": "creditor", "effective_start_date": "2025-01-01", "agency_name": "Acme Agency", "agency_address": "123 Court St", "case_id": "CASE-1", "order_number": "ORD-1", "cap_percentage": 25, "total_amount_owed": 500, "total_amount_withheld": 0 } }, "Withholding schedule (fixed amount per pay frequency)": { "summary": "Fixed amount per pay frequency", "value": { "companyID": "1eeec343485723ee58afef12", "workerID": "674759a85785745748e3847a", "workerType": "employee", "garnishment_type": "child_support", "effective_start_date": "2025-01-01", "agency_name": "State Disbursement Unit", "agency_address": "5500 S Eastern Ave, Commerce CA 90040", "case_id": "200000002611596", "order_number": "23CWCS16629", "withholding_schedule": [ { "frequency": "weekly", "brackets": [ { "min": 0, "max": null, "action": { "kind": "amount", "amount": 216.34 } } ] }, { "frequency": "biweekly", "brackets": [ { "min": 0, "max": null, "action": { "kind": "amount", "amount": 432.69 } } ] }, { "frequency": "monthly", "brackets": [ { "min": 0, "max": null, "action": { "kind": "amount", "amount": 937.5 } } ] } ] } }, "Withholding schedule": { "summary": "Advanced withholding schedule", "value": { "companyID": "1eeec343485723ee58afef12", "workerID": "674759a85785745748e3847a", "workerType": "employee", "garnishment_type": "creditor", "effective_start_date": "2025-01-01", "agency_name": "Acme Agency", "agency_address": "123 Court St", "case_id": "CASE-1", "order_number": "ORD-1", "withholding_schedule": [ { "frequency": "weekly", "brackets": [ { "min": 0, "max": 217.5, "action": { "kind": "exempt" } }, { "min": 217.51, "max": 290, "action": { "kind": "excess_over_floor", "floor": 217.5 } }, { "min": 290.01, "max": null, "action": { "kind": "percentage", "percentage": 25 } } ] }, { "frequency": "monthly", "brackets": [ { "min": 0, "max": null, "action": { "kind": "amount", "amount": 937.5 } } ] } ], "total_amount_owed": 500, "total_amount_withheld": 0 } } } } } }, "responses": { "201": { "description": "201", "content": { "application/json": { "examples": { "Simple caps": { "value": { "success": true, "data": { "garnishmentID": "3cab1c18d38a45e7a688aceeb4fcfcaa", "companyID": "1eeec343485723ee58afef12", "workerID": "674759a85785745748e3847a", "workerType": "contractor", "garnishment_type": "creditor", "priority": 50, "total_amount_owed": 500, "total_amount_withheld": 0, "status": "active", "effective_start_date": "2025-01-01", "agency_name": "Acme Agency", "agency_address": "123 Court St", "cap_percentage": 25, "case_id": "CASE-1", "order_number": "ORD-1", "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z" } } }, "Withholding schedule": { "summary": "Advanced withholding schedule", "value": { "success": true, "data": { "garnishmentID": "3cab1c18d38a45e7a688aceeb4fcfcaa", "companyID": "1eeec343485723ee58afef12", "workerID": "674759a85785745748e3847a", "workerType": "employee", "garnishment_type": "creditor", "priority": 50, "total_amount_owed": 500, "total_amount_withheld": 0, "status": "active", "effective_start_date": "2025-01-01", "agency_name": "Acme Agency", "agency_address": "123 Court St", "withholding_schedule": [ { "frequency": "weekly", "brackets": [ { "min": 0, "max": 217.5, "action": { "kind": "exempt" } }, { "min": 217.51, "max": 290, "action": { "kind": "excess_over_floor", "floor": 217.5 } }, { "min": 290.01, "max": null, "action": { "kind": "percentage", "percentage": 25 } } ] }, { "frequency": "monthly", "brackets": [ { "min": 0, "max": null, "action": { "kind": "amount", "amount": 937.5 } } ] } ], "case_id": "CASE-1", "order_number": "ORD-1", "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "garnishmentID": { "type": "string", "description": "Unique identifier for this garnishment", "example": "3cab1c18d38a45e7a688aceeb4fcfcaa" }, "companyID": { "type": "string", "description": "Company ID of employer", "example": "1eeec343485723ee58afef12" }, "workerID": { "type": "string", "description": "Employee or contractor ID this garnishment applies to", "example": "674759a85785745748e3847a" }, "workerType": { "type": "string", "enum": ["employee", "contractor"], "description": "Whether the worker is an employee or contractor", "example": "contractor" }, "garnishment_type": { "type": "string", "enum": [ "child_support", "federal_tax_levy", "state_tax_levy", "creditor", "student_loan", "other" ], "description": "Type of garnishment order", "example": "creditor" }, "priority": { "type": "integer", "description": "Effective withholding priority. Lower numbers are withheld first. When omitted on create, Zeal applies a type-based default (child_support=10, federal_tax_levy=20, state_tax_levy=30, student_loan=40, creditor=50, other=60).", "example": 50 }, "total_amount_owed": { "type": "number", "description": "Total balance owed in dollars. Omit for open-ended / forever orders.", "example": 500 }, "total_amount_withheld": { "type": "number", "description": "Total amount withheld to date in dollars", "example": 0 }, "status": { "type": "string", "enum": [ "active", "satisfied", "modified", "vacated", "canceled" ], "description": "Lifecycle status of the garnishment", "example": "active" }, "effective_start_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) when withholding begins", "example": "2025-01-01" }, "effective_end_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) when withholding ends. Omit for open-ended orders.", "example": "2025-12-31" }, "agency_name": { "type": "string", "description": "Name of the collecting agency", "example": "Acme Agency" }, "agency_address": { "type": "string", "description": "Address of the collecting agency", "example": "123 Court St" }, "cap_amount": { "type": "number", "description": "Per-paycheck maximum withhold amount in dollars. At least one of cap_amount or cap_percentage is required on create.", "example": 150 }, "cap_percentage": { "type": "number", "description": "Per-paycheck maximum withhold percentage of disposable earnings (0-100). At least one of cap_amount or cap_percentage is required on create.", "example": 25 }, "garnishment_state": { "type": "string", "description": "US state code (2-letter) associated with the order", "example": "CA" }, "case_id": { "type": "string", "description": "Court/agency case identifier", "example": "CASE-1" }, "order_number": { "type": "string", "description": "Court/agency order number", "example": "ORD-1" }, "custom_name": { "type": "string", "description": "Optional display name for this garnishment", "example": "Acme creditor" }, "external_id": { "type": "string", "description": "Optional external identifier for your own systems", "example": "ext-create-1" }, "previous_garnishmentID": { "type": "string", "description": "ID of the garnishment this record supersedes. Present when this garnishment was created via a modify (status: modified) transition; omitted otherwise.", "example": "2bab1c18d38a45e7a688aceeb4fcfcbb" }, "canceled_reason": { "type": "string", "description": "Reason provided when status is canceled" }, "satisfied_at": { "type": "string", "description": "ISO timestamp when the garnishment was fully satisfied" }, "created_at": { "type": "string", "description": "ISO timestamp when the garnishment was created", "example": "2025-01-01T00:00:00.000Z" }, "updated_at": { "type": "string", "description": "ISO timestamp when the garnishment was last updated", "example": "2025-01-01T00:00:00.000Z" }, "withholding_schedule": { "$ref": "#/components/schemas/WithholdingSchedule" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "cap_amount or cap_percentage must be provided.", "code": 0 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "example": 0 } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "garnishments", "x-fern-sdk-method-name": "create" }, "get": { "summary": "Get Garnishments", "description": "Returns a cursor-paginated list of garnishments for a company.", "operationId": "list-garnishments", "parameters": [ { "name": "companyID", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Company ID of employer" }, { "name": "workerID", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by worker ID. Must be provided together with workerType." }, { "name": "workerType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["employee", "contractor"] }, "description": "Filter by worker type. Must be provided together with workerID." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["active", "satisfied", "modified", "vacated", "canceled"] }, "description": "Filter by garnishment status" }, { "name": "garnishment_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by garnishment type. Accepts a single value or a comma-separated list." }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by external ID" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search across worker name, worker ID, garnishment ID, case ID, order number, and agency" }, { "name": "effective_start_date_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Inclusive lower bound for effective_start_date (YYYY-MM-DD)" }, { "name": "effective_start_date_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Inclusive upper bound for effective_start_date (YYYY-MM-DD)" }, { "name": "effective_end_date_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Inclusive lower bound for effective_end_date (YYYY-MM-DD)" }, { "name": "effective_end_date_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Inclusive upper bound for effective_end_date (YYYY-MM-DD)" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "priority", "created_at", "total_amount_owed", "effective_start_date", "effective_end_date" ] }, "description": "Field to sort by" }, { "name": "sort_direction", "in": "query", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] }, "description": "Sort direction" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Page size (1-100). Defaults to 25." }, { "name": "start_at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor for pagination" } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": [ { "garnishmentID": "3cab1c18d38a45e7a688aceeb4fcfcaa", "companyID": "1eeec343485723ee58afef12", "workerID": "674759a85785745748e3847a", "workerType": "contractor", "garnishment_type": "creditor", "priority": 50, "total_amount_owed": 500, "total_amount_withheld": 0, "status": "active", "effective_start_date": "2025-01-01", "agency_name": "Acme Agency", "agency_address": "123 Court St", "cap_percentage": 25, "case_id": "CASE-1", "order_number": "ORD-1", "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z" } ], "meta": { "next": null, "previous": null, "totalCount": 1 } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "garnishmentID": { "type": "string", "description": "Unique identifier for this garnishment", "example": "3cab1c18d38a45e7a688aceeb4fcfcaa" }, "companyID": { "type": "string", "description": "Company ID of employer", "example": "1eeec343485723ee58afef12" }, "workerID": { "type": "string", "description": "Employee or contractor ID this garnishment applies to", "example": "674759a85785745748e3847a" }, "workerType": { "type": "string", "enum": ["employee", "contractor"], "description": "Whether the worker is an employee or contractor", "example": "contractor" }, "garnishment_type": { "type": "string", "enum": [ "child_support", "federal_tax_levy", "state_tax_levy", "creditor", "student_loan", "other" ], "description": "Type of garnishment order", "example": "creditor" }, "priority": { "type": "integer", "description": "Withholding priority. Lower numbers are withheld first. When omitted on create, Zeal applies a type-based default.", "example": 50 }, "total_amount_owed": { "type": "number", "description": "Total balance owed in dollars. Omit for open-ended / forever orders.", "example": 500 }, "total_amount_withheld": { "type": "number", "description": "Total amount withheld to date in dollars", "example": 0 }, "status": { "type": "string", "enum": [ "active", "satisfied", "modified", "vacated", "canceled" ], "description": "Lifecycle status of the garnishment", "example": "active" }, "effective_start_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) when withholding begins", "example": "2025-01-01" }, "effective_end_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) when withholding ends. Omit for open-ended orders.", "example": "2025-12-31" }, "agency_name": { "type": "string", "description": "Name of the collecting agency", "example": "Acme Agency" }, "agency_address": { "type": "string", "description": "Address of the collecting agency", "example": "123 Court St" }, "cap_amount": { "type": "number", "description": "Per-paycheck maximum withhold amount in dollars. At least one of cap_amount or cap_percentage is required on create.", "example": 150 }, "cap_percentage": { "type": "number", "description": "Per-paycheck maximum withhold percentage of disposable earnings (0-100). At least one of cap_amount or cap_percentage is required on create.", "example": 25 }, "garnishment_state": { "type": "string", "description": "US state code (2-letter) associated with the order", "example": "CA" }, "case_id": { "type": "string", "description": "Court/agency case identifier", "example": "CASE-1" }, "order_number": { "type": "string", "description": "Court/agency order number", "example": "ORD-1" }, "custom_name": { "type": "string", "description": "Optional display name for this garnishment", "example": "Acme creditor" }, "external_id": { "type": "string", "description": "Optional external identifier for your own systems", "example": "ext-create-1" }, "previous_garnishmentID": { "type": "string", "description": "ID of the garnishment this record supersedes. Present when this garnishment was created via a modify (status: modified) transition; omitted otherwise.", "example": "2bab1c18d38a45e7a688aceeb4fcfcbb" }, "canceled_reason": { "type": "string", "description": "Reason provided when status is canceled" }, "satisfied_at": { "type": "string", "description": "ISO timestamp when the garnishment was fully satisfied" }, "created_at": { "type": "string", "description": "ISO timestamp when the garnishment was created", "example": "2025-01-01T00:00:00.000Z" }, "updated_at": { "type": "string", "description": "ISO timestamp when the garnishment was last updated", "example": "2025-01-01T00:00:00.000Z" }, "withholding_schedule": { "$ref": "#/components/schemas/WithholdingSchedule" } } } }, "meta": { "type": "object", "properties": { "next": { "type": "string", "nullable": true, "description": "URL for the next page, or null" }, "previous": { "type": "string", "nullable": true, "description": "URL for the previous page, or null" }, "totalCount": { "type": "integer", "description": "Total number of matching garnishments" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "workerID and workerType must be provided together.", "code": 0 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "example": 0 } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "garnishments", "x-fern-sdk-method-name": "list" } }, "/garnishments/{garnishmentID}": { "get": { "summary": "Get Garnishment", "description": "Fetch a single garnishment by ID.", "operationId": "get-garnishment", "parameters": [ { "name": "garnishmentID", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Garnishment ID" }, { "name": "companyID", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Company ID of employer" } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "success": true, "data": { "garnishmentID": "3cab1c18d38a45e7a688aceeb4fcfcaa", "companyID": "1eeec343485723ee58afef12", "workerID": "674759a85785745748e3847a", "workerType": "contractor", "garnishment_type": "creditor", "priority": 50, "total_amount_owed": 500, "total_amount_withheld": 0, "status": "active", "effective_start_date": "2025-01-01", "agency_name": "Acme Agency", "agency_address": "123 Court St", "cap_percentage": 25, "case_id": "CASE-1", "order_number": "ORD-1", "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "garnishmentID": { "type": "string", "description": "Unique identifier for this garnishment", "example": "3cab1c18d38a45e7a688aceeb4fcfcaa" }, "companyID": { "type": "string", "description": "Company ID of employer", "example": "1eeec343485723ee58afef12" }, "workerID": { "type": "string", "description": "Employee or contractor ID this garnishment applies to", "example": "674759a85785745748e3847a" }, "workerType": { "type": "string", "enum": ["employee", "contractor"], "description": "Whether the worker is an employee or contractor", "example": "contractor" }, "garnishment_type": { "type": "string", "enum": [ "child_support", "federal_tax_levy", "state_tax_levy", "creditor", "student_loan", "other" ], "description": "Type of garnishment order", "example": "creditor" }, "priority": { "type": "integer", "description": "Withholding priority. Lower numbers are withheld first. When omitted on create, Zeal applies a type-based default.", "example": 50 }, "total_amount_owed": { "type": "number", "description": "Total balance owed in dollars. Omit for open-ended / forever orders.", "example": 500 }, "total_amount_withheld": { "type": "number", "description": "Total amount withheld to date in dollars", "example": 0 }, "status": { "type": "string", "enum": [ "active", "satisfied", "modified", "vacated", "canceled" ], "description": "Lifecycle status of the garnishment", "example": "active" }, "effective_start_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) when withholding begins", "example": "2025-01-01" }, "effective_end_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) when withholding ends. Omit for open-ended orders.", "example": "2025-12-31" }, "agency_name": { "type": "string", "description": "Name of the collecting agency", "example": "Acme Agency" }, "agency_address": { "type": "string", "description": "Address of the collecting agency", "example": "123 Court St" }, "cap_amount": { "type": "number", "description": "Per-paycheck maximum withhold amount in dollars. At least one of cap_amount or cap_percentage is required on create.", "example": 150 }, "cap_percentage": { "type": "number", "description": "Per-paycheck maximum withhold percentage of disposable earnings (0-100). At least one of cap_amount or cap_percentage is required on create.", "example": 25 }, "garnishment_state": { "type": "string", "description": "US state code (2-letter) associated with the order", "example": "CA" }, "case_id": { "type": "string", "description": "Court/agency case identifier", "example": "CASE-1" }, "order_number": { "type": "string", "description": "Court/agency order number", "example": "ORD-1" }, "custom_name": { "type": "string", "description": "Optional display name for this garnishment", "example": "Acme creditor" }, "external_id": { "type": "string", "description": "Optional external identifier for your own systems", "example": "ext-create-1" }, "previous_garnishmentID": { "type": "string", "description": "ID of the garnishment this record supersedes. Present when this garnishment was created via a modify (status: modified) transition; omitted otherwise.", "example": "2bab1c18d38a45e7a688aceeb4fcfcbb" }, "canceled_reason": { "type": "string", "description": "Reason provided when status is canceled" }, "satisfied_at": { "type": "string", "description": "ISO timestamp when the garnishment was fully satisfied" }, "created_at": { "type": "string", "description": "ISO timestamp when the garnishment was created", "example": "2025-01-01T00:00:00.000Z" }, "updated_at": { "type": "string", "description": "ISO timestamp when the garnishment was last updated", "example": "2025-01-01T00:00:00.000Z" }, "withholding_schedule": { "$ref": "#/components/schemas/WithholdingSchedule" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "Invalid UUID", "code": 0 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "example": 0 } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "garnishments", "x-fern-sdk-method-name": "get" }, "patch": { "summary": "Update Garnishment", "description": "Transitions a garnishment lifecycle status. Details are append-only: use status modified with a modification payload to supersede terms; use canceled or vacated to close an active garnishment in place. Simple caps and withholding_schedule are mutually exclusive: sending a non-null value on one mode clears the omitted opposite mode. Sending both modes together is rejected. When modification.withholding_schedule is set, the garnishment must be for an employee (contractors have no pay frequency; use simple caps instead). It must tile $0.00 to infinity per pay frequency with no gaps or overlaps, and at least one bracket must withhold. It does not need to cover every pay frequency; a payment whose pay frequency is not listed withholds nothing.", "operationId": "update-garnishment", "parameters": [ { "name": "garnishmentID", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Garnishment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Modify", "type": "object", "required": ["companyID", "status", "modification"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "status": { "type": "string", "enum": ["modified"], "description": "Must be modified" }, "modification": { "type": "object", "description": "Partial overrides for the replacement garnishment. Omitted fields are inherited from the superseded record. Simple caps (cap_amount / cap_percentage) and withholding_schedule are mutually exclusive: sending a non-null value on one mode clears the omitted opposite mode, so a mode switch does not need to null the other side. Sending both modes together is rejected. When withholding_schedule is set, the garnishment must be for an employee (contractors have no pay frequency; use simple caps instead). Every frequency branch must tile $0.00 to infinity with no gaps or overlaps, and at least one bracket must withhold. The schedule does not need to cover every pay frequency; a payment whose pay frequency is not listed withholds nothing.", "properties": { "garnishment_type": { "type": "string", "enum": [ "child_support", "federal_tax_levy", "state_tax_levy", "creditor", "student_loan", "other" ], "description": "Override garnishment type. Omit to inherit from the superseded record." }, "effective_start_date": { "type": "string", "description": "Override effective start date. Omit to inherit." }, "effective_end_date": { "type": "string", "nullable": true, "description": "Override effective end date. Pass null to clear. Omit to inherit." }, "priority": { "type": "integer", "nullable": true, "minimum": 0, "description": "Override priority. Pass null to clear. Omit to inherit." }, "total_amount_owed": { "type": "number", "nullable": true, "minimum": 0, "description": "Override total amount owed. Pass null to clear. Omit to inherit. Must be >= amount already withheld." }, "cap_amount": { "type": "number", "nullable": true, "minimum": 0, "description": "Override per-paycheck cap amount in dollars. Pass null to clear. Omit to inherit, unless a non-null withholding_schedule is sent (that mode switch clears omitted simple caps). Mutually exclusive with withholding_schedule; do not send both. Resulting record must still have cap_amount, cap_percentage, or withholding_schedule." }, "cap_percentage": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100, "description": "Override per-paycheck cap percentage (0-100). Pass null to clear. Omit to inherit, unless a non-null withholding_schedule is sent (that mode switch clears omitted simple caps). Mutually exclusive with withholding_schedule; do not send both." }, "garnishment_state": { "type": "string", "nullable": true, "description": "Override state code. Pass null to clear. Omit to inherit." }, "agency_name": { "type": "string", "description": "Override agency name. Omit to inherit." }, "agency_address": { "type": "string", "description": "Override agency address. Omit to inherit." }, "case_id": { "type": "string", "description": "Override case ID. Omit to inherit." }, "order_number": { "type": "string", "description": "Override order number. Omit to inherit." }, "custom_name": { "type": "string", "nullable": true, "description": "Override custom name. Pass null to clear. Omit to inherit." }, "external_id": { "type": "string", "nullable": true, "description": "Override external ID. Pass null to clear. Omit to inherit." }, "withholding_schedule": { "allOf": [ { "$ref": "#/components/schemas/WithholdingSchedule" } ], "nullable": true, "description": "Override withholding schedule. Employee-only: contractors have no pay frequency, so a schedule on a contractor is rejected — use cap_amount / cap_percentage instead. Pass null to clear. Omit to inherit, unless a non-null simple cap is sent (that mode switch clears an omitted schedule). Mutually exclusive with cap_amount / cap_percentage; do not send both. When set, every frequency branch must tile $0.00 to infinity with no gaps or overlaps, and at least one bracket must withhold. Money fields are in dollars." } } } } }, { "title": "Cancel", "type": "object", "required": ["companyID", "status", "canceled_reason"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "status": { "type": "string", "enum": ["canceled"], "description": "Must be canceled" }, "canceled_reason": { "type": "string", "description": "Reason for cancellation (required)" } } }, { "title": "Vacate", "type": "object", "required": ["companyID", "status"], "properties": { "companyID": { "type": "string", "description": "Company ID of employer" }, "status": { "type": "string", "enum": ["vacated"], "description": "Must be vacated" } } } ] }, "examples": { "Modify": { "value": { "companyID": "1eeec343485723ee58afef12", "status": "modified", "modification": { "cap_percentage": 30, "total_amount_owed": 450 } } }, "Modify to withholding schedule": { "summary": "Switch to an advanced withholding schedule", "value": { "companyID": "1eeec343485723ee58afef12", "status": "modified", "modification": { "withholding_schedule": [ { "frequency": "weekly", "brackets": [ { "min": 0, "max": null, "action": { "kind": "amount", "amount": 50 } } ] } ] } } }, "Cancel": { "value": { "companyID": "1eeec343485723ee58afef12", "status": "canceled", "canceled_reason": "duplicate entry" } }, "Vacate": { "value": { "companyID": "1eeec343485723ee58afef12", "status": "vacated" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Canceled": { "value": { "success": true, "data": { "garnishmentID": "3cab1c18d38a45e7a688aceeb4fcfcaa", "companyID": "1eeec343485723ee58afef12", "workerID": "674759a85785745748e3847a", "workerType": "contractor", "garnishment_type": "creditor", "priority": 50, "total_amount_owed": 500, "total_amount_withheld": 0, "status": "canceled", "effective_start_date": "2025-01-01", "agency_name": "Acme Agency", "agency_address": "123 Court St", "cap_percentage": 25, "case_id": "CASE-1", "order_number": "ORD-1", "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z", "canceled_reason": "duplicate entry" } } }, "Modified": { "value": { "success": true, "data": { "garnishmentID": "4dab1c18d38a45e7a688aceeb4fcfcbb", "companyID": "1eeec343485723ee58afef12", "workerID": "674759a85785745748e3847a", "workerType": "contractor", "garnishment_type": "creditor", "priority": 50, "total_amount_owed": 450, "total_amount_withheld": 0, "status": "active", "effective_start_date": "2025-01-01", "agency_name": "Acme Agency", "agency_address": "123 Court St", "cap_percentage": 30, "case_id": "CASE-1", "order_number": "ORD-1", "previous_garnishmentID": "3cab1c18d38a45e7a688aceeb4fcfcaa", "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z" } } }, "Modify to withholding schedule": { "summary": "Switch to an advanced withholding schedule", "value": { "success": true, "data": { "garnishmentID": "4dab1c18d38a45e7a688aceeb4fcfcbb", "companyID": "1eeec343485723ee58afef12", "workerID": "674759a85785745748e3847a", "workerType": "employee", "garnishment_type": "creditor", "priority": 50, "total_amount_owed": 500, "total_amount_withheld": 0, "status": "active", "effective_start_date": "2025-01-01", "agency_name": "Acme Agency", "agency_address": "123 Court St", "withholding_schedule": [ { "frequency": "weekly", "brackets": [ { "min": 0, "max": null, "action": { "kind": "amount", "amount": 50 } } ] } ], "case_id": "CASE-1", "order_number": "ORD-1", "previous_garnishmentID": "3cab1c18d38a45e7a688aceeb4fcfcaa", "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z" } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "default": true }, "data": { "type": "object", "properties": { "garnishmentID": { "type": "string", "description": "Unique identifier for this garnishment", "example": "3cab1c18d38a45e7a688aceeb4fcfcaa" }, "companyID": { "type": "string", "description": "Company ID of employer", "example": "1eeec343485723ee58afef12" }, "workerID": { "type": "string", "description": "Employee or contractor ID this garnishment applies to", "example": "674759a85785745748e3847a" }, "workerType": { "type": "string", "enum": ["employee", "contractor"], "description": "Whether the worker is an employee or contractor", "example": "contractor" }, "garnishment_type": { "type": "string", "enum": [ "child_support", "federal_tax_levy", "state_tax_levy", "creditor", "student_loan", "other" ], "description": "Type of garnishment order", "example": "creditor" }, "priority": { "type": "integer", "description": "Withholding priority. Lower numbers are withheld first. When omitted on create, Zeal applies a type-based default.", "example": 50 }, "total_amount_owed": { "type": "number", "description": "Total balance owed in dollars. Omit for open-ended / forever orders.", "example": 500 }, "total_amount_withheld": { "type": "number", "description": "Total amount withheld to date in dollars", "example": 0 }, "status": { "type": "string", "enum": [ "active", "satisfied", "modified", "vacated", "canceled" ], "description": "Lifecycle status of the garnishment", "example": "active" }, "effective_start_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) when withholding begins", "example": "2025-01-01" }, "effective_end_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) when withholding ends. Omit for open-ended orders.", "example": "2025-12-31" }, "agency_name": { "type": "string", "description": "Name of the collecting agency", "example": "Acme Agency" }, "agency_address": { "type": "string", "description": "Address of the collecting agency", "example": "123 Court St" }, "cap_amount": { "type": "number", "description": "Per-paycheck maximum withhold amount in dollars. At least one of cap_amount or cap_percentage is required on create.", "example": 150 }, "cap_percentage": { "type": "number", "description": "Per-paycheck maximum withhold percentage of disposable earnings (0-100). At least one of cap_amount or cap_percentage is required on create.", "example": 25 }, "garnishment_state": { "type": "string", "description": "US state code (2-letter) associated with the order", "example": "CA" }, "case_id": { "type": "string", "description": "Court/agency case identifier", "example": "CASE-1" }, "order_number": { "type": "string", "description": "Court/agency order number", "example": "ORD-1" }, "custom_name": { "type": "string", "description": "Optional display name for this garnishment", "example": "Acme creditor" }, "external_id": { "type": "string", "description": "Optional external identifier for your own systems", "example": "ext-create-1" }, "previous_garnishmentID": { "type": "string", "description": "ID of the garnishment this record supersedes. Present when this garnishment was created via a modify (status: modified) transition; omitted otherwise.", "example": "2bab1c18d38a45e7a688aceeb4fcfcbb" }, "canceled_reason": { "type": "string", "description": "Reason provided when status is canceled" }, "satisfied_at": { "type": "string", "description": "ISO timestamp when the garnishment was fully satisfied" }, "created_at": { "type": "string", "description": "ISO timestamp when the garnishment was created", "example": "2025-01-01T00:00:00.000Z" }, "updated_at": { "type": "string", "description": "ISO timestamp when the garnishment was last updated", "example": "2025-01-01T00:00:00.000Z" }, "withholding_schedule": { "$ref": "#/components/schemas/WithholdingSchedule" } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": { "success": false, "errors": [ { "message": "status is required and must be 'modified', 'canceled', or 'vacated'", "code": 0 } ] } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer", "example": 0 } } } } } } } } } }, "deprecated": false, "x-fern-sdk-group-name": "garnishments", "x-fern-sdk-method-name": "update" } }, "/agents/chat": { "post": { "summary": "Chat with an agent", "description": "Send a message to a company-scoped Zeal agent and receive a streamed response. Requires an Agent-enabled API key. Include companyID in the request body. Supported agentId values: PayrollSpecialistAgent, HrSpecialistAgent, ReportingSpecialistAgent.", "operationId": "post-agents-chat", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bearer token. Must be an Agent-enabled API key. Contact the Zeal team to enable Agents on your partner account." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "companyID", "conversationId", "messages", "agentId" ], "properties": { "companyID": { "type": "string", "description": "Zeal company ID" }, "conversationId": { "type": "string", "description": "Client-managed conversation ID. You create and store this value; Zeal does not issue it. Generate a unique ID when the user starts a new chat (for example a UUID). Send the same conversationId on every later request in that chat so context is preserved. Use a new conversationId when starting a different conversation. Persist the ID in your application if users should be able to resume chats later." }, "messages": { "type": "array", "minItems": 1, "description": "Chat messages for this turn.", "items": { "type": "object", "required": ["id", "role", "parts"], "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "parts": { "type": "array", "items": {} } }, "additionalProperties": true } }, "agentId": { "type": "string", "description": "Agent to invoke. One of PayrollSpecialistAgent, HrSpecialistAgent, or ReportingSpecialistAgent.", "enum": [ "PayrollSpecialistAgent", "HrSpecialistAgent", "ReportingSpecialistAgent" ] }, "clientTimeZone": { "type": "string" } } }, "examples": { "Request Example": { "value": { "conversationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "agentId": "PayrollSpecialistAgent", "messages": [ { "id": "msg_01", "role": "user", "parts": [ { "type": "text", "text": "What is the status of the latest payroll run?" } ] } ], "clientTimeZone": "America/New_York", "companyID": "fc235f012bae46222ca3444cc2215bcfa" } } } } } }, "responses": { "200": { "description": "Streamed agent response", "content": { "text/event-stream": { "schema": { "type": "string" }, "examples": { "Result": { "value": "data: {\"type\":\"text-delta\",\"delta\":\"Payroll\"}\n\ndata: [DONE]\n\n" } } } }, "headers": { "x-vercel-ai-ui-message-stream": { "schema": { "type": "string", "example": "v1" }, "description": "Present on streamed responses." } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } }, "testMode": { "type": "boolean", "example": false } } }, "examples": { "Error": { "value": { "success": false, "errors": [ { "message": "Invalid request", "code": 0 } ], "testMode": false } } } } } }, "502": { "description": "502", "content": { "application/json": { "examples": { "Error": { "value": { "success": false, "errors": [ { "code": "SPOCK_AI_PROXY_ERROR", "message": "Failed to reach AI service" } ] } } } } } } }, "deprecated": false } }, "/mcp": { "get": { "summary": "MCP Streamable HTTP session", "description": "Open or continue an MCP Streamable HTTP session. Requires an Agent-enabled API key. Pass companyID as a query parameter.", "operationId": "get-mcp", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bearer token. Must be an Agent-enabled API key. Contact the Zeal team to enable Agents on your partner account." }, { "name": "companyID", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Zeal company ID" }, { "name": "mcp-session-id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "MCP session ID for continuing an existing session." }, { "name": "Accept", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional Accept header for the MCP client." } ], "responses": { "200": { "description": "MCP session stream or response", "content": { "text/event-stream": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "mcp-session-id": { "schema": { "type": "string" }, "description": "MCP session ID returned by Zeal when present." } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } }, "testMode": { "type": "boolean", "example": false } } }, "examples": { "Error": { "value": { "success": false, "errors": [ { "message": "Invalid request", "code": 0 } ], "testMode": false } } } } } }, "502": { "description": "502", "content": { "application/json": { "examples": { "Error": { "value": { "success": false, "errors": [ { "code": "UPSTREAM_UNAVAILABLE", "message": "Unable to complete the request" } ] } } } } } } }, "deprecated": false }, "post": { "summary": "MCP Streamable HTTP", "description": "Connect an MCP client to Zeal agents for a company over Streamable HTTP. Requires an Agent-enabled API key. Pass companyID as a query parameter. Available tools: ask_PayrollSpecialistAgent, ask_HrSpecialistAgent, ask_ReportingSpecialistAgent, ask_MigrationsSpecialistAgent.", "operationId": "post-mcp", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bearer token. Must be an Agent-enabled API key. Contact the Zeal team to enable Agents on your partner account." }, { "name": "companyID", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Zeal company ID" }, { "name": "mcp-session-id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "MCP session ID for continuing an existing session." }, { "name": "Accept", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional Accept header for the MCP client." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC MCP request body.", "additionalProperties": true }, "examples": { "Request Example": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } } } } } }, "responses": { "200": { "description": "MCP response (JSON or event stream)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "Result": { "value": { "jsonrpc": "2.0", "id": 1, "result": { "tools": [] } } } } }, "text/event-stream": { "schema": { "type": "string" } } }, "headers": { "mcp-session-id": { "schema": { "type": "string" }, "description": "MCP session ID returned by Zeal when present." } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } }, "testMode": { "type": "boolean", "example": false } } }, "examples": { "Error": { "value": { "success": false, "errors": [ { "message": "Invalid request", "code": 0 } ], "testMode": false } } } } } }, "502": { "description": "502", "content": { "application/json": { "examples": { "Error": { "value": { "success": false, "errors": [ { "code": "UPSTREAM_UNAVAILABLE", "message": "Unable to complete the request" } ] } } } } } } }, "deprecated": false }, "delete": { "summary": "End MCP session", "description": "End an MCP Streamable HTTP session. Requires an Agent-enabled API key. Pass companyID as a query parameter.", "operationId": "delete-mcp", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bearer token. Must be an Agent-enabled API key. Contact the Zeal team to enable Agents on your partner account." }, { "name": "companyID", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Zeal company ID" }, { "name": "mcp-session-id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "MCP session ID for continuing an existing session." } ], "responses": { "200": { "description": "MCP session ended", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "mcp-session-id": { "schema": { "type": "string" }, "description": "MCP session ID returned by Zeal when present." } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "integer" } } } }, "testMode": { "type": "boolean", "example": false } } }, "examples": { "Error": { "value": { "success": false, "errors": [ { "message": "Invalid request", "code": 0 } ], "testMode": false } } } } } }, "502": { "description": "502", "content": { "application/json": { "examples": { "Error": { "value": { "success": false, "errors": [ { "code": "UPSTREAM_UNAVAILABLE", "message": "Unable to complete the request" } ] } } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true }