Leads
Leads in the BlueSuite REST API
Create a contact, optionally create and link a property, then create a request in one call. All three write scopes are required, including properties:write when no property is supplied. The response includes contact_id, property_id, request_id, and the created records.
The contact defaults to type lead unless supplied explicitly. The request's contact and property links are set from the newly created records. This flow does not deduplicate against existing contacts and is not a database transaction; inspect the workspace before retrying a failed request. For an existing customer, use the individual contact/property/request endpoints.
Example: capture an inquiry
curl 'https://my.bluesuite.app/api/v1/leads' \
-H "Authorization: Bearer $BLUESUITE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"contact":{"first_name":"Jamie","last_name":"Rivera","email":"jamie@example.com"},"request":{"name":"Annual HVAC maintenance","details":"Please contact me to schedule."}}'POST /api/v1/leads
POST /api/v1/leadsRequired scopes: contacts:write, properties:write, requests:write.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
contact | object | Yes | |
contact.first_name | string | No | Default: "". |
contact.last_name | string | No | Default: "". |
contact.email | string or null | No | |
contact.phone | string or null | No | |
contact.secondary_email | string or null | No | |
contact.secondary_phone | string or null | No | |
contact.company | string or null | No | |
contact.company_department | string or null | No | |
contact.company_position | string or null | No | |
contact.title | "mr", "mrs", "miss", "ms", "dr", "prof", "rev" or null | No | |
contact.type | "none", "customer", "lead", "former_customer", "contractor", "partner", "vendor", "other" | No | Default: "none". |
contact.owner_id | string or null | No | |
contact.info | JSON value or null | No | |
contact.custom_fields | JSON value or null | No | |
property | object | No | |
property.address | object | When parent supplied | |
property.address.street | string | No | Default: "". |
property.address.street_2 | string | No | Default: "". |
property.address.city | string | No | Default: "". |
property.address.state | string | No | Default: "". |
property.address.postal_code | string | No | Default: "". |
property.address.country | string | No | Default: "". |
property.property_type | "single-family", "apartment", "complex", "townhouse", "land", "commercial", "other" | No | Default: "single-family". |
property.role | "owner", "tenant", "manager", "agent", "other" | No | Default: "owner". |
request | object | Yes | |
request.name | string or null | No | |
request.contact_id | integer or null | No | |
request.property_id | integer or null | No | |
request.assignee_id | string or null | No | |
request.details | string or null | No | |
request.assessment | string or null | No | |
request.requested_on | string | No | Pattern: ^\d{4}-\d{2}-\d{2}$. |
request.status | "new", "responded", "overdue", "converted", "rejected", "archived" | No | Default: "new". |
request.data | JSON value or null | No | |
request.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.