---
title: "List contract documents for an employment"
method: GET
path: "/v1/employments/{employment_id}/contract-documents"
tags: ["Employment Contracts"]
---

# List contract documents for an employment

`GET /v1/employments/{employment_id}/contract-documents`

## Request

- Base URL: `https://gateway.remote.com`
- URL: `https://gateway.remote.com/v1/employments/{employment_id}/contract-documents`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `https://gateway.remote.com/company.manage`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `document:read`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:read`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `document:read`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:read`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - HTTP bearer

Only contractor employment types are supported. Lists contract documents for a specific employment with pagination, filtering by status, and sorted by updated_at descending (latest first).

## Authentication

This endpoint accepts any one of the following token types:

- **Company-scoped access token** (`OAuth2AuthorizationCode`) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners).
- **Company-scoped access token (assertion)** (`OAuth2CompanyManagerAssertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for a company manager. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion).
- **Customer API token** (`CustomerAPIToken`) — generated by the customer on their Integration Settings page, with the scopes they choose there. See [Authorization for customers](https://developer.remote.com/docs/authorization-for-customers).

## Scopes

Any one of the scopes in a token type's row is enough. `all:read` and `all:write` work too.

| Token type | Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|---|
| Company-scoped access token | Manage employment documents (`employment_documents`) | View documents (`document:read`) | Manage documents (`document:write`) |
| Company-scoped access token (assertion) | Manage employment documents (`employment_documents`) | View documents (`document:read`) | Manage documents (`document:write`) |
| Customer API token | Manage employment documents (`employment_documents`) | View documents (`document:read`) | Manage documents (`document:write`) |

## Path parameters

- `employment_id` string, required

## Query parameters

- `statuses` ContractorContractDocumentStatus[]
- `except_statuses` ContractorContractDocumentStatus[]
- `page` integer
- `page_size` integer

## Response `200`

Success

- IndexContractDocumentsResponse: Paginated list of contract documents
  - `data` IndexContractDocuments, required: Paginated list of contract documents
    - `contract_documents` ContractDocumentItem[], required: Array of contract documents
      - `id` string, required: Contract document slug/ID
      - `inserted_at` string, required: Created timestamp
      - `name` string, nullable, required: Contract document name
      - `signatories` ListSignatory[], required: List of signatories for this contract document
        - `email` string, nullable: Email address of the signatory
        - `name` string, nullable: Full name of the signatory
        - `signature_method` 'in_platform' | 'docusign': Signing method used by this signatory
        - `signature_type` 'standard' | 'qes' | 'aes' | 'ses': Legal signature level applied when signing
        - `signed_at` string, date-time, nullable: Timestamp when the signatory signed the document, null if not yet signed
        - `status` 'pending' | 'signed' | 'unassigned', required: Current signing status of this signatory
        - `type` 'company' | 'employee' | 'admin' | 'external' | 'unknown', required: The role of this signatory in the contract signing process
        - `user_id` string, nullable: User identifier for internal signatories, null for external signatories
      - `status` 'draft' | 'awaiting_signatures' | 'deadline_passed' | 'finished', required: The signing status of a contract document. - `draft`: The document is being prepared and has not been sent for signing. - `awaiting_signatures`: The document has been sent and is waiting for one or more parties to sign. - `deadline_passed`: The signing deadline passed before all required signatures were collected. - `finished`: All required signatures have been collected and the contract is fully executed.
      - `type` string, required: Contract document type
      - `updated_at` string, nullable, required: Last updated timestamp
    - `current_page` integer, required: Current page number
    - `total_count` integer, required: Total number of contract documents
    - `total_pages` integer, required: Total number of pages

## Other responses

- `401`: Unauthorized
- `404`: Not Found
- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/remote-com/apis/contracts.md) - [All operations](https://skmtc.dev/remote-com/apis/contracts/llms.txt) - [OpenAPI document](https://skmtc.dev/remote-com/apis/contracts/revisions/a2ac13920580?raw)