For AI agents: an index of this documentation is at https://developer.rippling.com/llms.txt. Public pages have a Markdown version at the same URL with .md added.

Skip to main content
REST API
API

Create a new employee document

POST
/employee-documents/

Use with AI:Rippling AI ChatGPT Claude Cursor

Create a new employee document

POST
/employee-documents/

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

Helpful resources

Required Scopes

  • employee-documents.read-write

Request

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 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

      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​

Successful response
Schema
    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

      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]
      ]
Loading...