brixfit-sdk

Official JavaScript/TypeScript SDK for the Brixfit Coaching CRM API.

Zero dependencies. Works in Node.js 18+.

Installation

npm install brixfit-sdk

Quick Start

import { BrixfitClient } from 'brixfit-sdk'

const brixfit = new BrixfitClient({
  apiKey: 'brx_your_api_key_here',
})

// List leads
const { data, meta } = await brixfit.leads.list({ page: 1, per_page: 20 })
console.log(`${meta.total} leads found`)

// Create a lead
const { data: lead } = await brixfit.leads.create({
  name: 'John Doe',
  email: '[email protected]',
  phone: '+14155551234',
  goal: 'Weight loss',
})
console.log(lead.id, lead.health_metrics?.bmi)

Authentication

Get your API key from Brixfit → Developer → API Keys.

const brixfit = new BrixfitClient({
  apiKey: process.env.BRIXFIT_API_KEY!,
  baseUrl: 'https://brixfit.app', // optional, this is the default
  timeout: 30_000,               // optional, ms
})

API Reference

Leads

// List with filters
brixfit.leads.list({ page, per_page, search, status, sort })

// Get single lead
brixfit.leads.get(id)

// Create — returns lead + plan-gated health_metrics
brixfit.leads.create({ name, email?, phone?, status?, ...customFields })

// Update fields
brixfit.leads.update(id, { name?, email?, phone?, ...customFields })

// Move to a pipeline status
brixfit.leads.updateStatus(id, 'qualified')

// Delete
brixfit.leads.delete(id)

// Latest AI health report
brixfit.leads.getHealthReport(id)

// All health reports (paginated)
brixfit.leads.listHealthReports(id, { page?, per_page? })

// Coach's custom pipeline stages
brixfit.leads.statuses()

// Dynamic field definitions
brixfit.leads.fields()

Clients

// List with filters
brixfit.clients.list({ page, per_page, search, status })

// Get single client
brixfit.clients.get(id)

// Update details
brixfit.clients.update(id, { status?, goal?, phone?, end_date?, notes? })

// Deactivate account
brixfit.clients.deactivate(id)

// Latest AI health report
brixfit.clients.getHealthReport(id)

// All health reports (paginated)
brixfit.clients.listHealthReports(id, { page?, per_page? })

Check-ins

// List all check-ins
brixfit.checkins.list({ page, per_page, client_id, status, from_date, to_date })

// All check-ins for a specific client
brixfit.checkins.listByClient(clientId, { page, per_page, status, from_date, to_date })

Webhooks

// List registered webhooks
brixfit.webhooks.list()

// Register a new webhook (returns secret once)
const { data } = await brixfit.webhooks.create({
  url: 'https://yourapp.com/webhooks/brixfit',
  events: ['lead.created', 'lead.status_changed'],
  description: 'My app webhook',
})
console.log(data.secret) // store this — shown only once

// Enable / disable without deleting
brixfit.webhooks.setActive(id, false)

// Delete
brixfit.webhooks.delete(id)

Webhook Verification

Verify incoming webhook payloads from Brixfit using verifyWebhook. It uses timing-safe HMAC-SHA256 comparison and optional replay protection.

Express

import express from 'express'
import { verifyWebhook } from 'brixfit-sdk'

const app = express()

app.post(
  '/webhooks/brixfit',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const result = verifyWebhook({
      payload:   req.body,                                      // raw Buffer
      signature: req.headers['x-brixfit-signature'] as string,
      secret:    process.env.BRIXFIT_WEBHOOK_SECRET!,
      timestamp: req.headers['x-brixfit-timestamp'] as string, // replay protection
      maxAgeMs:  5 * 60 * 1000,                                // 5 minutes
    })

    if (!result.valid) {
      return res.status(401).json({ error: result.reason })
    }

    const { event, data } = result.payload!

    if (event === 'lead.created') {
      console.log('New lead:', data)
    }

    res.json({ ok: true })
  },
)

Next.js App Router

import { NextRequest, NextResponse } from 'next/server'
import { verifyWebhook } from 'brixfit-sdk'

export async function POST(req: NextRequest) {
  const body = await req.text()

  const result = verifyWebhook({
    payload:   body,
    signature: req.headers.get('x-brixfit-signature') ?? '',
    secret:    process.env.BRIXFIT_WEBHOOK_SECRET!,
    timestamp: req.headers.get('x-brixfit-timestamp') ?? undefined,
  })

  if (!result.valid) {
    return NextResponse.json({ error: result.reason }, { status: 401 })
  }

  const { event, data } = result.payload!
  // handle event...

  return NextResponse.json({ ok: true })
}

Error Handling

All methods throw BrixfitError on non-2xx responses.

import { BrixfitClient, BrixfitError } from 'brixfit-sdk'

try {
  const { data } = await brixfit.leads.get('nonexistent-id')
} catch (err) {
  if (err instanceof BrixfitError) {
    console.log(err.message) // 'Lead not found.'
    console.log(err.status)  // 404
    console.log(err.details) // validation details (422 errors)
  }
}

TypeScript

The SDK is written in TypeScript and ships full type declarations. All request params, response shapes, and webhook payloads are typed.

import type {
  Lead,
  Client,
  Checkin,
  Webhook,
  WebhookPayload,
  WebhookEvent,
  CreateLeadData,
} from 'brixfit-sdk'

Supported Events

| Event | Description | |-------|-------------| | lead.created | New lead added | | lead.updated | Lead fields changed | | lead.status_changed | Lead moved to new pipeline stage | | lead.converted | Lead converted to client | | lead.deleted | Lead deleted | | client.created | New client onboarded | | client.updated | Client details updated | | client.deleted | Client account deleted | | checkin.submitted | Client submitted a check-in |

Resources

• Brixfit website
• API documentation
• Developer dashboard
• npm package
• GitHub repository
• Report a bug
• Contact support

License

MIT — © 2026 Brixfit