# Create a Job

Creates a job and its Job folder. Starts in the not_started status. Name must be unique in the company.

Endpoint: POST /api/v1/jobs
Security: BearerAuth

## Request fields (application/json):

  - `name` (string, required)
    Name of the job. Must be unique within the company. Max 190 characters.

  - `notes` (string)
    Job notes. Max 4000 characters.

  - `start_date` (string)
    Date the job starts, as YYYY-MM-DD.
    Example: "2026-08-10"

  - `end_date` (string)
    Date the job is expected to be finished by, as YYYY-MM-DD.
    Example: "2026-08-14"

  - `external_job_link` (string)
    Link to this job in an external system.

  - `subfolders` (array)
    Subfolders to create inside the job folder, up to 25. After creation, manage folders through the items endpoints.

  - `subfolders.name` (string, required)
    Name of the subfolder.

  - `custom_field_values` (array)
    Custom field values to set. A job holds at most 2.

  - `custom_field_values.custom_field_id` (number, required)
    ID of the job custom field.

  - `custom_field_values.value` (string)
    The value to store. Max 191 characters.

  - `custom_field_values.version` (number)
    Version of the stored value. Pass it back unchanged when updating; omit when setting the field for the first time.

## Response 201 fields (application/json):

  - `data` (object)

  - `data.id` (number)

  - `data.name` (string)

  - `data.status` (string)

  - `data.folder_id` (number)

  - `data.custom_field_values` (array)

  - `data.custom_field_values.custom_field_id` (number)

  - `data.custom_field_values.value` (string,null)

  - `data.custom_field_values.version` (number,null)

  - `data.created_by` (object)

  - `data.updated_by` (object)

  - `data.created_at` (string)

  - `data.updated_at` (string)

  - `data.start_date` (string,null)

  - `data.end_date` (string,null)

  - `data.notes` (string,null)

  - `data.external_job_link` (string,null)

  - `data.started_at` (string,null)

  - `data.completed_at` (string,null)

## Response 400 fields (application/json):

  - `message` (string)

  - `errors` (object,null)

## Response 401 fields (application/json):

  - `message` (string)

  - `errors` (object,null)

## Response 409 fields (application/json):

  - `message` (string)

  - `errors` (object,null)

## Response 429 fields (application/json):

  - `message` (string)