Developer Docs

Bizoforce API

Access the full Bizoforce business directory programmatically. Query companies, products, reviews, submit leads, and stream events via webhooks.

https://bizoforce.com/api/v1

Current version: v1

Overview

The Bizoforce REST API gives developers programmatic access to the platform's business directory data. All responses are JSON and follow a consistent envelope format.

Base URL

https://bizoforce.com/api/v1

Protocol

HTTPS only

Format

JSON (application/json)

Auth

Bearer Token (permanent API key)

Response Envelope

Every response wraps data in a consistent structure:

{
  "success": true,
  "data": { ... }          // present on success
}

// On error:
{
  "success": false,
  "error": "Human-readable error message"
}

Authentication

Permanent bearer tokens — no session cookies required

Bizoforce uses permanent API keys as bearer tokens. They are valid until you explicitly delete them and have no dependency on browser sessions or cookies — making them ideal for server-to-server integrations.

Token lifetime: API keys do not expire. They remain active until you revoke them from your dashboard or via the DELETE /api/user/api-keys/:id endpoint. Treat them like passwords — store them securely and rotate them if compromised.

Obtaining a Key

Log in to your Bizoforce account.
Go to Dashboard → API & Webhooks → API Keys.
Click Create API Key, choose a name and scopes, then save the key — it is shown once.

Using Your Token

Pass your API key as a standard HTTP Authorization: Bearer header:

curl -X GET "https://bizoforce.com/api/v1/companies" \
  -H "Authorization: Bearer bzf_YOUR_API_KEY_HERE"

Legacy: X-API-Key: bzf_YOUR_KEY also works but Bearer is preferred.

Data Access Rules

Role	Can Access
Any authenticated user	Only their own data (leads sent/received, reviews submitted, API keys)
Vendor	Their own listing data + inbound leads for their company
Admin	Full access to all resources across all users

Public endpoints (companies, products, categories, search, reviews) are readable without authentication.

Available Scopes

Scope	Access Granted
read:listings	Read company and product listings
read:reviews	Read reviews for companies and products
read:leads	Read your inbound leads (vendors see their own; admins see all)
write:leads	Submit new lead enquiries

Versioning

The API uses URL-based versioning. The current stable version is v1.

# Current (stable)
https://bizoforce.com/api/v1/companies

# Explicit version prefix
https://bizoforce.com/api/v1/companies

Stability guarantee: Breaking changes will always bump the major version. We will maintain the previous version for at least 6 months after a new version ships, with deprecation notices sent via email to registered API users.

Rate Limiting

Rate limits are applied per IP (unauthenticated) or per API key (authenticated).

Tier	Limit	Window
Unauthenticated	100 requests	15 minutes
API Key (all plans)	500 requests	15 minutes
Search endpoint	30 requests	1 minute

When a limit is exceeded you will receive a 429 Too Many Requests response. Retry after the time indicated in the Retry-After header.

Error Responses

All error responses include a success: false flag and a human-readable error field.

HTTP Status	Meaning
400	Bad Request — missing or invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — valid key but insufficient scope or subscription
404	Not Found — resource does not exist
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — something went wrong on our end

{
  "success": false,
  "error": "At least one scope is required."
}

Companies

Access the business directory listings

Products

Software products listed in the directory

Reviews

Search

Leads

Requires write:leads scope

All lead endpoints require an API key with the write:leads or read:leads scope. Vendors can only read leads for their own listings; admins can read all.

API Keys (User)

Manage your own API keys programmatically

These endpoints are self-service — use your API key as a Bearer token. Each user can only manage their own keys. Admins can manage keys for any user via /api/admin/api-keys.

Webhooks

Receive real-time event notifications via HTTP POST

Webhooks deliver POST requests to your endpoint URL whenever an event occurs. Each delivery is signed with an HMAC-SHA256 signature so you can verify it came from Bizoforce.

Signature Verification

Every webhook request includes a X-Bizoforce-Signature header. Verify it with your webhook secret:

// Node.js example
const crypto = require('crypto')

function verifyWebhook(rawBody, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
          .update(rawBody)
          .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  )
}

// In your Express handler:
app.post('/webhooks/bizoforce', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-bizoforce-signature']
  if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature')
  }
  const event = JSON.parse(req.body)
  console.log('Received event:', event.event, event.data)
  res.sendStatus(200)
})

Webhook Payload Structure

{
  "event": "lead.created",
  "timestamp": "2026-04-30T08:00:00.000Z",
  "data": {
    // event-specific payload (see Webhook Events below)
  }
}

Retry Policy

If your endpoint returns a non-2xx status, Bizoforce will retry up to 3 times with exponential back-off (5 min, 30 min, 2 hrs). Deliveries that fail all retries are marked as failed in your webhook delivery log.

Managing Webhooks via API

Webhook Events

Events you can subscribe to

Event	Trigger	Key Payload Fields
lead.created	A new lead is submitted to your company	id, name, email, message, companyId
lead.status_changed	A lead's status is updated	id, oldStatus, newStatus
lead.reply	A reply is sent on a lead thread	id, leadId, message, senderRole
review.submitted	A new review is submitted for your listing	id, reviewerName, rating, title
review.approved	A review is approved and goes live	id, reviewerName, rating, companyId

Example: lead.created Payload

{
  "event": "lead.created",
  "timestamp": "2026-04-30T09:15:00.000Z",
  "data": {
    "id": 301,
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1 555 0100",
    "company": "Initech",
    "message": "Interested in your payroll module.",
    "serviceType": "Payroll",
    "budget": "$10k–$50k",
    "companyId": 1234,
    "createdAt": "2026-04-30T09:15:00.000Z"
  }
}

Questions or issues? Contact us at support@bizoforce.com

API v1 · Last updated April 2026 · Manage your API keys