Getting started

1. Requirement: access enabled

BMC enables API access for each company. Until it is active, the client area does not show the Developers section. If you do not see it, write to plataforma@bm.consulting with the company name.

The account holder (OWNER) or an administrator (ADMIN) of the company can create, edit, rotate and revoke tokens. Other users see the list but cannot change it.

2. Create a token

1. Sign in to the client area at https://app.bm.consulting/login with your email. You receive a one-time sign-in link: open it in the same browser.
2. Open Developers › API & MCP (https://app.bm.consulting/portal/desarrolladores), tab Credentials, and click Create API token.
3. Basic information. Under Description (required, up to 64 characters) say what it is for, for example "Monthly treasury report". Under What it is for (optional) note which integration uses it and who is responsible for it.
4. Permissions. Choose a level for each area or, inside an area, for each resource: None, Read, Write or Full. Advanced lets you pick action by action. Start with Read and add only what the integration needs (more on permissions).
5. Expand Token usage and fill in:
   • Companies and groups: which companies' data the token can see. The list shows the companies you administer that have API access enabled. You can pick single companies or Whole group (includes future subsidiaries). A group is included only if you choose it: picking one company does not add the rest of its group.
   • Primary account (quota and limits): one of the chosen companies, or one in a chosen group. The token uses that account's monthly quota and per-minute limits. It cannot be changed later; for another one, create a new token.
   • Expiry: a date. Empty, the token never expires.
   • Limits per minute (Read and Write): empty means 1,200 and 300 (Rate limits).
   • Own monthly quota: a cap on this token's calls per month, within the account quota. Empty, only the account quota applies.
   • Allowed IPs: one IP or CIDR range per line. Empty, any IP works. If you will use the token with the MCP server, leave it empty.
   • Can see personal data: unticked, tax ID, IBAN, phone, date of birth and address come back masked (Authentication).
6. Click Create token and copy the value, which looks like bmc_live_…: it is shown only once. Confirm with I have saved it.

In the Credentials list each token has a switch to turn it off and on again, and the actions Edit, Rotate (replaces the secret immediately; the old one stops working) and Revoke (permanent). The month's consumption is under the API usage tab.

3. Make your first call

This call lists your contacts. It requires the contacts:contacts.read permission, so the token needs at least the Read level on the Contacts resource.

export BMC_TOKEN="bmc_live_…"

curl -X GET "https://app.bm.consulting/api/v1/contacts?limit=50" \
  -H "Authorization: Bearer $BMC_TOKEN"

const res = await fetch("https://app.bm.consulting/api/v1/contacts?limit=50", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BMC_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://app.bm.consulting/api/v1/contacts?limit=50",
    headers={"Authorization": f"Bearer {os.environ['BMC_TOKEN']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()

4. Read the response

A successful response returns 200 and JSON. On this route the list comes in contacts together with the pagination fields. If the token cannot see personal data, the tax ID, phone and other personal data come back masked.

{
  "contacts": [
    {
      "id": "…",
      "firstName": "Ana",
      "lastName": "García",
      "fullName": "Ana García",
      "email": "ana@example.com",
      "nif": "A******21",
      "isActive": true
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50,
  "pages": 1
}

A 401 means the token is invalid, expired or revoked. A 403 means the token lacks the route's permission or the call comes from a disallowed IP. See Errors.

5. Find your company ids

Accounting routes carry the company in the path (/books/{companyId}/…). The companyId is the company's identifier at BMC. To see which companies your token reaches, call GET /auth/whoami, which requires no permission:

curl "https://app.bm.consulting/api/v1/auth/whoami" \
  -H "Authorization: Bearer $BMC_TOKEN"

{
  "token": { "id": "…", "prefix": "bmc_live_…", "name": "Monthly treasury report", "kind": "API" },
  "accountId": "cm…a1",
  "accountIds": ["cm…a1", "cm…b2", "cm…c3"],
  "audience": "client",
  "scopes": ["…"],
  "permissions": ["…"],
  "piiAccess": false,
  "expiresAt": null,
  "groupIds": ["cm…b2"]
}

• accountId: the token's primary account (quota and limits).
• accountIds: every company it reaches today, primary first, with group subsidiaries already included. Any of them is a valid companyId.
• groupIds: the groups chosen as a whole.

A companyId outside that list gets 403 or 404, with no data from another company.

Next steps

• Authentication: scope, expiry, rotation and allowed IPs.
• Permissions: the full catalogue.
• API reference: every operation with examples.

Base URL: https://app.bm.consulting/api/v1