The Blue Collar Lead API.

Get a key

Keys belong to one company. An owner of a Blue Collar Lead account makes them:

1. Sign in, open Connections in the menu, and find API and webhooks.
2. Press Make an API key, name it after the app that will use it, and tick only the permissions it needs.
3. Copy the key. It starts with bcl_live_ and is shown once; we keep only a fingerprint of it.

Make one key per app, so you can turn one off without breaking the others. A key that is turned off stops working at once.

No key can reach a company's settings, billing, logins or other keys, and no key can see another company.

Authentication

Send the key in the Authorization header on every request. Keep it on your server: a key does not belong in a web page or a mobile app.

curl https://www.bluecollarlead.com/api/v1/me \
  -H "Authorization: Bearer bcl_live_..."

{
  "company": { "id": "client-7f3a91c2", "name": "Peachtree Roofing Co.", "timezone": "America/New_York" },
  "api_key": { "name": "Office CRM sync", "prefix": "bcl_live_Xk3Q9a", "scopes": ["contacts:read", "jobs:write"] }
}

Basics

• Base URL: https://www.bluecollarlead.com/api/v1. Always use www; the bare domain redirects.
• Send and receive JSON. Send Content-Type: application/json with a body.
• Times are ISO 8601 in UTC, like 2026-10-19T18:05:00Z. Phone numbers come back in E.164, like +14045550101; send them in any common format.
• Creating a contact or a job takes an Idempotency-Key header (8 to 200 letters, digits, dots, dashes, colons or underscores). Retry with the same key and the record is created once.
• The whole API is described in openapi.json. Import it into Postman or Insomnia to try every call.

Errors

Every error has the same shape, with a status code that matches:

{ "error": { "code": "missing_scope", "message": "This API key does not have the \"jobs:write\" permission." } }

Lists and syncing

Lists return newest first, 25 at a time (up to 100 with ?limit=). When has_more is true, ask again with ?cursor= set to the next_cursor you were given.

To keep another system in step, remember when you last synced and ask only for what changed since: ?updated_since=2026-10-19T00:00:00Z. Webhooks tell you the moment something happens; a sync on a schedule catches anything a webhook missed.

curl "https://www.bluecollarlead.com/api/v1/contacts?updated_since=2026-10-19T00:00:00Z&limit=100" \
  -H "Authorization: Bearer bcl_live_..."

Rate limits

Each key may make 120 requests a minute. Every answer carries RateLimit and RateLimit-Policy headers; past the limit you get a 429 until the window resets. Page through big lists with limit=100 rather than fetching records one at a time.

Endpoints

Every field of every record is in the OpenAPI spec.

Jobs, in practice

A job made through the API is made exactly like one typed in on the board: it is checked, linked to the contact with that phone number (or a new one), numbered when it passes the lead stage, and the assigned person is told.

curl -X POST https://www.bluecollarlead.com/api/v1/jobs \
  -H "Authorization: Bearer bcl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-58213" \
  -d '{
    "title": "Roof replacement",
    "contact": { "name": "Jordan Lee", "phone": "404-555-0101" },
    "address": "412 Maple Ridge Dr, Roswell, GA",
    "value": 18500,
    "assigned_to": "emp-1",
    "note": "Wants GAF Timberline, charcoal."
  }'

curl -X POST https://www.bluecollarlead.com/api/v1/jobs/4229/stage \
  -H "Authorization: Bearer bcl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "stage": "sold" }'

Use GET /pipelines for the stage keys of each board, and GET /team for the ids to put in assigned_to. Custom fields go in fields, by the field's key.

Leads

POST /leads is the same door as a website form. The lead is checked for bots, spam and the do-not-call list, a job is made on the board, and the AI calls or texts within the company's calling hours and daily limit. The same number twice within 10 minutes counts once.

curl -X POST https://www.bluecollarlead.com/api/v1/leads \
  -H "Authorization: Bearer bcl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Casey Morgan", "phone": "678-555-0144", "address": "9 Elm Rd, Marietta, GA",
        "service": "Roof repair", "message": "Leak over the kitchen after the storm." }'

Only send people who asked to be contacted. For a customer you already work with, use POST /contacts or POST /jobs, which never call anyone.

Webhooks

Subscribe an https URL on your system to the events you care about. We POST JSON to it within seconds of the event.

curl -X POST https://www.bluecollarlead.com/api/v1/webhooks \
  -H "Authorization: Bearer bcl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/bcl", "events": ["job.created", "job.stage_changed"] }'

The answer includes a secret (whsec_...) shown only then. Owners can also add webhooks from the app.

What arrives

POST /hooks/bcl
X-BCL-Event: job.stage_changed
X-BCL-Delivery: dlv_Q2x7mK0aP1sT
X-BCL-Signature: sha256=5f0c...

{
  "id": "dlv_Q2x7mK0aP1sT",
  "event": "job.stage_changed",
  "created_at": "2026-10-19T18:05:02.114Z",
  "data": { "job": { "id": 4229, "stage": { "key": "sold", "label": "Approved" } }, "from_stage": "quoted", "to_stage": "sold" }
}

• Answer with any 2xx within 8 seconds. Do the slow work after you answer.
• We retry up to 4 times over about 30 seconds after a timeout, a 408, a 429 or a 5xx. Other answers are not retried.
• X-BCL-Delivery is the same on every retry, so you can ignore a repeat.
• After 100 failed deliveries in a row we turn the subscription off. Add it again once your end is fixed.
• Addresses that point at private networks are refused.

Verifying a webhook

Compute an HMAC-SHA256 of the raw request body with your secret, and compare it with X-BCL-Signature in constant time. Use the raw bytes, before any JSON parsing.

const crypto = require('crypto');

function verified(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(String(header || ''));
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hmac, hashlib

def verified(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

Rules worth knowing

• Stages move with their side effects. Moving a job to the company's finished stage can queue the customer's review request and push the job to their connected CRM, exactly like dragging the card. That is why the stage changes only through POST /jobs/{id}/stage, never PATCH.
• Jobs from a connected CRM (GoHighLevel, JobTread) belong to that CRM. Moving them answers 409; change them there and they sync back.
• Phone numbers tie the system together. A contact's phone cannot be changed through the API, because calls, texts and jobs find a person by it.
• Appointments are read only in this version. The AI books them against the company's calendars and rules; send a lead or create a job and the company takes it from there.
• Download links expire. File links work for 15 minutes. Ask for the file list again to get fresh ones.

Versions and help

This is version 1. Within it we only add things: new fields, new endpoints, new events. We never rename or remove a field, so ignore fields you do not know. Anything that would break an integration gets a new version, and the old one keeps working while you move.

Questions, or something you need the API to do: [email protected].