Integrate
API reference
Keys, endpoints, request and response shapes, errors.
Base URL https://www.birdray.com/api/v1. Authenticate with Authorization: Bearer brd_live_…. Keys are created under Settings → API keys by a workspace admin, act as that admin, and can be revoked any time. Every response is { "ok": true, "data": … } or { "ok": false, "error": "…", "message": "…" }. Licence numbers are CSLB licence numbers, digits only.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /me |
Confirm the key; returns workspace id and scopes |
| GET | /search?q=&county=&trade=&carrier=&renews_within_days=&limit= |
The California contractor dataset (max 200) |
| GET | /companies/{license_no} |
One company: fields, people (masked where unpaid), stage, account, lists |
| GET | /companies?updated_since=&limit=&offset= |
Your book, newest activity first, with stage |
| GET | /contacts?license_no= |
People at one company, or across the book |
| GET | /handoffs?since=&limit= |
Replies and meeting clicks, same payload as the webhook |
| POST | /lists |
{ "list": "name or id", "license_nos": ["…"] } add companies to a list, creating it by name |
| POST | /enroll |
{ "license_nos": ["…"], "play": "name or id", "scheduled_for": null } enroll in the agent (Outbound or Agency; credits apply) |
| POST | /status |
{ "license_no": "…", "status": "won", "note": "…" } CRM write-back; won, lost and not_now stop enrollments |
Examples
curl https://www.birdray.com/api/v1/companies/1109913 \
-H "Authorization: Bearer brd_live_…"
curl -X POST https://www.birdray.com/api/v1/status \
-H "Authorization: Bearer brd_live_…" \
-H "Content-Type: application/json" \
-d '{"license_no":"1109913","status":"won","note":"Bound with ICW, eff 11/1"}'
Statuses
new, contacted, replied, meeting, quoted, won, lost, not_now
Errors
| error | HTTP | Meaning |
|---|---|---|
| invalid_key | 401 | Missing, malformed or revoked key |
| insufficient_scope | 403 | Read-only key used for a write |
| key_owner_left_workspace | 403 | The admin who created the key is no longer a member |
| plan_required | 402 | Enrolling needs Outbound or Agency |
| insufficient_credits | 402 | Not enough credits for the enrollments requested |
| invalid_status | 400 | Status not in the list above |
Limits
Requests share the app's rate limits (60 per minute per key is a safe ceiling). Search returns at most 200 rows, book listings 500, hand-offs 500.