Changelog
Back to All
Added

Documents API (Beta)

4 days ago by ReadMe API

You can now read employees' HR documents, track compliance and expirations, and upload files onto employees' documents through the new Documents API.

🚧

Beta

The Documents API is in Beta. Endpoints, fields, and behavior may change in the upcoming weeks. See Beta Endpoints for what this means. Questions, feedback, or issues: [email protected].

New Endpoints

  • GET /documents/v1/documents — List the document templates you can view, with type, review, and expiration settings
  • GET /documents/v1/user-documents — List which users have which documents and each user's status. Filter by documentIds or userIds (up to 100 each), status, and expiringBefore
  • PUT /documents/v1/users/USERID/documents/{documentId}/entry — Push up to 10 uploaded files onto a user's document, with an optional per-entry expiresAt

Key Features

  • Compliance at a glance: every assigned document is returned per user, including ones not yet submitted (pendingUserUpload), with uploadedAt, signedAt, and expiresAt
  • Expiration tracking: expiringBefore covers both shared recurring dates and per-entry dates
  • Upload from your systems: upload files through the Attachments API with featureType: documents, then push them onto the employee
  • Permission-aware approval: pushes from callers with approve permission are approved; upload-only callers create pendingApproval entries. Entries awaiting review are never overwritten
  • Machine-readable errors: every Documents error returns extraData.errorCode

Authentication

  • API Key (X-API-KEY header), or
  • OAuth 2.0 with documents.read and documents.write (plus attachments.write for uploading files)

Available on the HR Hub Expert plan.

Use Cases

  • HRIS sync: mirror each employee's document status into your HR system
  • Expiry alerts: find licenses and certifications expiring in the next 30 days
  • Background checks: push a vendor's PDF straight onto the employee's profile

For full details and examples, see the Documents Overview, Track Document Compliance, and Upload Documents for Employees guides, and the API Reference.