REST API v1 Overview

Access contacts, quotes, jobs, invoices, events, and timesheets via the BlueSuite REST API

The REST API v1 provides full CRUD access to your BlueSuite workspace data. Use it to manage contacts, requests, quotes, jobs, invoices, events, and timesheets programmatically, and to attach files to any of them.

Base URL

All REST API v1 requests should be made to:

https://app.bluesuite.com/api/v1

Authentication

All requests require a valid API key passed as a Bearer token in the Authorization header. See the Authentication guide for details on creating and managing API keys.

curl -X GET https://app.bluesuite.com/api/v1/contacts \
  -H "Authorization: Bearer wk_a1b2c3d4.your_secret_key"

Your API key must have the appropriate scopes for the resource you are accessing. For example, listing contacts requires the contacts:read scope, while creating a contact requires contacts:write.

Response Format

Single Resource

{
  "success": true,
  "data": {
    "id": "abc-123",
    "name": "John Smith",
    "email": "john@example.com"
  }
}

List of Resources

{
  "success": true,
  "data": [
    { "id": "abc-123", "name": "John Smith" },
    { "id": "def-456", "name": "Jane Doe" }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_pages": 4
  }
}

Common Query Parameters

All list endpoints support the following optional query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number for pagination
`per_page`	integer	`25`	Number of results per page (max 100)
`search`	string	-	Search term to filter results
`sort_by`	string	-	Field to sort by (varies by resource)
`sort_direction`	string	`asc`	Sort direction: `asc` or `desc`

Example

curl -X GET "https://app.bluesuite.com/api/v1/contacts?page=2&per_page=10&search=smith&sort_by=name&sort_direction=asc" \
  -H "Authorization: Bearer wk_a1b2c3d4.your_secret_key"

Error Responses

All error responses include a success: false field and an error message:

{
  "success": false,
  "error": "Description of what went wrong"
}

HTTP Status Codes

Status Code	Meaning	Description
`400`	Bad Request	Invalid request body or query parameters
`401`	Unauthorized	Missing or malformed `Authorization` header
`403`	Forbidden	Invalid API key or insufficient scopes
`404`	Not Found	The requested resource does not exist
`500`	Internal Server Error	An unexpected error occurred on the server

Error Examples

400 - Validation Error

{
  "success": false,
  "error": "Validation failed: \"email\" must be a valid email address"
}

401 - Missing Authentication

{
  "success": false,
  "error": "Missing authorization header"
}

403 - Insufficient Permissions

{
  "success": false,
  "error": "Insufficient permissions. Required scope: contacts:write"
}

404 - Not Found

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

500 - Server Error

{
  "success": false,
  "error": "Internal server error"
}

Available Resources

Resource	Endpoint	Description
Contacts	`/api/v1/contacts`	Manage customer contacts and their properties
Requests	`/api/v1/requests`	Create and manage customer requests
Quotes	`/api/v1/quotes`	Create and manage quotes
Jobs	`/api/v1/jobs`	Create and manage jobs
Invoices	`/api/v1/invoices`	Create and manage invoices
Events	`/api/v1/events`	Schedule and manage events
Timesheets	`/api/v1/timesheets`	Track time entries and manage timesheets
Uploads	`/api/v1/uploads`	Attach files (receipts, photos, PDFs) to any entity
Notifications	`/api/v1/notifications`	Send quotes/invoices/reminders to customers via email and SMS
Comments	`/api/v1/comments`	Post and read internal comments on any entity, with @-mentions and replies

Each resource supports standard CRUD operations. Refer to the individual resource pages for detailed endpoint documentation, request/response schemas, and examples.

On this page