Contacts, properties, and tasks
Contacts, properties, and tasks in the BlueSuite REST API
Contacts represent people and companies; properties represent service locations. Use contact IDs from this workspace and user UUIDs from Users. Contact creation defaults to type none; Leads defaults a newly created contact to lead.
Property operations under a contact create, update, or remove that contact's link to a property. Deleting the link does not mean deleting the property everywhere. GET /properties searches properties across the workspace.
Contact tasks have a title, optional due date and assignee, and optional recurring schedule. Reminders default to off. A recurring task needs a due date; a finite repeat duration needs a count, and a custom weekly/monthly pattern needs selected days. See recurring work for the shared pattern fields. Task status uses its dedicated endpoint. When updating a repeating task, choose the appropriate update_scope.
List contacts with any of a set of tags using tag_ids=1,2. A record carrying either tag matches. When no records match, the result is empty.
Example: create a contact
curl 'https://my.bluesuite.app/api/v1/contacts' \
-H "Authorization: Bearer $BLUESUITE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"first_name":"Jamie","last_name":"Rivera","email":"jamie@example.com","type":"customer"}'GET /api/v1/contacts
GET /api/v1/contactsRequired scopes: contacts: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". |
type | string | No | Filter by type. |
owner_id | string | No | Filter by owner UUID from GET /users. |
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/contacts
POST /api/v1/contactsRequired scopes: contacts:write.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
first_name | string | No | Default: "". |
last_name | string | No | Default: "". |
email | string or null | No | |
phone | string or null | No | |
secondary_email | string or null | No | |
secondary_phone | string or null | No | |
company | string or null | No | |
company_department | string or null | No | |
company_position | string or null | No | |
title | "mr", "mrs", "miss", "ms", "dr", "prof", "rev" or null | No | |
type | "none", "customer", "lead", "former_customer", "contractor", "partner", "vendor", "other" | No | Default: "none". |
owner_id | string or null | No | |
info | 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/properties
GET /api/v1/propertiesRequired scopes: properties: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". |
property_type | string | No | Property type. |
Response
200 with { "success": true, "data": [...], "pagination": { "page": 1, "per_page": 25, "total_pages": 1 } }.
See response conventions and errors.
GET /api/v1/contacts/:id
GET /api/v1/contacts/:idRequired scopes: contacts: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/contacts/:id
PUT /api/v1/contacts/:idRequired scopes: contacts:write.
Path parameters: id. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
first_name | string | No | Default: "". |
last_name | string | No | Default: "". |
email | string or null | No | |
phone | string or null | No | |
secondary_email | string or null | No | |
secondary_phone | string or null | No | |
company | string or null | No | |
company_department | string or null | No | |
company_position | string or null | No | |
title | "mr", "mrs", "miss", "ms", "dr", "prof", "rev" or null | No | |
type | "none", "customer", "lead", "former_customer", "contractor", "partner", "vendor", "other" | No | Default: "none". |
owner_id | string or null | No | |
info | 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/contacts/:id
DELETE /api/v1/contacts/:idRequired scopes: contacts: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.
GET /api/v1/contacts/:id/properties
GET /api/v1/contacts/:id/propertiesRequired scopes: properties:read.
Path parameters: id. Use positive integer record IDs from this workspace.
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". |
Response
200 with { "success": true, "data": [...], "pagination": { "page": 1, "per_page": 25, "total_pages": 1 } }.
See response conventions and errors.
POST /api/v1/contacts/:id/properties
POST /api/v1/contacts/:id/propertiesRequired scopes: properties:write.
Path parameters: id. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
address | object | Yes | |
address.street | string | No | Default: "". |
address.street_2 | string | No | Default: "". |
address.city | string | No | Default: "". |
address.state | string | No | Default: "". |
address.postal_code | string | No | Default: "". |
address.country | string | No | Default: "". |
property_type | "single-family", "apartment", "complex", "townhouse", "land", "commercial", "other" | No | Default: "single-family". |
role | "owner", "tenant", "manager", "agent", "other" | No | Default: "owner". |
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/contacts/:id/tasks
GET /api/v1/contacts/:id/tasksRequired scopes: contacts:read.
Path parameters: id. Use positive integer record IDs from this workspace.
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". |
status | string | No | Filter by status. |
Response
200 with { "success": true, "data": [...], "pagination": { "page": 1, "per_page": 25, "total_pages": 1 } }.
See response conventions and errors.
POST /api/v1/contacts/:id/tasks
POST /api/v1/contacts/:id/tasksRequired scopes: contacts:write.
Path parameters: id. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
title | string | Yes | minLength: 1. |
description | string or null | No | |
due_date | string or null | No | ISO timestamp. Reminders fire relative to this. |
assignee_id | string or null | No | |
reminders_enabled | boolean | No | Default: false. |
recurrence_type | "single", "recurring" | No | Default: "single". |
repeat_frequency | integer or null | No | |
repeat_frequency_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "weekly". |
repeat_frequency_unit_custom | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "weekly". |
repeat_frequency_schedule | object or null | No | |
repeat_frequency_schedule.days | array of integer | When parent supplied | |
repeat_frequency_schedule.type | "weekDays", "monthWeekDays", "monthDays" | When parent supplied | |
repeat_duration | integer or null | No | |
repeat_duration_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "forever". |
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/contacts/:id/properties/:propertyId
PUT /api/v1/contacts/:id/properties/:propertyIdRequired scopes: properties:write.
Path parameters: id, propertyId. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
address | object | No | |
address.street | string | No | Default: "". |
address.street_2 | string | No | Default: "". |
address.city | string | No | Default: "". |
address.state | string | No | Default: "". |
address.postal_code | string | No | Default: "". |
address.country | string | No | Default: "". |
property_type | "single-family", "apartment", "complex", "townhouse", "land", "commercial", "other" | No | |
role | "owner", "tenant", "manager", "agent", "other" | 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/contacts/:id/properties/:propertyId
DELETE /api/v1/contacts/:id/properties/:propertyIdRequired scopes: properties:write.
Path parameters: id, propertyId. 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.
GET /api/v1/contacts/:id/tasks/:taskId
GET /api/v1/contacts/:id/tasks/:taskIdRequired scopes: contacts:read.
Path parameters: id, taskId. 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/contacts/:id/tasks/:taskId
PUT /api/v1/contacts/:id/tasks/:taskIdRequired scopes: contacts:write.
Path parameters: id, taskId. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
title | string | No | minLength: 1. |
description | string or null | No | |
due_date | string or null | No | ISO timestamp. Reminders fire relative to this. |
assignee_id | string or null | No | |
reminders_enabled | boolean | No | Default: false. |
recurrence_type | "single", "recurring" | No | Default: "single". |
repeat_frequency | integer or null | No | |
repeat_frequency_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "weekly". |
repeat_frequency_unit_custom | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "weekly". |
repeat_frequency_schedule | object or null | No | |
repeat_frequency_schedule.days | array of integer | When parent supplied | |
repeat_frequency_schedule.type | "weekDays", "monthWeekDays", "monthDays" | When parent supplied | |
repeat_duration | integer or null | No | |
repeat_duration_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "forever". |
update_scope | "single", "all", "recreate" | 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/contacts/:id/tasks/:taskId
DELETE /api/v1/contacts/:id/tasks/:taskIdRequired scopes: contacts:write.
Path parameters: id, taskId. 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.
PUT /api/v1/contacts/:id/tasks/:taskId/status
PUT /api/v1/contacts/:id/tasks/:taskId/statusRequired scopes: contacts:write.
Path parameters: id, taskId. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
status | "open", "completed", "overdue" | 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.