---
title: "Start a job step"
method: POST
path: "/jobs/{job_id}/steps/{id}/start"
tags: ["Job Steps"]
---

# Start a job step

`POST /jobs/{job_id}/steps/{id}/start`

## Request

- Base URL: `https://api.shopvox.com/v1`
- URL: `https://api.shopvox.com/v1/jobs/{job_id}/steps/{id}/start`
- Auth: API key in query parameter `account_id` and API key in query parameter `authToken`
- TypeScript: <https://skmtc.dev/shopvox/apis/shopvox-public-api/docs/jobs/:job_id/steps/:id/start/post.ts> (a function with typed inputs; its response is checked against the schema)

**Plan: Paid API.**

## Response `200`

Started.

- JobStep: Returned by start/stop/complete. Includes the parent `job` (full Job object) and, when present, `nextStep`.
  - `id` string, uuid
  - `jobId` string, uuid
  - `name` string
  - `workflowState` string, nullable
  - `jobStageName` string, nullable
  - `isCompleted` boolean
  - `isStarted` boolean
  - `isIdling` boolean
  - `isStopped` boolean
  - `isPending` boolean
  - `isActive` boolean
  - `scheduledAt` string, date-time, nullable
  - `estimatedTime` number, nullable
  - `actualTime` number, nullable
  - `manualTime` number, nullable
  - `assignedType` string, nullable
  - `assignedTo` object[]
    - `id` string, uuid
    - `assignedToId` string, uuid
    - `assignedToType` string
    - `name` string, nullable
    - `initials` string, nullable
  - `machineId` string, uuid, nullable
  - `machine` NamedRef: Lightweight reference to a related record.
    - `id` string, uuid
    - `name` string
  - `nextStep` object: The next step in the job, when present. A fuller step-summary object (not just id/name) - includes scheduling and assignment fields. `assignedTo[]` items here carry `pictureUrl` instead of `initials`.
    - `id` string, uuid
    - `jobId` string, uuid
    - `name` string, nullable
    - `workflowState` string, nullable
    - `jobStageName` string, nullable
    - `isCompleted` boolean
    - `isStarted` boolean
    - `isActive` boolean
    - `scheduledFrom` string, date-time, nullable
    - `scheduledTo` string, date-time, nullable
    - `estimatedTime` number, nullable
    - `machineId` string, uuid, nullable
    - `machine` NamedRef: Lightweight reference to a related record.
      - `id` string, uuid
      - `name` string
  - `job` Job: A production job. `steps`/`lineItems` are present when applicable. The **list** endpoint (`GET /jobs`) returns a slightly different projection: it adds a nested `steps[]` array and an `installDate` field, and its `lineItems[]` omit `uom`. get-a-job and create return the shape documented here.
    - `id` string, uuid
    - `tags` NamedRef[]: Active tags of the record.
      - `id` string, uuid
      - `name` string
    - `active` boolean
    - `name` string
    - `description` string, nullable
    - `workflowState` string, nullable
    - `companyId` string, uuid, nullable
    - `contactId` string, uuid, nullable
    - `assignedToId` string, uuid, nullable
    - `productionManagerId` string, uuid, nullable
    - `salesRepId` string, uuid, nullable
    - `jobTemplateId` string, uuid, nullable
    - `orderId` string, uuid, nullable
    - `orderLineItemId` string, uuid, nullable
    - `orderNumber` string, nullable
    - `lineNumber` integer, nullable
    - `projectNumber` string, nullable
    - `priority` string, nullable
    - `quantity` number, nullable
    - `requireProofing` boolean, nullable
    - `hasOrder` boolean
    - `daysLeft` integer, nullable
    - `dueDate` string, date, nullable
    - `dueTime` string, nullable
    - `dueDateFrom` string, nullable
    - `dueDateTo` string, nullable
    - `dueDateTimeFrom` string, nullable
    - `dueDateTimeTo` string, nullable
    - `currentStageId` string, uuid, nullable
    - `currentStageName` string, nullable
    - `currentStepId` string, uuid, nullable
    - `currentStepName` string, nullable
    - `bomDetails` string, nullable
    - `designDetails` string, nullable
    - `productionDetails` string, nullable
    - `shippingDetails` string, nullable
    - `installDetails` string, nullable
    - `lastEvent` string, nullable
    - `lastEventAt` string, date-time, nullable
    - `currentProofUrl` string, nullable
    - `currentProofThumbnailUrl` string, nullable
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `divisionId` string, uuid, nullable
    - `division` NamedRef: Lightweight reference to a related record.
      - `id` string, uuid
      - `name` string
    - `company` NamedRef: Lightweight reference to a related record.
      - `id` string, uuid
      - `name` string
    - `contact` NamedRef: Lightweight reference to a related record.
      - `id` string, uuid
      - `name` string
    - `salesRep` Party: A person reference (sales rep, PM, designer) with initials.
      - `id` string, uuid
      - `name` string, nullable
      - `initials` string, nullable
    - `productionManager` Party: A person reference (sales rep, PM, designer) with initials.
      - `id` string, uuid
      - `name` string, nullable
      - `initials` string, nullable
    - `assignedTo` Party: A person reference (sales rep, PM, designer) with initials.
      - `id` string, uuid
      - `name` string, nullable
      - `initials` string, nullable
    - `projectManager` Party: A person reference (sales rep, PM, designer) with initials.
      - `id` string, uuid
      - `name` string, nullable
      - `initials` string, nullable
    - `designer` Party: A person reference (sales rep, PM, designer) with initials.
      - `id` string, uuid
      - `name` string, nullable
      - `initials` string, nullable
    - `lineItems` object[]
      - `id` string, uuid
      - `lineNumber` integer, nullable
      - `position` integer
      - `name` string, nullable
      - `description` string, nullable
      - `quantity` number, nullable
      - `workflowState` string, nullable
      - `uom` string, nullable

## Other responses

- `422`: Transition not allowed from the current state.

## Changes

- **2026-11-10** `eb2f6524de94`: 1 info
  - added the optional property `job/tags` to the response with the `200` status

[Operation history](https://skmtc.dev/shopvox/apis/shopvox-public-api/changes/jobs/:job_id/steps/:id/start/post.md)

---

[API](https://skmtc.dev/shopvox/apis/shopvox-public-api.md) - [All operations](https://skmtc.dev/shopvox/apis/shopvox-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shopvox/apis/shopvox-public-api/revisions/eb2f6524de94?raw)