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

# Job posting

> List, create, edit, pause, resume, and close jobs on Collective

The job API connects your platform to Collective so you can manage job postings from your own system.
Receive shortlisted applications automatically with the [Application webhook](https://docs.collective.work/docs/application-webhook.md).

## The job API

| Endpoint | Purpose |
| - | - |
| [List jobs](https://docs.collective.work/api-reference/endpoint/job/list.md) | List your organization's jobs by status, with pagination and title search. |
| [Get a job](https://docs.collective.work/api-reference/endpoint/job/get.md) | Retrieve the full content of an open, paused, or closed job. |
| [Create a job](https://docs.collective.work/api-reference/endpoint/job/create.md) | Post a new job on Collective. |
| [Update a job](https://docs.collective.work/api-reference/endpoint/job/put.md) | Edit, pause, or resume an open or paused job. |
| [Close a job](https://docs.collective.work/api-reference/endpoint/job/delete.md) | Close a job and stop accepting applications. |

All endpoints use your organization API key and support [sandbox and production environments](https://docs.collective.work/docs/sandbox.md).
Production requests require production API access. Each request accesses only jobs in your organization and the selected environment.

## List your jobs

Call `GET /jobs` to retrieve your organization's jobs, including jobs created outside the API.
By default, only `OPEN` jobs are returned.
Results are ordered by creation date, newest first, then by Collective job ID in descending order for jobs with the same creation date.

```bash theme={null}
curl --get 'https://api.collective.work/sandbox/v1/jobs' \
	--header "Authorization: Bearer $COLLECTIVE_API_KEY" \
	--data-urlencode 'page=1' \
	--data-urlencode 'pageSize=50' \
	--data-urlencode 'search=developer'
```

Set `COLLECTIVE_API_KEY` to your organization API key. Replace `sandbox` with `production` to list production jobs.
When provided, `search` matches part of the title without regard to case, within the selected statuses.

Use `status` to select the jobs to include:

| Query | Jobs returned |
| - | - |
| No `status` parameter | Open jobs |
| `status=PAUSED` | Paused jobs |
| `status=CLOSED` | Closed jobs |
| `status=OPEN,PAUSED` | Open and paused jobs |
| `status=OPEN&status=PAUSED` | Open and paused jobs, using repeated parameters |
| `status=ALL` | Open, paused, and closed jobs |

Use uppercase values and pass `ALL` by itself. Empty or invalid values return `400`.
For example, add `--data-urlencode 'status=OPEN,PAUSED'` to the request above.

The response contains `jobs`, `total`, `page`, and `pageSize`.
`total` counts all matching jobs across pages. Increase `page` until `page * pageSize` is at least `total` to retrieve all results.
The default page is `1`, and the default page size is `50`. See [List jobs](https://docs.collective.work/api-reference/endpoint/job/list.md) for parameter limits and response fields.

> [!NOTE]
>
> The list includes expired jobs whose status is still `OPEN`. Check `isExpired`
> to hide expired jobs on your careers site. Use `status` to include paused or
> closed jobs. Deleted jobs are always excluded.

## Job responses

The list returns job summaries with identifiers, status, dates, title, company, budget, contract type, location, work preferences, skills, and language.
The get, create, update, and close endpoints return the full job, which also includes `description`, `profileWanted`, `questions`, `requirePhoneNumber`, and `notifyByEmailForEveryApplication`.

* `jobUrl` is the public URL in the form `https://www.collective.work/jobs/<language>/<slug>`.
* `status` is `OPEN`, `PAUSED`, or `CLOSED`. Expiration does not change a job's status. `isExpired` indicates whether its expiration date has passed.
* `workPreferences` is an array of `REMOTE`, `HYBRID`, or `ON_SITE` values in responses. Job creation and update accept a single string.
* `GET /job` returns the full job for any status, including closed jobs. Deleted jobs return `404`.
* `DELETE /job` returns the full job with `status: "CLOSED"` and its closing date in `closedAt`.

## Pause or resume a job

Send `status` to [Update a job](https://docs.collective.work/api-reference/endpoint/job/put.md), alone or together with content changes:

```bash theme={null}
curl --request PUT 'https://api.collective.work/sandbox/v1/job' \
  --header "Authorization: Bearer $COLLECTIVE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"id":"CLIENT-123","status":"PAUSED"}'
```

* Set `status` to `PAUSED` to pause a job, or `OPEN` to resume it. Repeating either request is supported and keeps the original pause date.
* Omit `status` to edit a job without changing its status.
* Resuming does not extend an expired job. Send `expirationDate` with `OPEN` to set a new expiration date on the job and its applications.
* Closed and deleted jobs return `404`. A closed job cannot be reopened.

To close a job, use [Close a job](https://docs.collective.work/api-reference/endpoint/job/delete.md). Closing expires the job and its applications immediately.

## Applications after closing

[Get applications](https://docs.collective.work/api-reference/endpoint/application/get-applications.md) and
[Get application](https://docs.collective.work/api-reference/endpoint/application/get-application.md) remain available for closed jobs.
These reads are scoped to your organization and the selected environment. In the sandbox, they return sample applications attached to your sandbox jobs, including closed jobs.

## Understanding the job identifiers

| Field | Meaning |
| - | - |
| `jobId` | The identifier generated by Collective. |
| `internalJobId` | Your own job identifier, supplied at creation, or `null` when none was provided. |

Both fields are always present in job summaries, full job responses, and application list responses.
For requests that take an `id`, you can pass either the Collective `jobId` or your `internalJobId`.

### Choose an internalJobId

Use an identifier that is unique in your organization, such as your database ID or a job URL slug.
Examples include `550e8400-e29b-41d4-a716-446655440000` and `javascript-developer-paris-03123`.

`internalJobId` is optional. If you omit it, store the `jobId` returned by the create endpoint to retrieve, update, or close the job later.

### Set the identifier at creation

You can set `internalJobId` only when creating a job. Updates cannot change it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.