---
title: "Jobs API"
description: "Background jobs for operations too large for one request — a custom-field delete or rename over thousands of contacts."
url: https://www.unitpost.com/docs/platform/jobs
section: "Platform API reference"
updated: 2026-11-17
---
# Jobs API

> Background jobs for operations too large for one request — a custom-field delete or rename over thousands of contacts. Such a call answers `202` with a job; follow it here until it finishes.

Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/platform/jobs.

## Operations

### `GET /api/v1/jobs/{id}`

Retrieve a job

Retrieve a background job by `id` to follow its progress. An operation that touches more contacts than fits in one request (for example [Delete a custom contact field](https://www.unitpost.com/docs/platform/delete-contact-fields-id) or [Rename a custom field's key](https://www.unitpost.com/docs/platform/post-contact-fields-id-rename) above 5,000 holders, or a campaign validation over more than 5,000 recipients) answers `202` with a job. Poll this until `status` is `COMPLETED`, `FAILED` or `CANCELED`; `processed` of `total` is the progress. A failed job keeps the work it finished; resume it with [Retry a job](https://www.unitpost.com/docs/platform/post-jobs-id-retry). Reading a job takes the read capability of the resource it changes (`contacts:read` for a custom-field job or a contacts export, `campaigns:read` for a campaign check, `topics:read` for a topic opt-out). Requires the `contacts:read` capability.

Reference: https://www.unitpost.com/docs/platform/get-jobs-id ([Markdown](https://www.unitpost.com/docs/platform/get-jobs-id.md))

### `GET /api/v1/jobs`

List jobs

Your background jobs, newest first and cursor-paginated, as Settings → Bulk operations lists them: the kinds an API operation starts that your key may read. Filter with `status` or `kind`. Requires the `contacts:read` capability.

Reference: https://www.unitpost.com/docs/platform/get-jobs ([Markdown](https://www.unitpost.com/docs/platform/get-jobs.md))

### `POST /api/v1/jobs/{id}/cancel`

Cancel a job

Stop a queued or running job. A running job stops after the part in flight; the work already done stays. A kind that can't stop half-way (a custom-field rename) is a `409` saying why. Takes no body. Needs the capability that starts the kind (`contacts:write` for a custom-field job, `contacts:read` for an export, `topics:write` for a topic opt-out). Requires the `contacts:read` or `contacts:write` capability.

Reference: https://www.unitpost.com/docs/platform/post-jobs-id-cancel ([Markdown](https://www.unitpost.com/docs/platform/post-jobs-id-cancel.md))

### `POST /api/v1/jobs/{id}/retry`

Retry a job

Resume a `FAILED` job from where it stopped: nothing it already processed runs again, but the rest does (a custom-field delete finishes removing the field from every contact). Any other status is a `409`. Takes no body. Needs the capability that starts the kind (`contacts:write` for a custom-field job, `contacts:read` for an export, `topics:write` for a topic opt-out). Requires the `contacts:read` or `contacts:write` capability.

Reference: https://www.unitpost.com/docs/platform/post-jobs-id-retry ([Markdown](https://www.unitpost.com/docs/platform/post-jobs-id-retry.md))

### `GET /api/v1/jobs/{id}/download`

Download a job's file

A finished job's file (a contacts export's CSV) as a signed `url` that expires in 5 minutes. A job that isn't `COMPLETED`, or a kind with no file, is a `409`. Needs the kind's capability now: the file holds that data. Requires the `contacts:read` capability.

Reference: https://www.unitpost.com/docs/platform/get-jobs-id-download ([Markdown](https://www.unitpost.com/docs/platform/get-jobs-id-download.md))
