Who is the API for?

The BlueSales API lets developers integrate AI calling directly into their own applications — CRMs, sales tools, scheduling systems, or internal dashboards. Instead of creating Blues manually, you can provision them, add leads, and trigger calls via HTTP requests.

Step 1 — Generate an API key

  1. Go to Dashboard → API.
  2. Click Generate New Key.
  3. Give the key a label (e.g. "CRM Integration" or "Production App").
  4. Copy the key immediately — it will only be shown once. Store it securely (e.g. in an environment variable, not hardcoded in source code).

You can generate multiple keys and revoke individual ones without affecting others — useful for isolating different integrations.

Step 2 — Authenticate requests

All API requests must include your key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

All requests and responses use JSON. The base URL is:

https://bluesales.ai/api/v1

Step 3 — Core endpoints

List your Blues

GET /blues

Returns all Blues in your account with their ID, name, type, role, and status.

Create a Blue

POST /blues

Request body example:

{
  "name": "Sales Campaign — Q2",
  "type": "outbound",
  "role": "sales",
  "business_profile_id": "bp_xxxxxxxxxxxx",
  "phone_number_id": "pn_xxxxxxxxxxxx",
  "brain_id": "br_xxxxxxxxxxxx"
}

The response includes the new Blue's id, which you can use in subsequent calls.

Get a specific Blue

GET /blues/{blue_id}

Add a lead to a list

POST /leads
{
  "lead_list_id": "ll_xxxxxxxxxxxx",
  "phone": "+12025550147",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "notes": "Interested in enterprise plan"
}

List available phone numbers

GET /phone-numbers

Returns your provisioned numbers. Use the id field when creating a Blue.

Step 4 — Error handling

The API returns standard HTTP status codes:

  • 200 / 201 — Success
  • 400 — Bad request (check your request body for missing or invalid fields)
  • 401 — Unauthorized (invalid or missing API key)
  • 404 — Resource not found
  • 429 — Rate limit exceeded (default: 100 requests per minute)
  • 500 — Server error (retry with exponential backoff)

Error responses include a JSON body with a message field explaining what went wrong:

{
  "error": "validation_failed",
  "message": "phone_number_id is required when creating an outbound Blue"
}

Step 5 — Using the API logs

Every API call is logged under Dashboard → API → Logs. Each log entry shows the endpoint, HTTP method, status code, timestamp, and request/response payload. Use this to debug integration issues without needing server-side logging.

Example: Full automation flow

A typical CRM integration might work like this:

  1. A new lead is created in your CRM.
  2. Your CRM webhook fires and calls POST /leads to add them to a BlueSales lead list.
  3. Your active outbound Blue picks up the new lead during the next calling window and dials them automatically.
  4. The call outcome is written back to BlueSales logs, which your CRM polls via GET /blues/{id}/calls.

Rate limits and best practices

  • The default rate limit is 100 requests per minute per API key.
  • For bulk lead imports, use CSV import in the dashboard rather than calling POST /leads in a loop.
  • Cache resource IDs (Blue IDs, phone number IDs, brain IDs) in your system — don't fetch them on every request.
  • Rotate API keys periodically, especially after team member offboarding.

Full API reference

For a complete list of endpoints, parameters, and response schemas, visit the API Reference in your dashboard.