> ## Documentation Index
> Fetch the complete documentation index at: https://jobticket-docs.ticket-plus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List Employee Documents

> Retrieve a paginated list of documents belonging to a specific employee.

Returns all documents associated with a given employee. For a company-wide view across all employees, use [List All Documents](/v1/endpoint/documents-list) instead.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://v1-api.ticket-plus.app/employees/42/documents?page=1&perPage=10" \
    --header "Authorization: Basic <base64(clientId:clientSecret)>"
  ```

  ```python Python theme={null}
  import requests, base64

  credentials = base64.b64encode(b"<clientId>:<clientSecret>").decode()

  res = requests.get(
      "https://v1-api.ticket-plus.app/employees/42/documents",
      params={"page": 1, "perPage": 10},
      headers={"Authorization": f"Basic {credentials}"},
  )
  print(res.json())
  ```

  ```javascript Node.js theme={null}
  const credentials = Buffer.from("<clientId>:<clientSecret>").toString("base64");

  const res = await fetch(
    "https://v1-api.ticket-plus.app/employees/42/documents?page=1&perPage=10",
    { headers: { Authorization: `Basic ${credentials}` } },
  );
  console.log(await res.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "data": [
        {
          "id": 101,
          "employeeId": 42,
          "documentName": "May 2024 Transit Invoice",
          "documentFileType": "pdf",
          "downloadable": true,
          "createdAt": "2024-05-01T09:00:00Z",
          "updatedAt": "2024-05-01T09:00:00Z",
          "resource": "employee-document",
          "_links": {
            "self": { "href": "https://v1-api.ticket-plus.app/employee-documents/101", "type": "application/json" },
            "employee": { "href": "https://v1-api.ticket-plus.app/employees/42", "type": "application/json" }
          }
        }
      ],
      "page": 1,
      "perPage": 10,
      "totalPages": 1,
      "total": 1
    }
  }
  ```
</ResponseExample>

<Tip>
  Check `downloadable` on each result before calling [Download
  Document](/v1/endpoint/documents-download). Documents with `downloadable:
      false` cannot be fetched as binary files.
</Tip>

## Path Parameters

<ParamField path="id" type="integer" required>
  The unique numeric ID of the employee whose documents to list.
</ParamField>

## Query Parameters

<ParamField query="search" type="string">
  Full-text search across document names.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number to return. Starts at `1`.
</ParamField>

<ParamField query="perPage" type="integer" default="10">
  Number of results per page. Maximum is `100`.
</ParamField>

<ParamField query="sortOrder" type="string" default="desc">
  Sort direction. Allowed values: `asc`, `desc`.
</ParamField>

## Response

<ResponseField name="data" type="object" required>
  <Expandable title="properties">
    <ResponseField name="data" type="object[]" required>
      Array of document objects.

      <Expandable title="document object">
        <ResponseField name="id" type="integer" required>
          Unique document identifier. Use this `id` with the [Download
          Document](/v1/endpoint/documents-download) endpoint.
        </ResponseField>

        <ResponseField name="employeeId" type="integer | null">
          ID of the employee this document belongs to.
        </ResponseField>

        <ResponseField name="documentName" type="string" required>
          Human-readable name of the document.
        </ResponseField>

        <ResponseField name="documentFileType" type="string" required>
          File extension of the document, e.g. `pdf`.
        </ResponseField>

        <ResponseField name="downloadable" type="boolean" required>
          `true` if the file binary can be fetched via [Download
          Document](/v1/endpoint/documents-download). `false` means the file is
          not available for download.
        </ResponseField>

        <ResponseField name="createdAt" type="string" required>
          ISO 8601 timestamp when the document was created.
        </ResponseField>

        <ResponseField name="updatedAt" type="string" required>
          ISO 8601 timestamp when the document was last updated.
        </ResponseField>

        <ResponseField name="resource" type="string" required>
          Resource type label. Always `"employee-document"`.
        </ResponseField>

        <ResponseField name="_links" type="object" required>
          HAL hypermedia links.

          <Expandable title="properties">
            <ResponseField name="self" type="object" required>
              Link to this document resource.

              <Expandable title="properties">
                <ResponseField name="href" type="string" required>
                  URL of this document.
                </ResponseField>

                <ResponseField name="type" type="string" required>
                  Media type.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="employee" type="object" required>
              Link to the employee who owns this document.

              <Expandable title="properties">
                <ResponseField name="href" type="string" required>
                  URL of the owning employee.
                </ResponseField>

                <ResponseField name="type" type="string" required>
                  Media type.
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="page" type="integer" required>
      Current page number.
    </ResponseField>

    <ResponseField name="perPage" type="integer" required>
      Number of results per page.
    </ResponseField>

    <ResponseField name="totalPages" type="integer" required>
      Total number of pages available.
    </ResponseField>

    <ResponseField name="total" type="integer" required>
      Total number of documents for this employee.
    </ResponseField>
  </Expandable>
</ResponseField>


## OpenAPI

````yaml GET /employees/{id}/documents
openapi: 3.0.3
info:
  title: JobTicket API
  description: >-
    The JobTicket B2B API lets you read employee data, manage HR integrations,
    and access employee documents programmatically. All endpoints use HTTP Basic
    Auth — pass your API key credentials from the Developer Portal as the
    username and password.
  version: 1.0.0
servers:
  - url: https://v1-api-staging.ticket-plus.app
    description: Staging server
  - url: https://v1-api.ticket-plus.app
    description: Production Server
security:
  - basicAuth: []
externalDocs:
  url: https://jobticket-docs.ticket-plus.app
  description: View our documentation to get more info
paths:
  /employees/{id}/documents:
    get:
      tags:
        - Employees
      summary: Paginate Employee Documents
      description: >-
        Returns a paginated list of all documents belonging to a specific
        employee. Requires the `view-employees` permission.
      parameters:
        - schema:
            type: integer
          in: path
          name: id
          required: true
          description: The unique numeric ID of the employee whose documents to list.
        - schema:
            type: string
            nullable: true
          in: query
          name: search
          required: false
          description: Search across document names.
        - schema:
            type: integer
            minimum: 0
            default: 1
            nullable: true
          in: query
          name: page
          required: false
          description: Page number to return. Starts at 1.
        - schema:
            type: integer
            minimum: 0
            maximum: 100
            default: 10
            nullable: true
          in: query
          name: perPage
          required: false
          description: Number of results per page. Maximum is 100.
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
            nullable: true
          in: query
          name: sortOrder
          required: false
          description: Sort direction — `asc` for ascending, `desc` for descending.
      responses:
        '200':
          description: A paginated list of the employee's documents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      data:
                        type: array
                        description: Array of document objects.
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              description: Unique document identifier.
                            employeeId:
                              type: integer
                              nullable: true
                              description: ID of the employee this document belongs to.
                            documentName:
                              type: string
                              description: Human-readable name of the document.
                            documentFileType:
                              type: string
                              description: >-
                                Category of the document, e.g. `contract`,
                                `payslip`.
                            downloadable:
                              type: boolean
                              description: >-
                                Whether the binary file can be fetched via the
                                download endpoint.
                            createdAt:
                              type: string
                              format: date-time
                              description: >-
                                ISO 8601 timestamp when the document was
                                created.
                            updatedAt:
                              type: string
                              format: date-time
                              description: >-
                                ISO 8601 timestamp when the document was last
                                updated.
                            resource:
                              type: string
                              description: Resource type label.
                            _links:
                              type: object
                              description: HAL hypermedia links.
                              properties:
                                self:
                                  type: object
                                  description: Link to this document.
                                  properties:
                                    href:
                                      type: string
                                    type:
                                      type: string
                                  required:
                                    - href
                                    - type
                                employee:
                                  type: object
                                  description: Link to the owning employee.
                                  properties:
                                    href:
                                      type: string
                                    type:
                                      type: string
                                  required:
                                    - href
                                    - type
                              required:
                                - self
                                - employee
                          required:
                            - id
                            - employeeId
                            - documentName
                            - documentFileType
                            - downloadable
                            - createdAt
                            - updatedAt
                            - resource
                            - _links
                      page:
                        type: integer
                        description: Current page number.
                      perPage:
                        type: integer
                        description: Number of results per page.
                      totalPages:
                        type: integer
                        description: Total number of pages.
                      total:
                        type: integer
                        description: Total number of matching documents.
                    required:
                      - data
                      - page
                      - perPage
                      - totalPages
                      - total
                required:
                  - data
      security:
        - basicAuth: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Auth using your API key credentials. Use the username and
        password issued from the Developer Portal. Encode them as
        `Base64(username:password)` and pass in the `Authorization: Basic
        <token>` header.

````