Brick & Yield API

The Brick & Yield API lets you sync clients, notes, tags, and tasks between Brick & Yield and your CRM or other tools. It powers the official Brick & Yield Zapier integration, and can be used directly by any HTTP client.

Overview

The API is organized around REST. All requests and responses use JSON. Every endpoint is scoped to a single agent — an API key can only read and write that agent's own clients and their related records. There is no access to other agents' data.

The API is versioned under /api/v1. Two-way sync is supported: you can push data in with the actions below, and receive real-time events out via webhooks (see Webhooks).

Authentication

The API uses per-agent API keys. An agent generates a key in the Brick & Yield admin app under Settings → API Keys. The key is shown once at creation time and stored hashed — if it is lost, revoke it and generate a new one.

Pass the key as a bearer token on every request. X-API-Key: <key> is also accepted.

Authorization: Bearer by_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Requests without a valid, non-revoked key return 401 Unauthorized. Verify a key with the connection test endpoint.

Conventions & errors

Successful responses include "ok": true alongside the returned resource. Write endpoints return 201 Created; reads and idempotent updates return 200 OK.

Errors return a non-2xx status with a JSON body:

{ "error": "Client not found." }

How clients are matched

Create/update and find operations locate an existing client using the following identifiers, in order. The first one that matches wins — this keeps repeated syncs from creating duplicates:

1. CRM Record ID — external_id (exact match). Recommended: store your CRM's contact ID so matching survives email changes.
2. Email — case-insensitive exact match.
3. Phone — normalized to the last 10 digits.

Note, tag, and task endpoints accept any of these in the {id} path segment — the Brick & Yield client UUID, the external_id, or the client's email.

Connection test

Returns the agent and organization the API key belongs to. Used to verify a key.

curl https://api.brickandyield.app/api/v1/me \
  -H "Authorization: Bearer by_live_xxx"

{
  "ok": true,
  "agent":        { "id": "…", "name": "Jane Agent", "email": "jane@brokerage.com" },
  "organization": { "id": "…", "name": "Acme Realty" }
}

Clients

curl -X POST https://api.brickandyield.app/api/v1/clients \
  -H "Authorization: Bearer by_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "crm-123",
    "external_source": "hubspot",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "(801) 555-1234",
    "stage": "new",
    "portal_type": "buyer",
    "tags": ["Hot Lead", "Investor"]
  }'

{
  "ok": true,
  "created": true,
  "client": {
    "id": "541218ce-9b41-4c1a-ba01-65b2d15a2a09",
    "external_id": "crm-123",
    "external_source": "hubspot",
    "first_name": "Jane",
    "last_name": "Doe",
    "full_name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "(801) 555-1234",
    "stage": "new",
    "portal_type": "buyer",
    "client_type": "home_buyer",
    "source": "zapier",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
}

curl "https://api.brickandyield.app/api/v1/clients?email=jane@example.com" \
  -H "Authorization: Bearer by_live_xxx"

{ "ok": true, "client": { "id": "…", "full_name": "Jane Doe", … } }

Notes, tags & tasks

For each of these, {id} may be the Brick & Yield client UUID, the external_id, or the client's email (URL-encode it).

curl -X POST https://api.brickandyield.app/api/v1/clients/crm-123/notes \
  -H "Authorization: Bearer by_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Called, left a voicemail." }'

{ "ok": true, "note": { "id": "…", "body": "Called, left a voicemail.", "created_at": "…", "source": "zapier" } }

{ "ok": true, "tag": { "id": "…", "name": "Hot Lead", "color": "#10b981" } }

curl -X POST https://api.brickandyield.app/api/v1/clients/crm-123/tasks \
  -H "Authorization: Bearer by_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Send listing agreement", "description": "Get it signed by Friday.", "due_date": "2026-01-05" }'

{ "ok": true, "task": { "id": "…", "title": "Send listing agreement", "description": "Get it signed by Friday.", "due_date": "2026-01-05", "completed": false, "source": "zapier" } }

Webhooks (triggers)

The API delivers real-time events via REST hooks. You subscribe a target URL to an event type; Brick & Yield then POSTs the event payload to that URL whenever it occurs. Events fire only from in-app activity, never from API writes — so a two-way sync will not loop.

curl -X POST https://api.brickandyield.app/api/v1/hooks/subscribe \
  -H "Authorization: Bearer by_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "event": "client.updated", "target_url": "https://hooks.example.com/abc" }'

{ "ok": true, "id": "5b3d483d-…" }

{ "ok": true }

curl "https://api.brickandyield.app/api/v1/hooks/sample?event=client.updated" \
  -H "Authorization: Bearer by_live_xxx"

Event types

Webhook event payloads

Each event is delivered as a JSON POST body. The shapes are:

client.created · client.updated · client.stage_changed

{
  "event": "client.updated",
  "client": {
    "id": "541218ce-9b41-4c1a-ba01-65b2d15a2a09",
    "external_id": "crm-123",
    "external_source": "hubspot",
    "first_name": "Jane",
    "last_name": "Doe",
    "full_name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "(801) 555-1234",
    "stage": "new",
    "portal_type": "buyer",
    "client_type": "home_buyer",
    "tags": ["Hot Lead", "Investor"]
  }
}

note.created

{
  "event": "note.created",
  "note":   { "id": "…", "body": "Called, left a voicemail.", "created_at": "…" },
  "client": { "id": "…", "full_name": "Jane Doe", "external_id": "crm-123", "email": "jane@example.com" }
}

task.created

{
  "event": "task.created",
  "task":   { "id": "…", "title": "Send listing agreement", "description": "…", "due_date": "2026-01-05", "completed": false },
  "client": { "id": "…", "full_name": "Jane Doe", "external_id": "crm-123", "email": "jane@example.com" }
}

tag.added

{
  "event": "tag.added",
  "tag":    { "id": "…", "name": "Hot Lead", "color": "#10b981" },
  "client": { "id": "…", "full_name": "Jane Doe", "external_id": "crm-123", "email": "jane@example.com" }
}

Field reference

Buyer stage (stage)

new · active · nurture · touring · under_contract · closed · paused

Portal type (portal_type)

buyer · seller · both

Client type (client_type)

investor · out_of_state_investor · house_hacker · home_buyer · seller_only