Requests

Create and manage requests from existing contacts. For a new inquiry that also needs a contact and property, use Leads.

POST /requests/:id/convert creates a draft job, quote, or invoice carrying the request's contact and property, then marks the request converted. The result contains converted_to, the new record's id, and record. It does not send a quote or invoice to the customer. The invoice table does not retain a request ID link.

The list filter status accepts comma-separated values. tag_ids matches any selected tag.

Example: convert to a quote

curl 'https://my.bluesuite.app/api/v1/requests/42/convert' \
  -H "Authorization: Bearer $BLUESUITE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"to":"quote","name":"Spring maintenance"}'

GET /api/v1/requests

GET /api/v1/requests

Required scopes: requests:read.

Query parameters

Field	Type / accepted values	Required	Details
`page`	integer	No	Page number, starting at 1. Default: `1`.
`per_page`	integer	No	Records per page, from 1 to 100. Default: `25`. minimum: 1. maximum: 100.
`search`	string	No	Search text. maxLength: 100.
`sort_by`	string	No	Sort column. See the supported columns below when listed.
`sort_direction`	`"asc"`, `"desc"`	No	Sort direction. Default: `"desc"`.
`contact_id`	string	No	Filter by contact ID.
`status`	string	No	Filter by status.
`tag_ids`	string	No	Comma-separated tag IDs. Tags must match this resource type.

Response

200 with { "success": true, "data": [...], "pagination": { "page": 1, "per_page": 25, "total_pages": 1 } }.

See response conventions and errors.

POST /api/v1/requests

POST /api/v1/requests

Required scopes: requests:write.

JSON body

Field	Type / accepted values	Required	Details
`name`	string or null	No
`contact_id`	integer or null	No
`property_id`	integer or null	No
`assignee_id`	string or null	No
`details`	string or null	No
`assessment`	string or null	No
`requested_on`	string	No	Pattern: `^\d{4}-\d{2}-\d{2}$`.
`status`	`"new"`, `"responded"`, `"overdue"`, `"converted"`, `"rejected"`, `"archived"`	No	Default: `"new"`.
`data`	JSON value or null	No
`custom_fields`	JSON value or null	No

Unknown body fields are rejected. Conditional requirements are explained above.

Response

201 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

GET /api/v1/requests/:id

GET /api/v1/requests/:id

Required scopes: requests:read.

Path parameters: id. Use positive integer record IDs from this workspace.

Response

200 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

PUT /api/v1/requests/:id

PUT /api/v1/requests/:id

Required scopes: requests:write.

Path parameters: id. Use positive integer record IDs from this workspace.

JSON body

Field	Type / accepted values	Required	Details
`name`	string or null	No
`contact_id`	integer or null	No
`property_id`	integer or null	No
`assignee_id`	string or null	No
`details`	string or null	No
`assessment`	string or null	No
`requested_on`	string	No	Pattern: `^\d{4}-\d{2}-\d{2}$`.
`status`	`"new"`, `"responded"`, `"overdue"`, `"converted"`, `"rejected"`, `"archived"`	No	Default: `"new"`.
`data`	JSON value or null	No
`custom_fields`	JSON value or null	No

Unknown body fields are rejected. Conditional requirements are explained above.

Response

200 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

DELETE /api/v1/requests/:id

DELETE /api/v1/requests/:id

Required scopes: requests:write.

Path parameters: id. Use positive integer record IDs from this workspace.

No request body.

Response

200 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

POST /api/v1/requests/:id/convert

POST /api/v1/requests/:id/convert

Required scopes: requests:write.

Path parameters: id. Use positive integer record IDs from this workspace.

JSON body

Field	Type / accepted values	Required	Details
`to`	`"job"`, `"quote"`, `"invoice"`	Yes	What to create from this request.
`name`	string or null	No	Name for the new record. Defaults to the request name plus a suffix.

Unknown body fields are rejected. Conditional requirements are explained above.

Response

201 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

PUT /api/v1/requests/:id/status

PUT /api/v1/requests/:id/status

Required scopes: requests:write.

Path parameters: id. Use positive integer record IDs from this workspace.

JSON body

Field	Type / accepted values	Required	Details
`status`	`"new"`, `"responded"`, `"overdue"`, `"converted"`, `"rejected"`, `"archived"`	Yes

Unknown body fields are rejected. Conditional requirements are explained above.

Response

200 with { "success": true, "data": ... }. The data contains the result of the operation.

See response conventions and errors.

On this page