--- updatedAt: 2026-10-15T14:19:57.000Z agentTools: projectIndex: https://developer.connecteam.com/llms.txt --- # Overview > 🚧 Beta > > **The Documents API is in Beta.** Endpoints, fields, and behavior may change in the upcoming weeks. See [Beta Endpoints](https://developer.connecteam.com/docs/beta-endpoints) for what this means. Questions, feedback, or issues: . Read your document templates, see which employees have which documents and where each one stands, and upload files onto employees' documents from your own systems. The Documents API covers the HR documents you collect from employees in Connecteam: IDs, licenses, certifications, signed policies, and government tax forms. Use it to sync compliance status into an HRIS, alert on expiring certifications, or push files you already hold (for example, a background check PDF) straight onto the employee's profile. > 🚧 Plan Requirement > > **The Documents API is available on the HR Hub Expert plan.** Calls from accounts without it return `403`. ## Available Endpoints | Method | Endpoint | Description | | :----- | :-------------------------------------------------------- | :-------------------------------------------------------------------------- | | GET | /documents/v1/documents | List the document templates you can view, with type and expiration settings | | GET | /documents/v1/user-documents | List which users have which documents, and each user's status | | PUT | /documents/v1/users/{userId}/documents/{documentId}/entry | Upload a file onto a user's document | *** ## Key Concepts | Concept | What it is | | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------- | | **Document** | A template defined in the dashboard, such as "Driver's License" or "W-4". Identified by `documentId`. | | **Document pack** | A folder of documents assigned to a group of employees. Assignment and visibility are decided per pack. | | **User document** | One row per user per assigned document. Carries the user's `status`, plus `uploadedAt`, `signedAt` and `expiresAt` when they apply. | | **Entry** | The file(s) a user or admin submitted for a document. Pushing an entry creates the user's latest submission. | A user only has a document if it is in a pack assigned to them. Packs, documents, and assignments are managed in the Connecteam dashboard; this API reads them and records entries. ### Document types | `documentType` | Meaning | Can you push a file? | | :------------------- | :------------------------------------------------------- | :------------------------------------- | | `document` | Plain upload (ID, license, certificate) | Yes | | `eSign` | A document the employee and/or admin signs in Connecteam | No, completed through the signing flow | | `governmentDocument` | A W-4, W-9 or I-9 form | No, completed through the signing flow | `templateType` tells you the underlying template for signing types: `sameForAll`, `perUser`, `w4`, `w9`, or `i9`. It is omitted for `document`. ### Statuses | `status` | Meaning | | :---------------------- | :------------------------------------------ | | `pendingUserUpload` | Nothing has been submitted yet | | `pendingUserFilling` | Waiting for the employee to fill in or sign | | `pendingAdminFilling` | Waiting for an admin to sign | | `pendingYourCompletion` | Waiting for **you**, the caller, to sign | | `pendingApproval` | Submitted and waiting for admin approval | | `approved` | Approved | | `rejected` | Rejected by an admin | ### Expiration A document can expire in one of two ways, shown in `expiration.type` on the documents endpoint: * `document`: every assigned user shares one recurring date (`frequency` is `biWeekly`, `monthly`, or `yearly`). `nextExpiresAt` rolls forward each cycle. * `entry`: each user's own entry carries its own date, for example the expiry printed on a license. Set it with `expiresAt` when you push the entry. `expiration` is omitted when the document does not expire. *** ## Authentication * **API Key** (`X-API-KEY` header), or * **OAuth 2.0** | Scope | Operations | | :---------------- | :-------------------------------- | | `documents.read` | GET documents, GET user documents | | `documents.write` | PUT a user document entry | Results are limited to the packs the caller is allowed to view. Pushing an entry needs upload or approve permission on the document's pack. *** ## Workflow 1. **Get documents:** list the templates and note the `documentId` values and expiration settings you care about. 2. **Get user documents:** filter by `documentIds` or `userIds` to see who has each document and their status. 3. **Push entries:** upload a file through the Attachments API with `featureType: documents`, then attach it to a user's document. 4. **Re-check:** read user documents again, for example with `status` or `expiringBefore`, to track what is still missing or about to expire. *** ## Guide Pages | Guide | What it covers | | :--------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | | [Track Document Compliance](documents-track-compliance) | List documents, find who is missing a document, see one employee's documents, find expiring documents, pagination | | [Upload Documents for Employees](documents-upload-for-employees) | Upload a file, push it onto a user's document, set per-entry expiration, approval behavior, replacing an entry, errors | *** ## Error Format Documents errors return the HTTP status plus a machine-readable code in `extraData.errorCode`: ```json { "requestId": "3f6c2a1e-8b7d-4c5e-9a0f-1b2c3d4e5f60", "error": "Document 52114 is not assigned to user 3067712", "path": "/documents/v1/users/3067712/documents/52114/entry", "extraData": { "errorCode": "DOCUMENT_NOT_ASSIGNED", "userId": 3067712, "documentId": 52114 } } ``` | HTTP Status | `errorCode` | When | | :------------ | :----------------------------- | :---------------------------------------------------------------------------------------------- | | `400` | `MISSING_FILTER` | Get user documents was called without `userIds` or `documentIds` | | `400` | `DOCUMENT_NOT_ASSIGNED` | The document exists but is not in any pack assigned to the user | | `400` | `DOCUMENT_TYPE_NOT_UPLOADABLE` | The document is `eSign` or `governmentDocument` | | `400` | `ENTRY_PENDING_REVIEW` | The user already has an entry waiting for approval on this document | | `400` | `EXPIRATION_NOT_SUPPORTED` | `expiresAt` was sent for a document whose expiration type is not `entry` | | `400` | `EXPIRATION_DATE_IN_PAST` | `expiresAt` is not in the future | | `400` | `FILE_NOT_FOUND` | A `fileId` does not exist, its upload was not completed, or it was uploaded for another feature | | `403` | `INSUFFICIENT_PERMISSION` | The caller lacks upload or approve permission on the document's pack | | `404` | `DOCUMENT_NOT_FOUND` | The document does not exist or was deleted | | `404` | — | The user does not exist or is outside the caller's scope | | `401` / `403` | — | Missing or invalid credentials, missing scope, or the plan does not include the Documents API | | `422` | — | Invalid parameters, for example more than 100 `userIds` | | `429` | — | Rate limit exceeded | *** [API Reference](https://developer.connecteam.com/reference/get_documents_documents_v1_documents_get)