Overview

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

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

Get documents: list the templates and note the documentId values and expiration settings you care about.
Get user documents: filter by documentIds or userIds to see who has each document and their status.
Push entries: upload a file through the Attachments API with featureType: documents, then attach it to a user's document.
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	List documents, find who is missing a document, see one employee's documents, find expiring documents, pagination
Upload Documents 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:

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

Beta

Plan Requirement

Available Endpoints

Key Concepts

Document types

Statuses

Expiration

Authentication

Workflow

Guide Pages

Error Format

What’s Next