Developer docs

BuilderMate API & Webhooks Reference

Read and change your CRM data over a JSON REST API, and get notified the moment something happens with webhooks.

Overview

BuilderMate exposes its CRM data over a JSON REST API at https://crm.bldrmate.com/api, authenticated with an organization API key, and pushes events to your systems through webhooks.

  • API: the same endpoints the BuilderMate web app uses. A key acts inside one organization only and can read and change clients, projects, quotes, invoices, tasks, appointments and more.
  • Webhooks: BuilderMate sends an HTTPS POST to a URL you register whenever a subscribed event happens, such as a lead being created or a client signing a contract.
  • Who can set this up: organization admins, under Settings → Integrations (tabs: API Keys, Webhooks).

Authentication

Every request carries an API key; send it in the X-API-Key header.

Request
curl https://crm.bldrmate.com/api/clients \
  -H "X-API-Key: crm_3f9a..."

Creating a key. An organization admin opens Settings → Integrations → API Keys and creates a key with a name and an optional expiry date. Keys look like crm_ followed by 64 hex characters. The full key is shown once, at creation; store it in a secrets manager.

Where the key can go (checked in this order):

LocationFormatUse
HeaderX-API-Key: crm_...Recommended
HeaderAuthorization: Bearer crm_...Supported

What a key can access. A key belongs to the organization it was created in and to the admin who created it. Every request is limited to that organization's data.

Conventions

Requests and responses are JSON; send Content-Type: application/json on every POST, PUT and PATCH. Bodies can be up to 50 MB.

IDs and paths. Every record has a numeric id, used in paths such as /api/clients/42. Fields are camelCase. Dates are ISO 8601 strings (2026-10-13T15:00:00Z) and money amounts are numbers in your organization's currency.

Pagination. Paginated lists take page (starting at 1) and limit query parameters. Most default to 10 items per page; tasks default to 5. Items are always in data, but the page counts sit in different places by endpoint:

EndpointWhere the counts are
GET /api/clients, GET /api/estimatespagination.page, pagination.limit, pagination.totalItems, pagination.totalPages
GET /api/projectspagination.currentPage, pagination.limit, pagination.totalItems, pagination.totalPages
GET /api/taskspagination.page, pagination.limit, pagination.total, pagination.totalPages
GET /api/invoices, GET /api/supplier-invoicesTop level: currentPage, limit, total, totalPages
GET /api/appointmentsNot paginated; a date window, with the count in meta.total

To read everything, request page=1, 2, 3... until page reaches totalPages.

Paginated list
GET /api/clients?page=2&limit=50&search=smith

{
  "data": [ { "id": 42, "firstName": "Jane", "lastName": "Smith", ... } ],
  "pagination": { "page": 2, "limit": 50, "totalItems": 131, "totalPages": 3 },
  "sorting": { "field": "createdat", "order": "desc" }
}

Errors. Failures return an HTTP status and a JSON body carrying error (most endpoints) or message:

StatusMeaning
400Missing or invalid input; the body says which field
401No key, or an unrecognized key
403Key inactive, expired or missing a required scope
404The record doesn't exist in your organization (records from other organizations also return 404)
500Server error. Some endpoints also report validation failures this way, with the details in message

Rate limits. No per-key rate limit is enforced today. For bulk loads, use the batch endpoints (projects take up to 50 per request; appointments and employees up to 100) instead of one request per record. Retry 5xx responses with exponential backoff.

API endpoints

The API covers 14 resource groups with 86 endpoints, all under https://crm.bldrmate.com. Paths take numeric IDs, PUT updates send only the fields being changed, and DELETE is permanent.

Clients and leads

Leads and clients are the same record; leadStatus tracks where a lead is in the pipeline.

MethodPathWhat it does
GET/api/clientsList and search. Filters: search, leadStatus, leadSource, leadCategory, startDate, endDate, salesPersonIds (comma-separated), sortField, sortOrder
GET/api/clients/:idGet one client
POST/api/clientsCreate a client or lead
POST/api/clients/batchCreate many: { "clients": [ ... ] }
PUT/api/clients/:idUpdate a client
DELETE/api/clients/:idDelete a client and its related data

Projects

MethodPathWhat it does
GET/api/projectsList. Filters: status, projectType, search, employeeId
GET/api/projects/:idGet one project
POST/api/projectsCreate a project
POST/api/projects/batchCreate up to 50: { "projects": [ ... ] }
PUT/api/projects/:idUpdate a project
DELETE/api/projects/:idDelete a project and its related data

Quotes (estimates)

MethodPathWhat it does
GET/api/estimatesList, with line items
GET/api/estimates/:idGet one quote, with line items and payment stages
POST/api/estimatesCreate a quote
PUT/api/estimates/:idUpdate a quote
DELETE/api/estimates/:idDelete a quote
GET/api/estimates/:id/pdfDownload the PDF
POST/api/estimates/:id/emailEmail the quote to the client

Change orders

MethodPathWhat it does
GET/api/change-orders/project/:projectIdList a project's change orders
GET/api/change-orders/:idGet one change order
POST/api/change-ordersCreate a change order (include projectId)
PUT/api/change-orders/:idUpdate a change order
DELETE/api/change-orders/:idDelete a change order
GET/api/change-orders/:id/pdfDownload the PDF

Contracts

MethodPathWhat it does
GET/api/contractsList contracts
GET/api/contracts/:idGet one contract
POST/api/contractsCreate a contract from a template
PUT/api/contracts/:idUpdate a contract
DELETE/api/contracts/:idDelete a contract
GET/api/contracts/:id/download-pdfDownload the PDF

Invoices and client payments

MethodPathWhat it does
GET/api/invoicesList. Filters: search, status, dateFrom, dateTo, amountMin, amountMax
GET/api/projects/:projectId/client-invoicesList a project's invoices
GET/api/client-invoices/:idGet one invoice
POST/api/client-invoicesCreate an invoice
PUT/api/client-invoices/:idUpdate an invoice
DELETE/api/client-invoices/:idDelete an invoice
GET/api/invoices/:id/pdfDownload the PDF
POST/api/invoices/:id/sendEmail the invoice to the client
POST/api/client-paymentsRecord a payment received
PUT/api/client-payments/:idUpdate a payment
DELETE/api/client-payments/:idDelete a payment

Expenses and supplier payments

MethodPathWhat it does
GET/api/supplier-invoicesList expenses (supplier invoices)
POST/api/supplier-invoicesCreate an expense
PUT/api/supplier-invoices/:idUpdate an expense
DELETE/api/supplier-invoices/:idDelete an expense
POST/api/supplier-paymentsRecord a payment to a supplier
PUT/api/supplier-payments/:idUpdate a supplier payment
DELETE/api/supplier-payments/:idDelete a supplier payment

Purchase orders

MethodPathWhat it does
GET/api/purchase-ordersList purchase orders
GET/api/purchase-orders/:idGet one purchase order
POST/api/purchase-ordersCreate a purchase order
PUT/api/purchase-orders/:idUpdate a purchase order
DELETE/api/purchase-orders/:idDelete a purchase order
GET/api/purchase-orders/:id/pdfDownload the PDF

Appointments

MethodPathWhat it does
GET/api/appointmentsList appointments in a date window (view, date, startDate, endDate)
POST/api/appointmentsSchedule an appointment
POST/api/appointments/batchCreate up to 100: { "appointments": [ ... ] }
PUT/api/appointments/:idUpdate or reschedule
DELETE/api/appointments/:idDelete an appointment

Tasks

MethodPathWhat it does
GET/api/tasksList tasks (default page size 5)
GET/api/tasks/:idGet one task
POST/api/tasksCreate a task
PUT/api/tasks/:idUpdate a task
PUT/api/tasks/:id/toggleToggle complete/incomplete
DELETE/api/tasks/:idDelete a task

Subcontractors

MethodPathWhat it does
GET/api/subcontractorsList and search
GET/api/subcontractors/:idGet one subcontractor
POST/api/subcontractorsAdd a subcontractor
POST/api/subcontractors/batchCreate many: { "subcontractors": [ ... ] }
PUT/api/subcontractors/:idUpdate a subcontractor
DELETE/api/subcontractors/:idDelete a subcontractor

Employees

MethodPathWhat it does
GET/api/employeesList employees (pass page and limit to paginate)
GET/api/employees/:idGet one employee
POST/api/employeesAdd an employee
POST/api/employees/batchCreate up to 100: { "employees": [ ... ] }
PUT/api/employees/:idUpdate an employee
DELETE/api/employees/:idDelete an employee

Reports and dashboard

Read-only summaries.

MethodPathWhat it does
GET/api/dashboardHeadline metrics and recent activity
GET/api/reports/financialRevenue, expenses and profit
GET/api/reports/cashflowMoney in and out over time
GET/api/reports/leadsLead conversion, sources and pipeline
GET/api/reports/projectsProject statuses, timelines and budgets
GET/api/reports/sales-performanceSales metrics by salesperson

Lead intake (Angi, Thumbtack)

These endpoints receive leads pushed from marketplaces, and the key needs the matching scope.

MethodPathScope
POST/api/integrations/angi/leadsangi:write
POST/api/integrations/thumbtack/webhookthumbtack:write

For request bodies and example responses for each endpoint, see Settings → API Documentation inside BuilderMate.

Webhooks

BuilderMate sends one HTTPS POST per event to each endpoint subscribed to it. There are no retries, so make your receiver fast and idempotent.

Setting up an endpoint

An organization admin opens Settings → Integrations → Webhooks and adds an endpoint with:

  • URL: must be https://, must resolve to a public address (private, loopback and cloud-metadata addresses are rejected) and can't contain credentials.
  • Events: any events from the catalog below, or * for all of them.
  • Headers: up to 10 custom headers sent with every delivery, typically an Authorization or API-key header your receiver checks.
  • Active: turn an endpoint off without deleting it.

Use Send test to deliver a webhook.test event right away and see the status your server returned. Only admins can manage endpoints, from the web app; API keys can't create or change them.

What a delivery looks like

Delivery
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: BuilderMate-Webhooks/1
X-BuilderMate-Event: lead.created
X-BuilderMate-Delivery: 7d3c1f0e-2b6a-4c9e-9a41-5e8f0b2d6c11
Authorization: Bearer <the value you configured>

{
  "event": "lead.created",
  "occurredAt": "2026-10-13T15:04:05.123Z",
  "organizationName": "Acme Remodeling",
  "data": { "id": 4211, "firstName": "Jane", "lastName": "Smith", "leadStatus": "new", ... }
}
FieldMeaning
eventEvent name from the catalog (also in the X-BuilderMate-Event header)
occurredAtWhen BuilderMate sent the event (ISO 8601, UTC)
organizationNameThe BuilderMate account the event came from, for receivers that serve several accounts
dataA snapshot of the record, loaded at send time

X-BuilderMate-Delivery is a unique ID per delivery; log it for support requests.

What's in data. The full record as the API returns it, with three changes:

  • Signatures, file contents and credentials are removed.
  • Internal fields (organizationId, accounting and payment-provider IDs) are removed.
  • Person IDs become names: createdById becomes createdByName, assignedToId becomes assignedToName, salesperson1id becomes salesperson1Name, and so on. Client and project IDs stay, so you can fetch related records through the API.

Verifying deliveries

Deliveries are not signed. Authenticate them with a secret custom header (for example Authorization: Bearer <long random value>), and reject any request where it doesn't match. Keep the endpoint on HTTPS so the header can't be read in transit.

Delivery rules

RuleBehavior
SuccessAny 2xx response
Timeout5 seconds; slower responses count as failed
RedirectsNot followed; a 3xx counts as failed
RetriesNone. A failed delivery is not sent again
OrderingNot guaranteed; use occurredAt and the record's updatedAt
DuplicatesPossible for some business events; dedupe on the event name plus the record's id and status
MonitoringThe settings page shows each endpoint's last delivery time, status code and error

Because failures aren't retried, treat webhooks as a prompt to act and use the API to reconcile. For example, list records updated since your last sync on a schedule.

Webhook event catalog

28 events are delivered today. Another 8 appear in the event picker but are never sent yet, so don't build on those. Unless noted, data is the full record named in the Data column.

Leads

EventFires whenData
lead.createdA lead or client is created (web app, API or import)Client
lead.updatedA lead or client is editedClient
lead.status_changedThe lead status changes, from an edit or the status controlClient. An edit that changes status sends both lead.updated and this event
lead.deletedA lead or client is deleted{ "id": 4211 } only

Projects

EventFires whenData
project.createdA project is createdProject
project.updatedA project is editedProject
project.deletedA project is deleted{ "id": ... } only

Tasks

EventFires whenData
task.createdA task is createdTask
task.updatedA task is edited or completedTask
task.deletedA task is deleted{ "id": ... } only
task.assignedA task is assigned to someoneTask
task.comment_addedSomeone comments on a taskTask (not the comment)

Appointments

EventFires whenData
appointment.createdAn appointment is scheduledAppointment
appointment.updatedAn appointment is changed or rescheduledAppointment
appointment.deletedAn appointment is cancelled or deleted{ "id": ... } only

Quotes

EventFires whenData
estimate.openedThe client opens the quote in the client portalQuote
estimate.approvedThe client approves and signs the quoteQuote
estimate.requestedThe client asks for changes to the quote from the client portalQuote. The request text is not included; read it in the app

Contracts

EventFires whenData
contract.openedThe client opens the contractContract
contract.signedThe client signs the contractContract
contract.third_party_signedA third-party signer signsContract
contract.subcontractor_signedA subcontractor signs their contractKnown issue: may arrive with no data or the wrong contract. Don't rely on it yet

Change orders

EventFires whenData
change_order.openedThe client opens the change orderChange order
change_order.approvedThe client approves and signs the change orderChange order

Invoices

EventFires whenData
invoice.openedThe client opens the invoiceInvoice
invoice.paidAn online payment completes and pays the invoiceInvoice

Other

EventFires whenData
bid.submittedA subcontractor submits a bid on a bid requestBid submission
purchase_order.signedA supplier signs a purchase orderPurchase order
webhook.testYou click Send test on an endpoint{ "message", "endpointId", "endpointName" }. Not subscribable

Building something on BuilderMate?

See which tools already connect on the integrations page, or contact us with questions about the API.

Connect BuilderMate to the rest of your stack

Start Free Trial