Jobs

List Jobs

Retrieve a paginated list of jobs.

GET /api/v1/jobs

Required Scope: jobs:read

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`25`	Results per page (1-100)
`search`	string		Search filter
`sort_by`	string		Field to sort by
`sort_direction`	string	`desc`	Sort direction (`asc` or `desc`)
`contact_id`	integer		Filter by contact ID
`quote_id`	integer		Filter by quote ID
`status`	string		Comma-separated list of statuses to filter by (e.g. `scheduled,in_progress`). Options: `draft`, `scheduled`, `in_progress`, `completed`, `cancelled`

curl https://app.bluesuite.com/api/v1/jobs?page=1&per_page=10&contact_id=42&status=scheduled,in_progress \
  -H "Authorization: Bearer wk_YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": 1,
      "number": 3001,
      "name": "Window cleaning job",
      "status": "scheduled",
      "type": "one-off",
      "contact_id": 42,
      "total": 475.20,
      "created_at": "2025-03-15T08:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total_pages": 1
  }
}

Create Job

Create a new job. The number is auto-generated.

POST /api/v1/jobs

Required Scope: jobs:write

Request Body:

Field	Type	Required	Description
`name`	string	No	Name or title of the job
`contact_id`	integer	No	ID of the associated contact
`property_id`	integer	No	ID of the associated property
`request_id`	integer	No	ID of the originating request
`quote_id`	integer	No	ID of the originating quote
`salesperson_id`	string (UUID)	No	ID of the assigned salesperson
`line_items`	array	No	Array of line item objects (see Line Items)
`discount`	number	No	Discount amount. Defaults to `0`
`discount_unit`	string	No	Discount unit: `%` or `$`. Defaults to `%`
`deposit`	number	No	Required deposit amount. Defaults to `0`
`deposit_unit`	string	No	Deposit unit: `%` or `$`. Defaults to `%`
`tax_rate`	number	No	Tax rate percentage. Defaults to `0`
`tax_rate_id`	integer	No	ID of a saved tax rate
`total`	number	No	Job total. Defaults to `0`
`status`	string	No	One of: `draft`, `scheduled`, `in_progress`, `completed`, `cancelled`. Defaults to `draft`
`type`	string	No	Job type: `one-off` or `recurring`. Defaults to `one-off`
`expected_end_date`	string	No	Expected completion date
`expenses`	array	No	Array of expense objects
`custom_fields`	any	No	Custom field values

curl -X POST https://app.bluesuite.com/api/v1/jobs \
  -H "Authorization: Bearer wk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Window cleaning job",
    "contact_id": 42,
    "quote_id": 1,
    "line_items": [
      { "name": "Exterior window cleaning", "quantity": 12, "unitPrice": 25.00 },
      { "name": "Interior window cleaning", "quantity": 12, "unitPrice": 15.00 }
    ],
    "discount": 10,
    "discount_unit": "%",
    "tax_rate": 10,
    "total": 475.20,
    "status": "scheduled",
    "type": "one-off"
  }'

{
  "success": true,
  "data": {
    "id": 1,
    "number": 3001,
    "name": "Window cleaning job",
    "contact_id": 42,
    "quote_id": 1,
    "status": "scheduled",
    "type": "one-off",
    "line_items": [
      { "_type": "lineItem", "id": "a1b2c3d4-...", "name": "Exterior window cleaning", "description": null, "quantity": 12, "unitPrice": 25.00 },
      { "_type": "lineItem", "id": "e5f6a7b8-...", "name": "Interior window cleaning", "description": null, "quantity": 12, "unitPrice": 15.00 }
    ],
    "discount": 10,
    "discount_unit": "%",
    "tax_rate": 10,
    "total": 475.20,
    "workspace_id": 123,
    "created_at": "2025-03-15T08:00:00.000Z"
  }
}

Get Job

Retrieve a single job by ID. Returns the expanded job with related data.

GET /api/v1/jobs/:id

Required Scope: jobs:read

curl https://app.bluesuite.com/api/v1/jobs/1 \
  -H "Authorization: Bearer wk_YOUR_API_KEY"

{
  "success": true,
  "data": {
    "id": 1,
    "number": 3001,
    "name": "Window cleaning job",
    "status": "scheduled",
    "type": "one-off",
    "contact_id": 42,
    "property_id": 7,
    "request_id": 1,
    "quote_id": 1,
    "salesperson_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "line_items": [
      { "_type": "lineItem", "id": "a1b2c3d4-...", "name": "Exterior window cleaning", "description": null, "quantity": 12, "unitPrice": 25.00 },
      { "_type": "lineItem", "id": "e5f6a7b8-...", "name": "Interior window cleaning", "description": null, "quantity": 12, "unitPrice": 15.00 }
    ],
    "discount": 10,
    "discount_unit": "%",
    "deposit": 0,
    "deposit_unit": "%",
    "tax_rate": 10,
    "total": 475.20,
    "expected_end_date": null,
    "expenses": [],
    "workspace_id": 123,
    "created_at": "2025-03-15T08:00:00.000Z"
  }
}

Update Job

Update an existing job. All fields are optional -- only include the fields you want to change.

PUT /api/v1/jobs/:id

Required Scope: jobs:write

Request Body:

All fields from Create Job are accepted. Only provided fields will be updated.

curl -X PUT https://app.bluesuite.com/api/v1/jobs/1 \
  -H "Authorization: Bearer wk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "expected_end_date": "2025-03-20"
  }'

{
  "success": true,
  "data": {
    "id": 1,
    "number": 3001,
    "name": "Window cleaning job",
    "status": "in_progress",
    "type": "one-off",
    "expected_end_date": "2025-03-20",
    "total": 475.20,
    "workspace_id": 123,
    "created_at": "2025-03-15T08:00:00.000Z"
  }
}

Delete Job

Delete a job by ID.

DELETE /api/v1/jobs/:id

Required Scope: jobs:write

curl -X DELETE https://app.bluesuite.com/api/v1/jobs/1 \
  -H "Authorization: Bearer wk_YOUR_API_KEY"

{
  "success": true,
  "data": {
    "deleted": true
  }
}

Update Job Status

Update only the status of a job.

PUT /api/v1/jobs/:id/status

Required Scope: jobs:write

Request Body:

Field	Type	Required	Description
`status`	string	Yes	One of: `draft`, `scheduled`, `in_progress`, `completed`, `cancelled`

curl -X PUT https://app.bluesuite.com/api/v1/jobs/1/status \
  -H "Authorization: Bearer wk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed"
  }'

{
  "success": true,
  "data": {
    "id": 1,
    "number": 3001,
    "name": "Window cleaning job",
    "status": "completed",
    "workspace_id": 123
  }
}

Line Items

Line items represent individual services or products on a job. When creating or updating a job, provide line items in this format:

Field	Type	Required	Description
`name`	string	Yes	Item name
`description`	string	No	Additional description
`quantity`	number	No	Quantity (default: 1)
`unitPrice`	number	Yes	Unit price
`taxable`	boolean	No	Whether the item is taxable
`optional`	boolean	No	Whether the item is optional

The API automatically assigns each line item a unique id and _type field. Response objects will include these generated fields.

{
  "line_items": [
    { "name": "Exterior window cleaning", "quantity": 12, "unitPrice": 25.00 },
    { "name": "Interior window cleaning", "quantity": 12, "unitPrice": 15.00, "description": "Includes screens" }
  ]
}

List Jobs

Create Job

Get Job

Update Job

Delete Job

Update Job Status

Line Items

On this page