Creates a new W-4 request for an employee.

post

https://example.com/wep/companies/{companyId}/w-4/requests

Access: System, Admin, ClientAdmin, and Employee users.

The request captures a snapshot of the employee data used for the W-4 flow, including the residential address, the primary work location, and related tax inputs. Later employee profile changes do not alter the in-progress W-4 request.

Employees can create requests only for themselves. Other callers can create requests only for employees they are allowed to access.

If Worklio.ApiModels.API.Enums.W4.SpecialAction_v10.P2RedirectToFinishUrl is included in data, EeFinishUrl must also be provided.

After the W-4 request is finalized, the workflow generates the employee tax setup and the resulting W-4 documents.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

companyId

int32

required

Company identifier from the route.

Body Params

Payload describing the employee and optional workflow behavior for the new W-4 request.

Request payload for creating a new W-4 request.

employeeId

int32 | null

required

Employee identifier for whom the W-4 request should be created. Required.

specialActions

int32

enum

Flags that change the behavior of a newly created W-4 request.

Members:

1 - DisableEeEmails ( Do not send workflow emails to the employee. )
2 - DisableErEmails ( Do not send workflow emails to the employer. )
4 - P2RedirectToFinishUrl ( Redirect the employee to EeFinishUrl after the final workflow step is completed. )
8 - EeForceESignature ( Automatically apply the employee electronic signature to documents that otherwise require employee signing. )
16 - FW4ErSectionFromClient ( Federal W-4 Form: prefills the employer information section under the employee signature with client data. )
32 - FW4ErSectionFromMaster ( Federal W-4 Form: prefills the employer information section under the employee signature with master-company / PEO data. )

Allowed:

eeFinishUrl

string | null

Absolute URL that the employee should be redirected to after the final workflow step.

newWorkLocations

array of int32s | null

Optional work-location identifiers that should be added to the resulting employee tax setup and included in generated state W-4 documents.

newWorkLocations

includeEeTaxSetups

int32

enum

Flags that specify which employee tax setups should contribute other work locations to a new W-4 request.

Members:

2 - Current ( Include work locations from the current employee tax setup. )
4 - FirstInFuture ( Include work locations from the first future-dated employee tax setup. )

Allowed:

Headers

api-version

string

Defaults to 1.0

The requested API version

x-api-version

string

Defaults to 1.0

The requested API version

Responses

201Created

400Bad Request

403Forbidden

500Internal Server Error