HelloBooks / Agents

Build and connect

All HelloBooks APIs, in one place.

Find an endpoint, inspect its parameters, and open its documentation. Browse public data here or connect a company through the authenticated accounting API.

31 public endpoints43 MCP tools491 accounting operations

Find an accountantCatalog JSONAccounting OpenAPIDeveloper quickstart
Clear filters

1 matching APIs

Authenticated accounting

Create customers (hand-written route)

POST /public/v1/orgs/{orgId}/entities/{entityId}/customers

Predates the generic factory; see the GET. The route normalises a bare object or a bare array into `{ Customers: [...] }` before calling the internal controller, so all three body forms are accepted. DECLARED FIELD-CONTRACT GAP: this route is listed in `UNCONTRACTED_ROUTE_PREFIXES` in `middlewares/publicApiSerialize.middleware.js`. The response field allowlist does not apply to it; only the deny-key floor does. It is named here rather than omitted.

OAuth 2.0; company authorization and operation scopes required

Request example

curl --request POST 'https://sandboxapi.hellobooks.ai/public/v1/orgs/{orgId}/entities/{entityId}/customers' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' --data @request.json

Replace tenant/path placeholders and prepare request.json from the published request schema when needed.
Complete published contract
{
  "operationId": "createCustomersLegacy",
  "summary": "Create customers (hand-written route)",
  "description": "Predates the generic factory; see the GET. The route normalises a bare object or a bare array into `{ Customers: [...] }` before calling the internal controller, so all three body forms are accepted.\n\nDECLARED FIELD-CONTRACT GAP: this route is listed in `UNCONTRACTED_ROUTE_PREFIXES` in `middlewares/publicApiSerialize.middleware.js`. The response field allowlist does not apply to it; only the deny-key floor does. It is named here rather than omitted.",
  "tags": [
    "customers"
  ],
  "security": [
    {
      "marketplaceOAuth2": [
        "contacts:write"
      ]
    },
    {
      "marketplaceOAuth2": [
        "book:write"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Success.",
      "headers": {
        "RateLimit": {
          "description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
          "schema": {
            "type": "string"
          }
        },
        "RateLimit-Policy": {
          "description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
          "schema": {
            "type": "string"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true,
            "description": "Response shape is not published for this route. The publishable field contract for this resource is NOT yet published, so this description does not enumerate its fields. The response body is a JSON object whose shape is whatever the internal controller emits. Do not read the absence of properties here as 'this resource has no fields' — it means 'HelloBooks has not yet committed to a field list for it'. The contract lands in routes/publicApi.fields.generated.js; this file regenerates from it.",
            "x-hellobooks-field-contract": "unpublished"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "402": {
      "$ref": "#/components/responses/PaymentRequired"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/ServerError"
    },
    "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
    }
  },
  "x-hellobooks-source": "hand-written",
  "x-hellobooks-field-contract": "declared-gap",
  "x-hellobooks-tenant-guard": true,
  "x-hellobooks-required-scopes": [
    "contacts:write"
  ],
  "x-hellobooks-scope-grain": "granular",
  "parameters": [
    {
      "$ref": "#/components/parameters/orgId"
    },
    {
      "$ref": "#/components/parameters/entityId"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "description": "Accepted as `{ Customers: [ ... ] }`, a bare array of customer objects, or a single bare customer object. Field-level shape is not published — this route is a declared field-contract gap.",
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "Customers": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                }
              },
              "required": [
                "Customers"
              ]
            },
            {
              "type": "array",
              "items": {
                "type": "object"
              }
            },
            {
              "type": "object"
            }
          ]
        }
      }
    }
  },
  "referenceUrl": "https://agents.hellobooks.ai/api/developer-reference.json",
  "scopeRule": "OpenAPI security array entries are alternatives (OR); scopes inside one security requirement are cumulative (AND).",
  "environment": "Use the developer portal for sandbox setup and production access. API metadata does not prove a deployed operation is available.",
  "components": {
    "responses": {
      "Unauthorized": {
        "description": "Missing, malformed, expired or revoked bearer token, or a disabled client.",
        "headers": {
          "RateLimit": {
            "description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
            "schema": {
              "type": "string"
            }
          },
          "RateLimit-Policy": {
            "description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GatewayError"
            },
            "examples": {
              "invalid_token": {
                "value": {
                  "error": "invalid_token",
                  "message": "Token invalid or expired."
                }
              },
              "invalid_client": {
                "value": {
                  "error": "invalid_client",
                  "message": "Client disabled."
                }
              }
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "The tenant's AI-credit wallet cannot cover this request. Charged before any tenant work; the deduction settles only on a <400 response.",
        "headers": {
          "RateLimit": {
            "description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
            "schema": {
              "type": "string"
            }
          },
          "RateLimit-Policy": {
            "description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AiCreditsError"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Denied. THREE different bodies land on this status: the token is not bound to the org/entity in the path (`tenant_scope_violation`), the token lacks the scope the route requires (`insufficient_scope`), or the organisation's plan does not include API access — which returns the entitlement shape, not the gateway shape.",
        "headers": {
          "RateLimit": {
            "description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
            "schema": {
              "type": "string"
            }
          },
          "RateLimit-Policy": {
            "description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/GatewayError"
                },
                {
                  "$ref": "#/components/schemas/EntitlementError"
                }
              ]
            },
            "examples": {
              "tenant_scope_violation": {
                "value": {
                  "error": "tenant_scope_violation",
                  "message": "Token not authorized for this entity."
                }
              },
              "insufficient_scope": {
                "value": {
                  "error": "insufficient_scope",
                  "message": "Missing scope: book:write",
                  "required": [
                    "book:write"
                  ]
                }
              },
              "plan_denied": {
                "value": {
                  "success": false,
                  "error": {
                    "code": "FEATURE_NOT_IN_PLAN",
                    "plan": "free",
                    "upgradeTo": "pro",
                    "upgradeUrl": "/settings/subscription?intent=upgrade",
                    "feature": "ApiAccess"
                  }
                }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded for this (clientId, installId) pair. Default 120 requests per 60s; see the description at the top of this document for the per-app override and the plan-derived ceiling.",
        "headers": {
          "RateLimit": {
            "description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
            "schema": {
              "type": "string"
            }
          },
          "RateLimit-Policy": {
            "description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
            "schema": {
              "type": "string"
            }
          },
          "Retry-After": {
            "description": "Seconds until the window resets.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GatewayError"
            },
            "examples": {
              "rate_limited": {
                "value": {
                  "error": "rate_limited",
                  "message": "Public API rate limit exceeded."
                }
              }
            }
          }
        }
      },
      "ServerError": {
        "description": "Unhandled failure. The generic resource gateway also returns 500 with `controller_load_failed` or `handler_missing` when a registry row names a controller or export that does not resolve — binding is lazy and per-request, so a bad row fails on its own route rather than at boot.",
        "headers": {
          "RateLimit": {
            "description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
            "schema": {
              "type": "string"
            }
          },
          "RateLimit-Policy": {
            "description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GatewayError"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The AI-credit balance check itself was unavailable.",
        "headers": {
          "RateLimit": {
            "description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
            "schema": {
              "type": "string"
            }
          },
          "RateLimit-Policy": {
            "description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AiCreditsError"
            }
          }
        }
      }
    },
    "schemas": {
      "GatewayError": {
        "type": "object",
        "description": "The error shape emitted by the /public/v1 gateway middlewares (authentication, tenant match, scope, rate limit, controller binding).",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable machine-readable code."
          },
          "message": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Present on `insufficient_scope`: the scopes that were missing."
          },
          "resource": {
            "type": "string",
            "description": "Present on `controller_load_failed` / `handler_missing`: the registry `seg`."
          },
          "handler": {
            "type": "string",
            "description": "Present on `handler_missing`: the controller export that was absent."
          },
          "detail": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "AiCreditsError": {
        "type": "object",
        "description": "AI-credit metering refusal. Every /public/v1 request except /health, /me and the books draft→commit flow is charged against the install's tenant AI-credit wallet before any tenant work happens.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "INSUFFICIENT_AI_CREDITS",
              "AI_CREDITS_CHECK_UNAVAILABLE",
              "MISSING_ORG_OR_ENTITY"
            ]
          },
          "feature": {
            "type": "string"
          },
          "requiredUSD": {
            "type": "number"
          },
          "balanceUSD": {
            "type": "number"
          },
          "creditBalance": {
            "type": "number"
          },
          "requiredCredits": {
            "type": "number"
          },
          "topUpUrl": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "EntitlementError": {
        "type": "object",
        "description": "A SECOND, DIFFERENT error shape. Plan-entitlement denials (`requireApiAccessFeature`) do not use the gateway shape above — they return the first-party subscription-guard payload, in which `error` is an OBJECT rather than a string. A client that reads `body.error` as a string will get `[object Object]` here. This divergence is real and is described rather than smoothed over.",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "object",
            "required": [
              "code"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "FEATURE_NOT_IN_PLAN",
                  "LIMIT_EXCEEDED"
                ]
              },
              "plan": {
                "type": "string"
              },
              "upgradeTo": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "upgradeUrl": {
                "type": "string"
              },
              "feature": {
                "type": "string"
              },
              "limitKey": {
                "type": "string"
              },
              "limit": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "current": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      }
    },
    "parameters": {
      "orgId": {
        "name": "orgId",
        "in": "path",
        "required": true,
        "description": "The organisation the call targets. MUST equal the OrgRefId the access token's AppInstall is bound to — `requireTenantParamMatch` returns 403 `tenant_scope_violation` otherwise. There is no cross-tenant form of this API.",
        "schema": {
          "type": "string"
        }
      },
      "entityId": {
        "name": "entityId",
        "in": "path",
        "required": true,
        "description": "The entity (book) within the organisation. MUST equal the install's EntityRefId; see `orgId`.",
        "schema": {
          "type": "string"
        }
      }
    },
    "securitySchemes": {
      "marketplaceOAuth2": {
        "type": "oauth2",
        "description": "Authorization-code OAuth 2.0 against the HelloBooks marketplace provider. The access token's audience is `marketplace_app`; it is bound to one AppInstall, and therefore to exactly one (org, entity) pair. Public clients use PKCE (`code_challenge` / `code_challenge_method` are accepted on /oauth/authorize).\n\nScopes are GRANULAR: 14 domains x {read, write} = 28 scopes, derived from the internal RBAC permission entity each of the 100 registry resources already gates on, folded onto the module axis of the RBAC v2 manifest. `book:read` and `book:write` are NOT deprecated and NOT removed — they remain first-class grantable BUNDLE scopes that expand to every granular read / write scope respectively, which is why every token issued before this vocabulary existed keeps working unchanged. Request the narrowest domains you need; ask for a bundle only if you genuinely need the whole surface.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.hellobooks.ai/oauth/authorize",
            "tokenUrl": "https://api.hellobooks.ai/oauth/token",
            "refreshUrl": "https://api.hellobooks.ai/oauth/token",
            "scopes": {
              "book:read": "Read all of your books data (legacy bundle — grants every read scope)",
              "book:write": "Create and update all of your books data (legacy bundle — grants every write scope)",
              "accounting:read": "Read: Chart of accounts, journals, ledger, classes, locations, budgets and tax rates",
              "accounting:write": "Create, update and delete: Chart of accounts, journals, ledger, classes, locations, budgets and tax rates",
              "banking:read": "Read: Bank transactions, transaction lines, categorisation, cashbook, transfers and reconciliation links",
              "banking:write": "Create, update and delete: Bank transactions, transaction lines, categorisation, cashbook, transfers and reconciliation links",
              "sales:read": "Read: Invoices, quotes, sales orders, credit notes, delivery challans, recurring invoices, customer advances and leads",
              "sales:write": "Create, update and delete: Invoices, quotes, sales orders, credit notes, delivery challans, recurring invoices, customer advances and leads",
              "purchases:read": "Read: Bills, purchase orders, purchase requests, RFQs, goods receipts, vendor prepayments and expenses",
              "purchases:write": "Create, update and delete: Bills, purchase orders, purchase requests, RFQs, goods receipts, vendor prepayments and expenses",
              "contacts:read": "Read: Customers, vendors, business owners, their addresses, contact people, groups and balances",
              "contacts:write": "Create, update and delete: Customers, vendors, business owners, their addresses, contact people, groups and balances",
              "payments:read": "Read: Payments received and made",
              "payments:write": "Create, update and delete: Payments received and made",
              "paymentmethods:read": "Read: Stored credit and debit card details for customers, vendors, employees and owners",
              "paymentmethods:write": "Create, update and delete: Stored credit and debit card details for customers, vendors, employees and owners",
              "inventory:read": "Read: Items and stock records",
              "inventory:write": "Create, update and delete: Items and stock records",
              "reports:read": "Read: Balance sheet, profit and loss, cash flow, gross profit and revenue-by-customer reports",
              "reports:write": "Create, update and delete: Balance sheet, profit and loss, cash flow, gross profit and revenue-by-customer reports",
              "fixedassets:read": "Read: Fixed assets, asset groups, disposals, surveys, transfers and depreciation timing",
              "fixedassets:write": "Create, update and delete: Fixed assets, asset groups, disposals, surveys, transfers and depreciation timing",
              "projects:read": "Read: Projects and job tracking",
              "projects:write": "Create, update and delete: Projects and job tracking",
              "payroll:read": "Read: Employee records and employee addresses",
              "payroll:write": "Create, update and delete: Employee records and employee addresses",
              "comments:read": "Read: Comments attached to documents",
              "comments:write": "Create, update and delete: Comments attached to documents",
              "webhooks:read": "Read: Your app's webhook subscriptions",
              "webhooks:write": "Create, update and delete: Your app's webhook subscriptions"
            }
          }
        },
        "x-hellobooks-scope-model": {
          "grain": "granular",
          "source": "utils/publicApiScopes.util.js",
          "domainCount": 14,
          "granularScopeCount": 28,
          "domains": [
            {
              "name": "accounting",
              "label": "Chart of accounts, journals, ledger, classes, locations, budgets and tax rates",
              "read": "accounting:read",
              "write": "accounting:write",
              "manifestModule": "accounting"
            },
            {
              "name": "banking",
              "label": "Bank transactions, transaction lines, categorisation, cashbook, transfers and reconciliation links",
              "read": "banking:read",
              "write": "banking:write",
              "manifestModule": "banking"
            },
            {
              "name": "sales",
              "label": "Invoices, quotes, sales orders, credit notes, delivery challans, recurring invoices, customer advances and leads",
              "read": "sales:read",
              "write": "sales:write",
              "manifestModule": "sales"
            },
            {
              "name": "purchases",
              "label": "Bills, purchase orders, purchase requests, RFQs, goods receipts, vendor prepayments and expenses",
              "read": "purchases:read",
              "write": "purchases:write",
              "manifestModule": "purchases"
            },
            {
              "name": "contacts",
              "label": "Customers, vendors, business owners, their addresses, contact people, groups and balances",
              "read": "contacts:read",
              "write": "contacts:write",
              "manifestModule": "contacts"
            },
            {
              "name": "payments",
              "label": "Payments received and made",
              "read": "payments:read",
              "write": "payments:write",
              "manifestModule": null,
              "manifestNote": "split out of banking — money movement, separate on the Intuit precedent"
            },
            {
              "name": "paymentmethods",
              "label": "Stored credit and debit card details for customers, vendors, employees and owners",
              "read": "paymentmethods:read",
              "write": "paymentmethods:write",
              "manifestModule": null,
              "manifestNote": "no manifest module; stored payment-instrument detail, isolated deliberately"
            },
            {
              "name": "inventory",
              "label": "Items and stock records",
              "read": "inventory:read",
              "write": "inventory:write",
              "manifestModule": "inventory"
            },
            {
              "name": "reports",
              "label": "Balance sheet, profit and loss, cash flow, gross profit and revenue-by-customer reports",
              "read": "reports:read",
              "write": "reports:write",
              "manifestModule": "reports"
            },
            {
              "name": "fixedassets",
              "label": "Fixed assets, asset groups, disposals, surveys, transfers and depreciation timing",
              "read": "fixedassets:read",
              "write": "fixedassets:write",
              "manifestModule": null,
              "manifestNote": "internal permission entities exist; no manifest v2 module yet"
            },
            {
              "name": "projects",
              "label": "Projects and job tracking",
              "read": "projects:read",
              "write": "projects:write",
              "manifestModule": null,
              "manifestNote": "internal `project:*` permission entity; no manifest v2 module yet"
            },
            {
              "name": "payroll",
              "label": "Employee records and employee addresses",
              "read": "payroll:read",
              "write": "payroll:write",
              "manifestModule": "payroll"
            },
            {
              "name": "comments",
              "label": "Comments attached to documents",
              "read": "comments:read",
              "write": "comments:write",
              "manifestModule": null,
              "manifestNote": "internal `comment:*` permission entity; cross-cutting annotations, no manifest module"
            },
            {
              "name": "webhooks",
              "label": "Your app's webhook subscriptions",
              "read": "webhooks:read",
              "write": "webhooks:write",
              "manifestModule": null,
              "manifestNote": "not a registry resource; the app's own webhook subscriptions"
            }
          ],
          "bundles": {
            "book:read": {
              "description": "Read all of your books data (legacy bundle — grants every read scope)",
              "expandsTo": [
                "accounting:read",
                "banking:read",
                "sales:read",
                "purchases:read",
                "contacts:read",
                "payments:read",
                "paymentmethods:read",
                "inventory:read",
                "reports:read",
                "fixedassets:read",
                "projects:read",
                "payroll:read",
                "comments:read",
                "webhooks:read"
              ]
            },
            "book:write": {
              "description": "Create and update all of your books data (legacy bundle — grants every write scope)",
              "expandsTo": [
                "accounting:write",
                "banking:write",
                "sales:write",
                "purchases:write",
                "contacts:write",
                "payments:write",
                "paymentmethods:write",
                "inventory:write",
                "reports:write",
                "fixedassets:write",
                "projects:write",
                "payroll:write",
                "comments:write",
                "webhooks:write"
              ]
            }
          },
          "compatibilityRules": [
            "`book:read` expands to every `<domain>:read`.",
            "`book:write` expands to every `<domain>:write`. It deliberately does NOT expand to reads — a write-only token cannot reach a read route today, and that stays true.",
            "Webhook subscription management was gated by nothing beyond a valid bearer token, so `webhooks:read` + `webhooks:write` are granted to any token carrying either bundle AND to any token carrying no granular public-API scope at all. That covers live installs on unrelated vocabularies. Only a NEW grant that opted into granular scopes is held to them."
          ],
          "expansionIsCheckedAtTheGuard": "middlewares/appAccessToken.middleware.js expands the granted list before requireScope() tests it, and never rewrites it: GET /me still reports exactly what was granted, not the expansion.",
          "coarseByDesign": [
            "POST /oauth/register (dynamic client registration) grants only the two bundles.",
            "The /books/drafts draft -> confirm -> commit routes require only the bundles.",
            "Both because AI-MCP-Hellobooks understands exactly four scope strings and ignores the rest, so a granular scope would grant its connector nothing."
          ],
          "notGrantableOnThisApi": {
            "scopes": [
              "owner:close",
              "audit:export"
            ],
            "reason": "Part of the marketplace catalog and enforced by AI-MCP-Hellobooks, but checked by no /public/v1 route. Listing them among this API's scopes would imply they grant something here. They do not."
          }
        }
      }
    }
  }
}

This API as JSON · Full reference and referenced schemas