BSimple API Docs: Endpoints, Auth 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.

Write endpoints (all POST endpoints that change data) require an Idempotency-Key request header — a client-chosen identifier of 1–255 characters that is unique per logical operation. Retrying the same key with the same body returns the original response instead of performing the write twice; reusing a key with a different body returns 409. Generate a fresh key (for example a UUID) for every new operation.

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

Saleable items

Returns the slice's saleable (warehouse bundle) list with each component inventory code resolved to description, price and quantity. Requires the saleable feature to be enabled for the account.

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, payments, invoice approval or sending, invoice editing or deletion, stocktake-count writes, transfer writes, purchase-order receiving, or location PAR writes. Purchase-order creation, auto-build and sending, stock adjustments, inventory management, supplier reorder levels and saleable reads are available. Use the polling and reconciliation guide for current integration patterns.

This reference was reviewed on 19 October 2026. See the API changelog for documented changes.