BSimple API Documentation — Endpoints, Authentication and Scopes

BSimple API Documentation

This is the current developer reference for the BSimple REST API. The API uses JSON responses and a versioned base path:

https://<your-bsimple-domain>/api/v1

For the business overview, see BSimple API. For a guided first request, see Getting started.

Authentication

Every request requires an API key created by an administrator in Settings → API Keys. The recommended method is the X-API-Key header:

curl --fail --silent \
  --header 'X-API-Key: YOUR_API_KEY' \
  'https://<your-bsimple-domain>/api/v1/customers/list'

The key secret is shown once at creation. BSimple stores a SHA-256 hash rather than the original secret. If a key is lost, revoke it and create a replacement. Do not put a key in browser JavaScript, source control, screenshots or support tickets.

Scopes

A request whose key lacks the required scope returns 403 with an insufficient_scope error. Grant each integration only the scopes it needs.

Response format

Successful requests use a data value and a meta object. List responses include pagination metadata:

{
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 137,
    "total_pages": 7
  }
}

Errors use an error object and an appropriate HTTP status:

{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "Customer was not found"
  }
}

Common statuses are 400 bad request, 401 missing or invalid key, 403 insufficient scope, 404 not found, 409 conflict and 422 validation failure.

List parameters

List endpoints support these common parameters where applicable:

Always follow meta.total_pages rather than assuming that one request returns every row.

Leads

Customers

Inventory and suppliers

Locations, PAR and reorder

Stocktakes

Purchase orders and transfers

Invoices

Invoice creation accepts inventory-backed lines with item_code and free-form service lines with description and unit_price. A request can mix both line types. See Create a draft invoice for the complete body and response semantics.

Current limitations

The current public API does not provide webhooks, bulk operations, file attachments, payments, invoice approval or sending, invoice editing or deletion, stocktake-count writes, purchase-order writes, transfer writes or general stock adjustments. Use the polling and reconciliation guide for current integration patterns.

This reference was reviewed on 9 September 2026. See the API changelog for documented changes.