BulkEmployeeDocumentRequest

Top-level request body for POST /employee-documents/.

id stringrequired

Identifier field

created_at stringrequired

Record creation date

updated_at stringrequired

Record update date

items

object[]

required

List of role/document items to process. No limit on number of items; total documents across all items must not exceed 40.

Array [

worker_id stringrequired

Id of the worker to attach documents to.

documents

object[]

required

Documents to attach to the role. At least one required. Each entry references a FileUploadTracker by file_id.

Array [

file_id stringrequired

Id of a FileUploadTracker in ACTIVE status whose file should become a document on the hire

name string

Document name. Defaults to the uploaded file name when omitted.

signature_date string

Signature date in YYYY-MM-DD format.

]

folder_id string

Optional destination folder for documents. Accepts either: (1) an ObjectId string for custom folders, or (2) a default folder identifier ('root', 'confidential_documents', 'notices', 'work_authorization'). When omitted, documents land at the root of the worker's profile (current default behavior). When supplied, the folder must exist, be in an active state, be provisioned for the target worker, and the caller must have UPLOAD permission on it — otherwise behavior is governed by on_invalid_folder.

on_invalid_folder string

Possible values: [fail, fallback_to_root]

Fallback behavior when folder_id is supplied but inaccessible. 'fail' (default) rejects each affected document with FOLDER_ACCESS_ERROR. 'fallback_to_root' uploads to the worker's root profile instead and attaches a FOLDER_ACCESS_FALLBACK warning to each result. Ignored when folder_id is omitted.

]