# Create a new employee document

> Create a new employee document

POST

/employee-documents/

Creates a new employee document and returns its ID and details.

#### Helpful resources

-   [Upload and attach files](https://developer.rippling.com/documentation/rest-api/guides/file-uploads)

### Required Scopes

-   employee-documents.read-write
    

### Request

-   application/json

**Body**

**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** string required

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** string required

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

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.

**Possible values:** \[fail,fallback\_to\_root\]

\]

## Responses

-   200

Successful response

-   application/json

-   Schema
-   Example (from schema)

**Schema**

**id** string required

Identifier field

**created\_at** string required

Record creation date

**updated\_at** string required

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** string required

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** string required

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

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.

**Possible values:** \[fail,fallback\_to\_root\]

\]

```json
{
  "id": "string",
  "created_at": "string",
  "updated_at": "string",
  "items": [
    {
      "worker_id": "string",
      "documents": [
        {
          "file_id": "string",
          "name": "string",
          "signature_date": "string"
        }
      ],
      "folder_id": "string",
      "on_invalid_folder": "fail"
    }
  ]
}
```

Source: https://developer.rippling.com/documentation/rest-api/reference/create-employee-documents

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Public pages have a Markdown version at the same URL with .md added.