Getting Started with the BSimple API

The quickest way to try the BSimple API is to create a key, grant one read scope and make a request from a server-side application. The API is intended for portals, ordering systems, CRMs, dashboards and other applications that need selected BSimple data.

1. Create an API key

An administrator creates keys in Settings → API Keys inside BSimple. Give the key a name that identifies the integration, such as customer-portal-production or warehouse-dashboard-test.

The full secret is shown once. Copy it directly into a secure secret manager or environment variable. Never commit it to a repository or expose it in browser code.

2. Select the smallest useful scopes

Start with read-only access. For example:

inventory:read to read products and quantities.
locations:read to read warehouse locations.
customers:read to read customer records.
invoices:read to read invoices.

Add a write scope only when the integration has a clear requirement. Creating a draft invoice requires invoices:write. Read the full scope and endpoint reference before choosing permissions.

3. Store the key safely

Set the key in the environment of your server-side application:

export BSIMPLE_API_KEY='replace-with-your-key'
export BSIMPLE_API_BASE='https://<your-bsimple-domain>/api/v1'

The example is for local development. Use the secret-management facility appropriate to your hosting environment in production.

4. Make the first request

This request reads the first page of customers:

curl --fail --silent \
  --header "X-API-Key: ${BSIMPLE_API_KEY}" \
  "${BSIMPLE_API_BASE}/customers/list?page=1&per_page=20"

A successful response contains data and meta:

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

5. Handle errors deliberately

401: check that the key is present, current and sent in the header.
403: grant the required scope or change the endpoint used by the integration.
404: check the path and identifier.
409: treat the operation as a conflict and reconcile before retrying.
422: inspect the validation message and correct the request.

Do not retry every error. Retry only transient failures after confirming the API contract and use a bounded backoff strategy in the application.

6. Move to production

Before switching on a live integration:

Use a separate production key rather than reusing a development secret.
Grant only the scopes required by the live workflow.
Store the key outside source control and logs.
Log request IDs or safe error metadata, never the API key or full customer data.
Implement pagination for every list endpoint.
Add a reconciliation process for integrations that must remain consistent.
Document who owns key rotation and what happens when a key is revoked.

Next steps

Read the full BSimple API documentation, learn how to read inventory and stock, or build a draft invoice integration.

For a business-level overview, visit BSimple API.

Getting Started with the BSimple API