Back to guides

Getting started with the Bill Alps API

What the REST v1 API covers, how to get a key safely on the sandbox, and the first call that tells you which companies you can act on.

Developers6 min read
Table of contents+

The Bill Alps public API exposes, over REST, what the application does on screen: clients, invoices, quotes, employees, payslips, expenses and accounting. This guide takes you from zero to a first successful call, on the sandbox, without touching your production data.

BASE=https://<deployment>.convex.site/api/v1
KEY=ba_...

1. What the API covers

The v1 API runs on top of the same code as the application: every route calls the app's business logic, with the same checks, the same quotas and the same PDFs. Whatever is refused on screen is refused by the API, and the other way round.

  • Account and companies: /me, /companies, /mandates for trustees.
  • Invoicing: clients, invoice templates, invoices, quotes, recurring invoices, with their PDFs and their email sending.
  • Payroll: employees, payslips (single and batch), absences.
  • Expenses and accounting: vendor expenses, imported bank transactions, the annual financial statement.

Company-addressed routes (/companies/{companyId}/…) require that company to be on the Business plan, with the relevant module (invoicing, payroll, expenses, financial statements) switched on. Keys are server-to-server credentials: the endpoints have no CORS, by design, so never put a key in a browser or a mobile app.

2. Start on the sandbox

In the sandbox every company reads as Business whatever its real plan, which opens every route even to a Free account. Emails are not delivered, Stripe bills nothing, team invitations do not go out. Everything else runs, including the scheduled jobs: it is the right place to build and test an integration.

3. Create a key

  • Create the key from any Business company you administer — the company only gates the creation; the key itself is personal and carries no company.
  • You need the owner or admin role on the active company, and it must be on Business (in the sandbox, it always is).
  • A key belongs to the person who created it, not to the company: it acts on every company that person can access, with their permissions. Up to 10 active keys per user.
  • To rotate a key: create a second one, migrate your integration, then revoke the first from the same screen.

4. Base URL and header

The API does not live on the application host but on the Convex deployment that serves it: a .convex.site address, printed in the API keys panel right under your keys. The sandbox panel prints the sandbox address, the production one the production address; keys are not interchangeable between the two, a sandbox key is unknown to production.

Every request carries the key in the Authorization header:

Authorization: Bearer ba_...

5. First call

The first call to make is GET /me: it tells you who holds the key and what it can act on.

curl -H "Authorization: Bearer $KEY" $BASE/me

The response holds data.companies[], each company with its id, your role, its effective plan and its modules. Those ids are the ones every /companies/{companyId}/… route takes. The same list exists as a plain array:

curl -H "Authorization: Bearer $KEY" $BASE/companies

A company on Free or Team appears in the list, but its routes answer 403 PLAN_NOT_ALLOWED. Pick a company whose module you care about is on, and you are ready for the next guides.

6. Interactive documentation

Every deployment describes itself. At https://<deployment>.convex.site/api/docs, a Swagger UI shows the live contract: click Authorize, paste a ba_ key, then "Try it out" on any route. The key stays in the browser's local storage until you Logout, so prefer a revocable key and the sandbox.

The OpenAPI 3.1 document is served at https://<deployment>.convex.site/api/v1/openapi.json, public, no key, CORS open. It is generated on request from the route table and the request and response schemas: what it describes is exactly what the API enforces. servers[0].url is the origin you fetched it from, so production and sandbox each point at themselves. Paste the URL into editor.swagger.io to browse it, or use it to generate a client.

On the sandbox, the AccountAPI keys panel also offers a "Documentation DEV" link to the application's data model (entity-relationship diagram), useful to understand how the resources hang together.

Read the rest in whichever order suits you: invoicing with the API, payroll, expenses and accounting with the API and, for the cross-cutting rules, conventions and errors. Your deployment's Swagger UI remains the reference for every field.