---
title: "opening.list"
method: POST
path: "/opening.list"
tags: ["Openings"]
---

# opening.list

`POST /opening.list`

Lists openings.

See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples.

**Requires the [`jobsRead`](authentication#permissions-openinglist) permission.**

## Request body

- OpeningListRequest
  - `createdAfter` integer, nullable — The API will return data after this date, which is the time since the unix epoch in milliseconds
  - `cursor` string, nullable — The pagination cursor. Use 'start' for the first page or the nextCursor value from a previous response.
  - `syncToken` string, nullable — A sync token to retrieve only openings updated since the last sync. Obtained from a previous list response.
  - `limit` integer, nullable — The maximum number of openings to return per page.

## Response `200`

Responses from the opening.list endpoint

- union
  - OpeningListSuccessResponse
    - `success` true, required
    - `results` Opening[], required
      - `id` string, uuid, required — The unique identifier for the opening
      - `openedAt` string, date-time, nullable, required — The timestamp when the opening was opened
      - `closedAt` string, date-time, nullable, required — The timestamp when the opening was closed
      - `isArchived` boolean, required — Whether the opening is archived
      - `closeReasonId` string, uuid, nullable, required — The unique identifier for the close reason
      - `archivedAt` string, date-time, nullable, required — The timestamp when the opening was archived
      - `openingState` 'Draft' | 'Approved' | 'Open' | 'Closed' | 'Filled', required — The current state of the opening
      - `latestVersion` OpeningVersion, required
        - `id` string, uuid, required — The unique identifier for the opening version
        - `identifier` string, required — The human-readable opening identifier
        - `description` string, nullable, required — The opening description
        - `authorId` string, uuid, nullable, required — The unique identifier for the author
        - `createdAt` string, date-time, required — The timestamp when the opening version was created
        - `targetHireDate` string, nullable, required — The target hire date for the opening
        - `targetStartDate` string, nullable, required — The target start date for the opening
        - `isBackfill` boolean, required — Whether the opening is a backfill
        - `employmentType` 'FullTime' | 'PartTime' | 'Intern' | 'Contract' | 'Temporary', required — The employment type for the opening
        - `teamId` string, uuid, nullable, required — The unique identifier for the team
        - `jobIds` string[], required — The unique identifiers for jobs linked to the opening
        - `locationIds` string[], required — The unique identifiers for locations linked to the opening
        - `hiringTeam` OpeningHiringTeamRole[], required — The hiring team roles assigned to the opening
          - `userId` string, uuid, required — The unique identifier for the user
          - `firstName` string, required — The user's first name
          - `lastName` string, required — The user's last name
          - `email` string, email, required — The user's email address
          - `role` string, required — The user's role on the opening hiring team
        - `customFields` OpeningCustomField[], required — Custom fields associated with the opening
          - `id` string, uuid, required — The unique identifier for the custom field definition
          - `isPrivate` boolean — Whether the custom field is private and requires additional permissions
          - `title` string, required — The title of the custom field
          - `valueLabel` union — The label of the custom field value for select fields
            - string
            - string[]
          - `value` union, required — The value of the custom field
            - boolean
            - number
            - string
            - string[]
            - object
              - …
            - object
              - …
            - object
              - …
    - `nextCursor` string — Cursor for the next page of results, if available
    - `moreDataAvailable` boolean — Whether more data is available beyond this page
    - `syncToken` string — Sync token to use for future incremental syncs. Only present on the last page.
  - ErrorResponse
    - `success` false, required
    - `errors` ErrorDetail[], required
      - `message` string, required
      - `parameter` string

---

[API](https://skmtc.net/ashbyhq/apis/ashby-api.md) · [All operations](https://skmtc.net/ashbyhq/apis/ashby-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ashbyhq/ashby-api/revisions/778b919dc743/schema)