STABLEVersion 2.0

Vendor API Reference

Complete reference for the Balance for Life Vendor API. Build integrations, automate workflows, and connect your systems with the BFL platform.

Base URL

https://api.balanceforlifeai.com

Auth Header

X-API-Key: YOUR_API_KEY

Rate Limit

100 /min

Encryption

TLS 1.3 + AES-256

Quick Start

Make your first API request in under a minute.

All API requests require an X-API-Key header. Your API key is provided by the platform admin during onboarding.

bash

curl -X GET "https://api.balanceforlifeai.com/api/v2/members/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY"

Or with TypeScript:

typescript

const response = await fetch("https://api.balanceforlifeai.com/api/v2/members/", {
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.VENDOR_API_KEY,
  },
});
const members = await response.json();

Authentication

API key scopes and security best practices.

Include your API key in every request via the X-API-Key header. Each key has specific scopes that determine what resources you can access.

Scope	Permissions
`members:read`	View assigned members
`sessions:read`	View sessions, care context, intelligence, handoffs, events
`sessions:write`	Log sessions, update care context, manage handoffs
`notes:read`	View clinical notes
`notes:write`	Create clinical notes
`assessments:read`	View assessments
`assessments:write`	Submit assessments
`crisis:read`	View crisis flags
`crisis:write`	Create crisis flags

Security: Never expose your API key in client-side code, public repos, or browser network logs. Store it server-side and proxy requests through your backend.

Error Handling

HTTP status codes and error response format.

All errors return a JSON body with a detail field.

json

{ "detail": "Member not found or not assigned to this vendor" }

Status	Meaning	Action
401	Invalid or expired API key	Re-authenticate with a valid key
403	Insufficient scope / not assigned	Check your API key permissions
404	Resource not found	Verify the ID is correct
409	Conflict (duplicate resource)	Check existing records
422	Validation error	Fix the request body per the detail message
429	Rate limit exceeded	Wait and retry after Retry-After seconds
500	Internal server error	Retry with exponential backoff

Rate Limits

Request throttling and retry strategies.

The API enforces a rate limit of 100 requests per minute per API key. Rate limit status is communicated via response headers.

Header	Description
`X-RateLimit-Limit`	Maximum requests per window (100)
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait (only on 429 responses)

typescript

async function fetchWithRetry(url: string, opts: RequestInit, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, opts);
    if (res.status === 429) {
      const wait = parseInt(res.headers.get("Retry-After") || "5");
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    return res;
  }
  throw new Error("Rate limit exceeded after retries");
}

API Reference

27 endpoints across 10 resources

Members

Manage and view member profiles assigned to your vendor account.

Intelligence

Access computed intelligence briefs including risk levels, engagement scores, and mood trends.

Care Context

Configure treatment parameters that guide the Zen AI companion.

Sessions

Log therapy sessions and track session history.

Clinical Notes

Create and manage encrypted clinical notes tied to sessions.

Assessments

Submit and review clinical assessments (PHQ-9, GAD-7, custom).

Crisis Flags

Report and monitor crisis flags for members.

Handoffs

Manage care transitions between vendors with full clinical context.

Events

Access the real-time activity feed and member timelines.

Onboarding

Public endpoint for vendor onboarding requests.