Contacts & Properties

The Contacts API lets you create, read, update, and delete contacts in your workspace. You can also manage properties (service addresses) linked to each contact.

Authentication

All endpoints require an API key with the appropriate scope. Pass your key in the Authorization header:

Authorization: Bearer wk_your_api_key

Contacts

List Contacts

Returns a paginated list of contacts in your workspace.

GET /api/v1/contacts

Required Scope: contacts:read

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`25`	Results per page (1-100)
`search`	string		Search contacts by name, email, or phone
`sort_by`	string		Field to sort by
`sort_direction`	string	`desc`	Sort direction: `asc` or `desc`
`type`	string		Filter by contact type: `none`, `customer`, `lead`, `former_customer`, `contractor`, `partner`, `vendor`, `other`
`owner_id`	string		Filter by owner user UUID

curl https://app.bluesuite.com/api/v1/contacts?page=1&per_page=10&type=customer \
  -H "Authorization: Bearer wk_your_api_key"

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "first_name": "John",
      "last_name": "Smith",
      "email": "john@example.com",
      "phone": "555-123-4567",
      "type": "customer",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total_pages": 3
  }
}

Create a Contact

Creates a new contact in your workspace.

POST /api/v1/contacts

Required Scope: contacts:write

Request Body:

Field	Type	Required	Description
`first_name`	string	Yes	Contact's first name
`last_name`	string	Yes	Contact's last name
`email`	string	No	Primary email address
`phone`	string	No	Primary phone number
`secondary_email`	string	No	Secondary email address
`secondary_phone`	string	No	Secondary phone number
`company`	string	No	Company name
`company_department`	string	No	Department within the company
`company_position`	string	No	Job title or position
`title`	string	No	Honorific: `mr`, `mrs`, `miss`, `ms`, `dr`, `prof`, `rev`
`type`	string	No	Contact type. Default: `none`. One of: `none`, `customer`, `lead`, `former_customer`, `contractor`, `partner`, `vendor`, `other`
`owner_id`	string (UUID)	No	ID of the workspace member who owns this contact
`info`	any	No	Arbitrary additional information
`custom_fields`	any	No	Custom field values

curl -X POST https://app.bluesuite.com/api/v1/contacts \
  -H "Authorization: Bearer wk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "phone": "555-123-4567",
    "type": "customer"
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "phone": "555-123-4567",
    "secondary_email": null,
    "secondary_phone": null,
    "company": null,
    "company_department": null,
    "company_position": null,
    "title": null,
    "type": "customer",
    "owner_id": null,
    "info": null,
    "custom_fields": null,
    "workspace_id": 123,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Get a Contact

Returns a single contact with expanded owner and created_by fields.

GET /api/v1/contacts/:id

Required Scope: contacts:read

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

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "phone": "555-123-4567",
    "type": "customer",
    "owner": {
      "id": "uuid",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "created_by": {
      "id": "uuid",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Update a Contact

Updates an existing contact. All fields are optional -- only include fields you want to change.

PUT /api/v1/contacts/:id

Required Scope: contacts:write

Request Body:

All fields from Create a Contact are accepted, and all are optional.

curl -X PUT https://app.bluesuite.com/api/v1/contacts/1 \
  -H "Authorization: Bearer wk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "555-999-0000",
    "type": "lead"
  }'

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "phone": "555-999-0000",
    "type": "lead",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:22:00.000Z"
  }
}

Delete a Contact

Permanently deletes a contact.

DELETE /api/v1/contacts/:id

Required Scope: contacts:write

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

Response:

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

Properties

Properties represent physical addresses linked to a contact. Each contact can have multiple properties, and each link includes a role describing the contact's relationship to that property.

List All Properties

Returns a paginated list of all properties across the workspace, regardless of which contact they belong to. Use this when you need to browse or search properties without knowing the contact.

GET /api/v1/properties

Required Scope: properties:read

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`25`	Results per page (1-100)
`search`	string		Search by street, city, state, or postal code
`sort_by`	string		Field to sort by: `id`, `property_type`, `created_at`, `modified_at`
`sort_direction`	string	`desc`	Sort direction: `asc` or `desc`
`property_type`	string		Filter by property type: `single-family`, `apartment`, `complex`, `townhouse`, `land`, `commercial`, `other`

curl https://app.bluesuite.com/api/v1/properties?search=Springfield \
  -H "Authorization: Bearer wk_your_api_key"

Response:

{
  "success": true,
  "data": [
    {
      "id": 10,
      "address": {
        "street": "123 Main St",
        "street_2": "",
        "city": "Springfield",
        "state": "IL",
        "postal_code": "62701",
        "country": "US"
      },
      "property_type": "single-family",
      "contact_ids": [1, 5],
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_pages": 1
  }
}

List Contact Properties

Returns a paginated list of properties linked to a specific contact.

GET /api/v1/contacts/:id/properties

Required Scope: properties:read

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`25`	Results per page (1-100)
`search`	string		Search properties by address
`sort_by`	string		Field to sort by
`sort_direction`	string	`desc`	Sort direction: `asc` or `desc`

curl https://app.bluesuite.com/api/v1/contacts/1/properties \
  -H "Authorization: Bearer wk_your_api_key"

Response:

{
  "success": true,
  "data": [
    {
      "id": 10,
      "address": {
        "street": "123 Main St",
        "street_2": "",
        "city": "Springfield",
        "state": "IL",
        "postal_code": "62701",
        "country": "US"
      },
      "property_type": "single-family",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_pages": 1
  }
}

Create a Property

Creates a new property and links it to the specified contact.

POST /api/v1/contacts/:id/properties

Required Scope: properties:write

Request Body:

Field	Type	Required	Description
`address`	object	Yes	The property address
`address.street`	string	No	Street address (default: `""`)
`address.street_2`	string	No	Street address line 2 (default: `""`)
`address.city`	string	No	City (default: `""`)
`address.state`	string	No	State or province (default: `""`)
`address.postal_code`	string	No	Postal or ZIP code (default: `""`)
`address.country`	string	No	Country (default: `""`)
`property_type`	string	No	Default: `single-family`. One of: `single-family`, `apartment`, `complex`, `townhouse`, `land`, `commercial`, `other`
`role`	string	No	Contact's role at this property. Default: `owner`. One of: `owner`, `tenant`, `manager`, `agent`, `other`

curl -X POST https://app.bluesuite.com/api/v1/contacts/1/properties \
  -H "Authorization: Bearer wk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "street": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701",
      "country": "US"
    },
    "property_type": "single-family",
    "role": "owner"
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": 10,
    "address": {
      "street": "123 Main St",
      "street_2": "",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701",
      "country": "US"
    },
    "property_type": "single-family",
    "workspace_id": 123,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Update a Property

Updates a property linked to a contact. All fields are optional -- only include fields you want to change. You can update the address, property type, and/or the contact's role at this property.

PUT /api/v1/contacts/:id/properties/:propertyId

Required Scope: properties:write

Request Body:

Field	Type	Required	Description
`address`	object	No	Updated address (same fields as create)
`property_type`	string	No	One of: `single-family`, `apartment`, `complex`, `townhouse`, `land`, `commercial`, `other`
`role`	string	No	Contact's role at this property. One of: `owner`, `tenant`, `manager`, `agent`, `other`

curl -X PUT https://app.bluesuite.com/api/v1/contacts/1/properties/10 \
  -H "Authorization: Bearer wk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "street": "456 Oak Ave",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62702",
      "country": "US"
    },
    "role": "tenant"
  }'

Response:

{
  "success": true,
  "data": {
    "id": 10,
    "address": {
      "street": "456 Oak Ave",
      "street_2": "",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62702",
      "country": "US"
    },
    "property_type": "single-family",
    "workspace_id": 123,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:22:00.000Z"
  }
}

Unlink a Property

Removes the link between a contact and a property. This does not delete the property itself.

DELETE /api/v1/contacts/:id/properties/:propertyId

Required Scope: properties:write

curl -X DELETE https://app.bluesuite.com/api/v1/contacts/1/properties/10 \
  -H "Authorization: Bearer wk_your_api_key"

Response:

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

Error Responses

When a request fails, the API returns a JSON error with success: false:

{
  "success": false,
  "error": "Contact not found"
}

Common HTTP status codes:

Status	Description
`400`	Bad request -- invalid or missing fields
`401`	Unauthorized -- missing or invalid API key
`403`	Forbidden -- API key lacks the required scope
`404`	Not found -- the contact or property does not exist
`422`	Validation error -- request body failed schema validation
`500`	Internal server error

Validation errors include a details field with specifics:

{
  "success": false,
  "error": "Validation failed",
  "details": [
    {
      "path": ["first_name"],
      "message": "First name is required"
    }
  ]
}

On this page