{"openapi":"3.1.0","info":{"title":"Blue Collar Lead API","version":"1.0.0","description":"Connect your own systems to Blue Collar Lead: contacts, jobs, appointments, calls, leads, job photos and reports, and webhooks. An owner makes an API key under Connections, API keys.","contact":{"name":"Blue Collar Lead","email":"info@bluecollarlead.com","url":"https://www.bluecollarlead.com/developers"}},"servers":[{"url":"https://www.bluecollarlead.com/api/v1"}],"security":[{"bearer":[]}],"paths":{"/me":{"get":{"summary":"The company and key you are using","tags":["Account"],"security":[{"bearer":[]}],"x-required-scope":null,"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/team":{"get":{"summary":"Active team members (to assign jobs)","tags":["Jobs"],"security":[{"bearer":[]}],"x-required-scope":"jobs:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pipelines":{"get":{"summary":"Boards and their stages","tags":["Jobs"],"security":[{"bearer":[]}],"x-required-scope":"jobs:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Pipeline"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts":{"get":{"summary":"List contacts","tags":["Contacts"],"security":[{"bearer":[]}],"x-required-scope":"contacts:read","parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page.","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"Only records changed at or after this ISO 8601 time. Use it to sync.","schema":{"type":"string","format":"date-time"}},{"name":"q","in":"query","required":false,"description":"Search name, email, company or address.","schema":{"type":"string"}},{"name":"phone","in":"query","required":false,"description":"Exact phone number.","schema":{"type":"string"}},{"name":"email","in":"query","required":false,"description":"Exact email.","schema":{"type":"string"}},{"name":"include_archived","in":"query","required":false,"description":"true to include archived contacts.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a contact","tags":["Contacts"],"security":[{"bearer":[]}],"x-required-scope":"contacts:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Send the same key on a retry and it is created once.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/{id}":{"get":{"summary":"Get a contact","tags":["Contacts"],"security":[{"bearer":[]}],"x-required-scope":"contacts:read","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a contact","tags":["Contacts"],"security":[{"bearer":[]}],"x-required-scope":"contacts:write","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs":{"get":{"summary":"List jobs","tags":["Jobs"],"security":[{"bearer":[]}],"x-required-scope":"jobs:read","parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page.","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"Only records changed at or after this ISO 8601 time. Use it to sync.","schema":{"type":"string","format":"date-time"}},{"name":"stage","in":"query","required":false,"description":"Stage key.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"open, won, lost or abandoned.","schema":{"type":"string"}},{"name":"pipeline_id","in":"query","required":false,"description":"Board id.","schema":{"type":"string"}},{"name":"assigned_to","in":"query","required":false,"description":"Team member id.","schema":{"type":"string"}},{"name":"contact_id","in":"query","required":false,"description":"Contact id.","schema":{"type":"string"}},{"name":"job_number","in":"query","required":false,"description":"Job number.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Search title, name, address or company.","schema":{"type":"string"}},{"name":"include_archived","in":"query","required":false,"description":"true to include archived jobs.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a job","tags":["Jobs"],"security":[{"bearer":[]}],"x-required-scope":"jobs:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Send the same key on a retry and it is created once.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{id}":{"get":{"summary":"Get a job","tags":["Jobs"],"security":[{"bearer":[]}],"x-required-scope":"jobs:read","parameters":[{"name":"id","in":"path","required":true,"description":"Job id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a job","tags":["Jobs"],"security":[{"bearer":[]}],"x-required-scope":"jobs:write","parameters":[{"name":"id","in":"path","required":true,"description":"Job id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{id}/stage":{"post":{"summary":"Move a job to another stage","tags":["Jobs"],"security":[{"bearer":[]}],"x-required-scope":"jobs:write","description":"Runs exactly like dragging the card on the board: when the company has turned them on, reaching the finished stage queues the review request and pushes the job to their CRM.","parameters":[{"name":"id","in":"path","required":true,"description":"Job id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["stage"],"properties":{"stage":{"type":"string","description":"Stage key from GET /pipelines."},"pipeline_id":{"type":"integer","description":"Move to another board."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{id}/notes":{"get":{"summary":"A job's notes","tags":["Jobs"],"security":[{"bearer":[]}],"x-required-scope":"jobs:read","parameters":[{"name":"id","in":"path","required":true,"description":"Job id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a note to a job","tags":["Jobs"],"security":[{"bearer":[]}],"x-required-scope":"jobs:write","parameters":[{"name":"id","in":"path","required":true,"description":"Job id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","description":"The note, up to 4,000 characters."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Note"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{id}/files":{"get":{"summary":"A job's photos, videos and documents","tags":["Files"],"security":[{"bearer":[]}],"x-required-scope":"files:read","description":"Each file carries a download_url that works for 15 minutes. Ask again for a fresh one.","parameters":[{"name":"id","in":"path","required":true,"description":"Job id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{id}/reports":{"get":{"summary":"A job's photo reports","tags":["Reports"],"security":[{"bearer":[]}],"x-required-scope":"reports:read","parameters":[{"name":"id","in":"path","required":true,"description":"Job id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Report"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/{id}":{"get":{"summary":"Get a photo report","tags":["Reports"],"security":[{"bearer":[]}],"x-required-scope":"reports:read","parameters":[{"name":"id","in":"path","required":true,"description":"Report id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/{id}/pdf":{"get":{"summary":"A photo report as a PDF","tags":["Reports"],"security":[{"bearer":[]}],"x-required-scope":"reports:read","parameters":[{"name":"id","in":"path","required":true,"description":"Report id","schema":{"type":"string"}}],"responses":{"200":{"description":"The PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/{id}/zip":{"get":{"summary":"A photo report's PDF and every photo and video, as one ZIP","tags":["Reports"],"security":[{"bearer":[]}],"x-required-scope":"reports:read","parameters":[{"name":"id","in":"path","required":true,"description":"Report id","schema":{"type":"string"}}],"responses":{"200":{"description":"The ZIP","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/appointments":{"get":{"summary":"List appointments","tags":["Appointments"],"security":[{"bearer":[]}],"x-required-scope":"appointments:read","parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page.","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"Only records changed at or after this ISO 8601 time. Use it to sync.","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","required":false,"description":"confirmed, completed, cancelled, pending ...","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Scheduled at or after (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"description":"Scheduled before (ISO 8601).","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Appointment"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/appointments/{id}":{"get":{"summary":"Get an appointment","tags":["Appointments"],"security":[{"bearer":[]}],"x-required-scope":"appointments:read","parameters":[{"name":"id","in":"path","required":true,"description":"Appointment id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/calls":{"get":{"summary":"List calls","tags":["Calls"],"security":[{"bearer":[]}],"x-required-scope":"calls:read","parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page.","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"Only records changed at or after this ISO 8601 time. Use it to sync.","schema":{"type":"string","format":"date-time"}},{"name":"phone","in":"query","required":false,"description":"Calls from this number.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Call"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/calls/{id}":{"get":{"summary":"Get a call","tags":["Calls"],"security":[{"bearer":[]}],"x-required-scope":"calls:read","parameters":[{"name":"id","in":"path","required":true,"description":"Call id","schema":{"type":"string"}},{"name":"include","in":"query","required":false,"description":"\"transcript\" to include what was said.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads":{"post":{"summary":"Send in a lead","tags":["Leads"],"security":[{"bearer":[]}],"x-required-scope":"leads:write","description":"Handled exactly like a website form: the bot and spam checks, do-not-call list, daily limit and calling hours apply, a job is made on the board, and the AI follows up. Do NOT use this for existing customers; use POST /contacts or POST /jobs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadInput"}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadAccepted"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/events":{"get":{"summary":"The events you can subscribe to","tags":["Webhooks"],"security":[{"bearer":[]}],"x-required-scope":"webhooks:manage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"summary":"List webhook subscriptions","tags":["Webhooks"],"security":[{"bearer":[]}],"x-required-scope":"webhooks:manage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Subscribe a URL to events","tags":["Webhooks"],"security":[{"bearer":[]}],"x-required-scope":"webhooks:manage","description":"The answer carries the signing secret ONCE. Store it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","description":"An https URL on your system."},"events":{"type":"array","items":{"type":"string","enum":["job.created","job.stage_changed","contact.created","lead.received","appointment.booked","optout.requested"]}},"description":{"type":"string","description":"A note for yourself."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","description":"whsec_... Shown once."}}}]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"delete":{"summary":"Remove a webhook subscription","tags":["Webhooks"],"security":[{"bearer":[]}],"x-required-scope":"webhooks:manage","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id","schema":{"type":"string"}}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/test":{"post":{"summary":"Send a test event (ping) to a subscription","tags":["Webhooks"],"security":[{"bearer":[]}],"x-required-scope":"webhooks:manage","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id","schema":{"type":"string"}}],"responses":{"200":{"description":"The result","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A company API key, bcl_live_... Permissions: contacts:read, contacts:write, jobs:read, jobs:write, appointments:read, calls:read, leads:write, files:read, reports:read, webhooks:manage."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"TeamMember":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"Pipeline":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"is_default":{"type":"boolean"},"stages":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"meaning":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"Contact":{"type":"object","properties":{"id":{"type":"integer"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"address":{"anyOf":[{"type":"string"},{"type":"null"}]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_type":{"type":"string","enum":["Customer","General Contact"]},"tags":{"type":"array","items":{"type":"string"}},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ContactInput":{"type":"object","required":["phone"],"properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"address":{"type":"string"},"company_name":{"type":"string"},"notes":{"type":"string"},"contact_type":{"type":"string","enum":["Customer","General Contact"]},"tags":{"type":"array","items":{"type":"string"}}}},"ContactUpdate":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"address":{"type":"string"},"company_name":{"type":"string"},"notes":{"type":"string"},"contact_type":{"type":"string","enum":["Customer","General Contact"]},"tags":{"type":"array","items":{"type":"string"}}}},"Job":{"type":"object","properties":{"id":{"type":"integer"},"job_number":{"anyOf":[{"type":"integer"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"contact":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","description":"E.164"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"address":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage":{"type":"object","properties":{"key":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"pipeline":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"status":{"type":"string","enum":["open","won","lost","abandoned"]},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"priority":{"type":"string","enum":["normal","high","urgent"]},"assigned_to":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},{"type":"null"}]},"service":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"lost_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"fields":{"type":"object","description":"The company's custom fields, by key."},"provider":{"type":"string"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"stage_changed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"JobInput":{"type":"object","description":"At least one of title, contact.name, contact.phone or company_name.","properties":{"title":{"type":"string"},"contact":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","description":"E.164"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"contact_id":{"type":"integer"},"company_name":{"type":"string"},"address":{"type":"string"},"value":{"type":"number"},"stage":{"type":"string"},"pipeline_id":{"type":"integer"},"assigned_to":{"type":"string","description":"Team member id from GET /team."},"service":{"type":"string"},"description":{"type":"string"},"priority":{"type":"string","enum":["normal","high","urgent"]},"tags":{"type":"array","items":{"type":"string"}},"fields":{"type":"object"},"note":{"type":"string","description":"A first note on the job."},"source":{"type":"string","description":"Where the job came from. Default: \"API: <key name>\"."}}},"JobUpdate":{"type":"object","properties":{"title":{"type":"string"},"contact":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}}},"company_name":{"type":"string"},"address":{"type":"string"},"value":{"type":"number"},"priority":{"type":"string","enum":["normal","high","urgent"]},"status":{"type":"string","enum":["open","won","lost","abandoned"]},"description":{"type":"string"},"lost_reason":{"type":"string"},"service":{"type":"string"},"assigned_to":{"type":"string"},"fields":{"type":"object"}}},"Note":{"type":"object","properties":{"id":{"type":"integer"},"job_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"contact_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"body":{"type":"string"},"author":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"edited_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"File":{"type":"object","properties":{"id":{"type":"integer"},"job_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"kind":{"type":"string","enum":["photo","video","document"]},"filename":{"anyOf":[{"type":"string"},{"type":"null"}]},"mime":{"anyOf":[{"type":"string"},{"type":"null"}]},"bytes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"stage":{"anyOf":[{"type":"string","enum":["before","during","after"]},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"taken_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"gps":{"anyOf":[{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"download_url_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"Report":{"type":"object","properties":{"id":{"type":"integer"},"job_id":{"type":"integer"},"title":{"type":"string"},"kind":{"type":"string","enum":["photos","completion","timeline","walkthrough"]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"photo_count":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"pdf_url":{"type":"string"},"zip_url":{"type":"string"}}},"Appointment":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"scheduled_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","description":"E.164"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"homeowner":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","description":"E.164"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"address":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"service":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigned_to":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},{"type":"null"}]},"calendar_event_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Call":{"type":"object","properties":{"id":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"anyOf":[{"type":"string"},{"type":"null"}]},"caller_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"caller_email":{"anyOf":[{"type":"string"},{"type":"null"}]},"caller_address":{"anyOf":[{"type":"string"},{"type":"null"}]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"outcome":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"intent":{"anyOf":[{"type":"string"},{"type":"null"}]},"lead_quality":{"anyOf":[{"type":"string"},{"type":"null"}]},"urgency":{"anyOf":[{"type":"string"},{"type":"null"}]},"service":{"anyOf":[{"type":"string"},{"type":"null"}]},"recording_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"transcript":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["agent","caller"]},"text":{"type":"string"},"at_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]}}}}}},"LeadInput":{"type":"object","required":["phone"],"properties":{"name":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"address":{"type":"string","description":"The property address."},"service":{"type":"string","description":"What they need, for example \"Roof replacement\"."},"message":{"type":"string","description":"What they wrote."}}},"LeadAccepted":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["received","filtered"]},"duplicate":{"type":"boolean"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["job.created","job.stage_changed","contact.created","lead.received","appointment.booked","optout.requested"]}},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"last_delivery_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_status":{"anyOf":[{"type":"integer"},{"type":"null"}]},"failures_in_a_row":{"type":"integer"}}}}},"x-webhook-events":{"job.created":"A job was created: in the app, by the AI from a call or text, from a lead, or through the API.","job.stage_changed":"A job moved to another stage.","contact.created":"A contact was created in the app or through the API.","lead.received":"A new lead came in from a website form or the API (before the AI follows up).","appointment.booked":"The AI booked an appointment.","optout.requested":"Someone asked not to be contacted again. Stop calling and texting them."}}