--- title: "Create a job" method: POST path: "/v1/jobs" tags: ["Jobs"] --- # Create a job `POST /v1/jobs` ## Request - Base URL: `https://api.workwing.io` - URL: `https://api.workwing.io/v1/jobs` - Auth: HTTP bearer Create a new job with optional custom fields and job type field validation. Pass exactly one of `customer_id` or `project_id`. With `project_id` the job is created as one of that project's jobs: customer, brand and default location are inherited, and the job joins the project's pool unscheduled unless `scheduled_start`/`scheduled_end` pin it to its own window. `location_id` is the site the work happens at and must be one of the job customer's locations. Left out, it falls back to the project's location and then to the customer's primary location. `parent_job_id` and `kind` are never accepted as input. `operator_form_data` and `resource_form_data` are keyed by job type field id and validated against the job type. A number field takes a JSON number (numeric text such as `"12.5"` is accepted and stored as a number). A signature field takes `{ "dataUri": "data:image/png;base64,...", "capturedAt": "" }` (a bare data URI string is accepted and stored in that shape, stamped with the request time). A file field takes an array of file metadata objects or URLs (a single one is accepted and stored as a one-item array). Scopes: `create:jobs` and `read:jobs` (the created job is read back in the response). ## Headers - `Idempotency-Key` string, required ## Request body - object - `customer_id` string, uuid - `project_id` string, uuid - `parent_job_id` unknown - `kind` unknown - `template_id` string, uuid, required - `location_id` string, uuid - `title` string - `notes` string - `internal_notes` string - `status` 'T_PENDING' | 'T_SCHEDULED' | 'T_ASSIGNED' | 'T_IN_PROGRESS' | 'T_ON_HOLD' | 'T_INCOMPLETE' | 'T_REBOOK' | 'T_COMPLETED' | 'T_CANCELLED' | 'T_FAILED' - `status_notes` string - `priority` 'T_LOW' | 'T_NORMAL' | 'T_HIGH' | 'T_URGENT' - `scheduled_start` string, date-time - `scheduled_end` string, date-time - `assigned_resource_id` string, uuid - `resource_group_id` string, uuid - `custom_fields` object - `operator_form_data` object - `resource_form_data` object ## Response `201` Default Response - object - `data` object, required: The created job - `id` string, uuid, required - `brand_id` string, uuid, required - `customer_id` string, uuid, required - `location_id` string, uuid, nullable, required - `template_id` string, uuid, nullable, required - `created_by_user_id` string, uuid, required - `resource_group_id` string, uuid, nullable, required - `parent_job_id` string, uuid, nullable, required: The project this job belongs to, if any. - `job_schedule_id` string, uuid, nullable, required: The recurring schedule that generated this job, if any. - `source_observation_id` string, uuid, nullable, required: The field observation this job was raised from, if any. - `job_number` string, nullable, required - `title` string, nullable, required - `kind` 'T_STANDARD' | 'T_PROJECT', required: `T_PROJECT` owns a pool of jobs; `T_STANDARD` is an ordinary job, which is also what each job in a project is. - `status` 'T_PENDING' | 'T_SCHEDULED' | 'T_ASSIGNED' | 'T_IN_PROGRESS' | 'T_ON_HOLD' | 'T_INCOMPLETE' | 'T_REBOOK' | 'T_COMPLETED' | 'T_CANCELLED' | 'T_FAILED', required - `status_notes` string, nullable, required - `status_reason_code` string, nullable, required - `priority` string, nullable, required: One of T_LOW, T_NORMAL, T_HIGH, T_URGENT. - `source` 'T_WEB' | 'T_API' | 'T_IMPORT', required: Where the job was created: in the app, through the API, or by a CSV import. - `notes` string, nullable, required - `scheduled_start` string, date-time, nullable, required - `scheduled_end` string, date-time, nullable, required - `scheduled_instance_date` string, date, nullable, required: For a job generated by a recurring schedule, the occurrence date it was generated for, `YYYY-MM-DD`. - `is_schedule_locked` boolean, required - `route_sequence` integer, nullable, required - `started_at` string, date-time, nullable, required - `completed_at` string, date-time, nullable, required - `completion_locked` boolean, required - `sla_response_due_at` string, date-time, nullable, required - `sla_resolution_due_at` string, date-time, nullable, required - `child_count` integer, required: For a project, how many jobs it has. - `child_completed_count` integer, required: For a project, how many of its jobs are complete. - `operator_form_data` object, nullable, required: Operator form answers, keyed by job type field id. - `resource_form_data` object, nullable, required: Resource form answers, keyed by job type field id. - `operator_form_snapshot` object, nullable, required: The job type's operator form as it stood when the job was created. - `resource_form_snapshot` object, nullable, required: The job type's resource form as it stood when the job was created. - `resource_form_progress` object, nullable, required: Where the resource has got to in a multi-step form. - `integration_responses` object, nullable, required: Responses recorded by integrations that ran on the job. - `external_references` object[], required - `provider` string, required - `type` string, required - `ref` string, required - `url` string, uri - `tracking_id` string, required: The id in the job's customer tracking link. - `verification_code` string, nullable, required - `created_at` string, date-time, nullable, required - `updated_at` string, date-time, nullable, required - `project_id` string, uuid, nullable, required: The project this job belongs to, if any. The same value as parent_job_id. - `custom_fields` object, required: Custom field values keyed by field_key. Only fields that hold a value are listed. - `meta` object, required - `request_id` string, required - `timestamp` string, date-time, required --- [API](https://skmtc.dev/workwing/apis/workwing-api.md) · [All operations](https://skmtc.dev/workwing/apis/workwing-api/llms.txt) · [OpenAPI document](https://skmtc.dev/workwing/apis/workwing-api/revisions/54bb14368a35?raw)