> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/objects/job.md). # The job object The job object in the Shortcut API - every field, an example, and the endpoints that return it. A job: a service a customer buys, one-time or recurring, and the source of its visits. ## Fields | Field | Type | Description | | --------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | id | The job's id. | | `object` | `"job"` | Always `job`. | | `name` | string | The job's name, such as `Weekly mowing`. New jobs take their service's name. | | `description` | string or null | The job's description, when it has one. | | `status` | `pending`, `scheduled`, `paused`, `canceled`, `completed` | `pending` jobs are not scheduled yet (schedule them with `POST /v1/jobs/{id}/schedule`). `scheduled` jobs have visits on the schedule. `paused` jobs are on hold. `canceled` and `completed` jobs are closed. | | `customerId` | id | The customer the job is for. | | `propertyId` | id or null | The property (service address), when the job has one. | | `address` | string or null | The property's street address, when the job has a property. | | `serviceId` | id or null | The catalog service the job was created from, when it still exists. | | `estimateId` | id or null | The estimate the job came from, when it was created by approving one. | | `cadence` | `one_off`, `recurring`, `on_demand` | `one_off` jobs have one visit, `recurring` jobs repeat, `on_demand` jobs (snow removal) get a visit per storm. | | `cadenceFrequency` | integer or null | For recurring jobs, how many visits per `cadencePeriod`; null otherwise. | | `cadencePeriod` | `per_week`, `per_month`, `per_year`, `per_day` or null | For recurring jobs, the period `cadenceFrequency` counts in; null otherwise. | | `priceStructure` | `per_hour`, `per_sqft`, `flat`, `per_man_hour` | How the job is priced: `flat`, `per_hour`, `per_sqft`, or `per_man_hour`. | | `rate` | number | The price per unit, in US dollars. | | `quantity` | number or null | The units priced (hours, square feet, or 1 for a flat price). | | `subtotal` | number | The price per visit, in US dollars (`rate` × `quantity`). | | `teamId` | id or null | The job's own crew (for a recurring job, its owner). Visits with no crew of their own inherit it. Null when the job has no crew. | | `effectiveTeamId` | id or null | The crew doing the job's next visit: that visit's own crew when it has one, otherwise `teamId`. Equals `teamId` when the job has no upcoming visit. | | `nextVisitId` | id or null | The job's next visit on or after today, when it has one. | | `nextVisitDate` | date or null | The next visit's date, `YYYY-MM-DD` in the workspace's timezone, or null. | | `pausedUntil` | date or null | For a job paused until a date, that date (`YYYY-MM-DD`); null when it is paused indefinitely or not paused. | | `pauseReason` | string or null | Why the job was paused, when a reason was given. | | `previousVersionJobId` | id or null | When a price change replaced an earlier job with this one, the earlier job's id. | | `effectiveUntilDate` | date or null | When a price change replaced this job with a newer one, the last date this job covers (`YYYY-MM-DD`); null for the current job. | | `externalReferences` | array of objects | Ids this job has in your other systems, set with `externalReference`, the external upsert, or a link. | | `externalReferences[].source` | string | The system the id comes from. | | `externalReferences[].externalId` | string | The object's id in that system. | | `createdAt` | timestamp | When the job was created, ISO 8601 in UTC. | | `updatedAt` | timestamp | When the job last changed, ISO 8601 in UTC. | ## Example ```json { "id": "1f07ba26-1b51-456d-879c-30b413e66bfb", "object": "job", "name": "Weekly mowing", "description": null, "status": "scheduled", "customerId": "9ea5c382-9aef-4ec9-873a-3a1093847557", "propertyId": "78eb443d-7535-4f84-817f-bacb6dc9f612", "address": "412 Elm St, Bozeman, MT 59715", "serviceId": "b1926741-addc-4288-8a26-ddcfa6711916", "estimateId": null, "cadence": "recurring", "cadenceFrequency": 1, "cadencePeriod": "per_week", "priceStructure": "per_hour", "rate": 45, "quantity": 1, "subtotal": 45, "teamId": "606582dd-5caf-4e24-88f9-f96b554434b2", "effectiveTeamId": "5fa65e64-5bf0-49ab-883a-d4f254851039", "nextVisitId": "4b6a8b30-47b4-4677-83ff-01be40493d05", "nextVisitDate": "2026-10-20", "pausedUntil": null, "pauseReason": null, "previousVersionJobId": null, "effectiveUntilDate": null, "externalReferences": [ { "source": "mywebsite", "externalId": "contact-58213" } ], "createdAt": "2026-10-16T17:04:12.381Z", "updatedAt": "2026-10-16T17:04:12.381Z" } ``` ## Endpoints | Endpoint | What it does | | --------------------------------------------------- | --------------------------------- | | `GET /v1/jobs` | List jobs | | `POST /v1/jobs` | Create jobs from services | | `GET /v1/jobs/{id}` | Get a job | | `PATCH /v1/jobs/{id}` | Update a job | | `POST /v1/jobs/{id}/cancel` | Cancel a job | | `PUT /v1/jobs/{id}/external-references/{source}` | Link a job to your id | | `DELETE /v1/jobs/{id}/external-references/{source}` | Unlink a job from your id | | `POST /v1/jobs/{id}/pause` | Pause a job | | `POST /v1/jobs/{id}/resume` | Resume a job | | `POST /v1/jobs/{id}/schedule` | Schedule a job | | `GET /v1/jobs/external/{source}/{externalId}` | Get a job by your id | | `PUT /v1/jobs/external/{source}/{externalId}` | Create or update a job by your id |