Belvak API and webhooks

Overview

The Belvak API is a REST API that returns and accepts JSON. Every request goes to a path under the base URL above, authenticated with an API key you create in your workspace. It reads and writes the same records you work with in the app, so a request through the API runs the same validation, tax, currency, and activity logging that the app does.

curl https://app.belvak.com/api/v1/me \
  -H "Authorization: Bearer bv_live_your_key_here"

Authentication

Create an API key in Settings, Integrations, API & Webhooks. Only an admin can manage keys, and API access is available on the Professional plan and above. A key is shown in full once, at the moment you create it, so copy it then. Keys belong to the workspace, not to the person who made them.

Send the key as a bearer token on every request:

Authorization: Bearer bv_live_...

You can rotate or revoke a key from the same screen, and the change takes effect immediately: a revoked key stops working on its very next request, even mid-session. A request with a missing or revoked key returns 401 invalid_key.

Conventions

• Public ids everywhere. Every id you send or receive is your per-workspace public id, the same number shown as #N in the app. Internal database ids are never exposed and never accepted. Relation fields are public ids too, for example client_id, project_id, invoice_id, and referral_id.
• Query parameters for reads. A single read and list filters use query parameters, never path segments. For example GET https://app.belvak.com/api/v1/invoices?id=42 returns invoice #42. An unrecognised query parameter returns 400 unsupported_param; an invalid limit or after_id value returns 400 invalid_input.
• Date-range filters. fromDate and toDate are inclusive YYYY-MM-DD dates, and each entity's filter list says which field the range applies to. Where that field is a creation timestamp (clients and proposals), the calendar day is evaluated in UTC, so a record created near your local midnight can file under the neighbouring UTC day. Plain date fields (project end dates, invoice service periods, payment dates) are compared exactly as stored.
• The body carries writes. Create, update, and delete send everything in the JSON body, including the record id for update and delete. A PUT or DELETE is addressed as https://app.belvak.com/api/v1/invoices with { "id": 42, ... } in the body, not as a query string. A query parameter on a write returns 400 unsupported_param; an unaccepted body field returns 400 unsupported_field.
• Update replaces the whole record. PUT is a full replace, not a patch: it expects the same fields as create, with the same required fields, and on most record types an optional field you leave out is cleared or reset to its default. Read the record first, then send every writable field you want to keep, with the values you want. Read-only response fields are not accepted back on a write. A few fields are kept, not cleared, when you leave them out of a PUT:
  • clients: phone, email, address, tax_number, and contacts (send address, tax_number, or contacts as null to clear them)
  • employees: ephone, hDate, emergency_contact_relation, expected_weekly_hours, hourly_cost_override with its effective date, and the location lat/lon
  • maintenances: contract_end_date (send null to clear it)
  • proposals: status (send a valid status to change it)
  • referrals: commission_currency
  Notes are the exception to full replace: a note update takes only title, note, and color, and all three are required.
• Pagination. List endpoints accept limit (default 100, maximum 500) and after_id, a cursor that is the public id of the last row you saw. Pass the last id back as after_id to fetch the next page.

  GET https://app.belvak.com/api/v1/clients?limit=100
  GET https://app.belvak.com/api/v1/clients?limit=100&after_id=100

• Rate limit. Requests are limited to about 30 per second per IP address. Over the limit, the API returns a plain 429 response. Slow down and retry.
• Module gates are additive. Even with API access, entities that belong to a module your plan does not include stay gated. A workspace without payroll or maintenance features gets a 403 feature error on the employees or maintenance endpoints, and that error passes straight through.

Responses

Every response is a JSON object with an ok flag. The shape depends on the call. Ids in the body are always your public ids.

List

GET https://app.belvak.com/api/v1/clients

{
  "ok": true,
  "data": [ { "id": 42, "clientName": "Acme Studio" } ],
  "count": 1,
  "has_more": false,
  "next_cursor": null
}

One record

GET https://app.belvak.com/api/v1/clients?id=42

{ "ok": true, "data": { "id": 42, "clientName": "Acme Studio" } }

Create

POST https://app.belvak.com/api/v1/clients

{ "ok": true, "id": 42 }

Update and delete

{ "ok": true }

Error

{ "ok": false, "error_code": "invalid_input", "message": "A human-readable reason." }

On a list, has_more tells you another page exists and next_cursor is the after_id to pass for it. On a successful create, id is the public id of the new record. A successful entity create returns HTTP 200; registering a webhook subscription is the one create that returns 201. Errors always carry an error_code, and usually a message; 404 responses carry the code alone.

Errors

Errors come back as JSON with an error_code you can branch on. Known errors carry the codes below. A validation error on a field (for example a missing required field) passes through with the same message the app would show.

Field validation reuses the same rules as the app, so a bad value comes back as invalid_input, or with a more specific code and message where the app has one (for example recurring_amount_required or invalid_recurring_interval on a recurring project). Branch on error_code and fall back to message.

A 500 server_error is deliberately opaque: the details are logged on our side and never returned, so nothing internal leaks to the caller.

Idempotency

To make a POST safe to retry, send an Idempotency-Key header with a value you choose (a UUID works well). It is optional, and only applies to creates.

curl https://app.belvak.com/api/v1/invoices \
  -X POST \
  -H "Authorization: Bearer bv_live_..." \
  -H "Idempotency-Key: 6f1c9b0e-2a7d-4f3e-9c11-8e2a7d4f3e9c" \
  -H "Content-Type: application/json" \
  -d '{"project_id": 42, "Amount": 1500, "due_date": "2026-08-01", "status": "Pending", "currency": "USD"}'

• Only a successful response is stored. Reuse the same key with the same body and the stored response is replayed, without creating a second record.
• If the first request fails with a 4xx error (a validation or permission problem), the key is released, so you can fix the request and retry with the same key.
• Reuse the same key with a different body and the request is rejected with 409 idempotency_conflict.
• Send it again while the first is still running and you get 409 idempotency_in_progress. Wait and retry.
• If the first request fails with a 5xx server error, or is interrupted before finishing (a dropped connection or a server restart), a later retry with that key returns 409 idempotency_interrupted. The record may or may not have been created, so check first, then retry with a new Idempotency-Key.

Keys are remembered for 24 hours.

Entities

Each of the eleven record types supports the same calls: list, read one, create, update, and delete. Notes are the one exception, they are always listed under a parent record and have no read-one call. The tables below list the fields you can write for each type (v1); fields marked required must be present on create, and again on update: an update is a full replace, so send the complete record, not just the fields that changed. Update and delete send the record id in the JSON body. Relation fields are public ids, and you send them by the public id of the related record: an unknown id returns 404 unknown_reference. Every list endpoint also accepts the pagination parameters.

Webhooks

Webhooks tell your systems when something changes in Belvak, so you do not have to poll. Register an endpoint, choose the events you care about, and Belvak posts to it as they happen. Manage subscriptions in Settings, or over the API:

The create body takes two fields: url, required, and events, an optional array of event names from the catalog below. Leave events out, or send it as null or an empty array, to subscribe to every event. An unknown event name is rejected, an unknown body field returns 400 unsupported_field, and a non-object body returns 400 invalid_json.

POST https://app.belvak.com/api/v1/webhooks
{ "url": "https://example.com/hooks/belvak" }

POST https://app.belvak.com/api/v1/webhooks
{ "url": "https://example.com/hooks/belvak",
  "events": ["invoice.created", "payment.created"] }

When you register an endpoint you get a signing secret, prefixed whsec_ and shown once. A PATCH body takes url, events, or action, where action is disable, enable, or rotate_secret. On PATCH and DELETE the subscription id can go in the query string as ?id= or in the JSON body. This is the one place an id is accepted on the query string for a write, because webhook management is a dedicated endpoint rather than one of the record types above.

The payload

Payloads are thin. They tell you what happened and where to read the full record, which you then fetch from the API. A *.deleted event is a tombstone: it carries the id of the record that was removed, and no self link. Note events also omit self, because notes have no single-record read: list them by their parent with entity_type and entity_id.

{
  "event": "invoice.created",
  "occurred_at": "2026-07-18T09:41:00Z",
  "delivery_id": "b6d1f0c2a9e34b7c8d5e6f7a8b9c0d1e",
  "workspace": { "name": "Acme Studio" },
  "entity": "invoice",
  "id": 42,
  "self": "https://app.belvak.com/api/v1/invoices?id=42"
}

Headers on every delivery

• Belvak-Event the event type, for example invoice.created
• Belvak-Delivery a unique id for this delivery, used to dedupe
• Belvak-Webhook-Id the public id of the subscription
• Belvak-Signature the signature, described below

Verifying the signature

Each delivery is signed with the subscription secret so you can confirm it really came from Belvak. The header looks like this:

Belvak-Signature: t=1750000000,v1=<hex>

To verify, take the timestamp t and the exact raw request body, join them with a dot as {t}.{rawBody}, and compute HMAC-SHA256 of that string using your secret. Compare it to the v1 value using a constant-time comparison. Verify against the raw body bytes, before any JSON parsing or re-serialising, since re-encoding changes the signature. Reject a delivery whose t is more than five minutes from your own clock, which blocks replays.

Worked example

With these fixed inputs you should get exactly this signature, which you can use to confirm your verification code:

secret     whsec_test_secret
timestamp  1750000000
raw body   {"event":"invoice.created"}

signed string:
1750000000.{"event":"invoice.created"}

HMAC-SHA256 (hex):
0556c1c4f94574349f40d02a3d8038ddf20d741c66fe42de885f695ff11fef86

full header:
Belvak-Signature: t=1750000000,v1=0556c1c4f94574349f40d02a3d8038ddf20d741c66fe42de885f695ff11fef86

Delivery

Delivery is best effort until an event is queued. Once queued, Belvak delivers at least once, so a duplicate is possible: dedupe on the Belvak-Delivery id and treat repeats as no-ops. Belvak retries automatically with a growing backoff for up to ten attempts, and an endpoint that keeps failing is disabled automatically. Because a single change can be logged more than once, you may see more than one event for it, which is another reason to make your handler idempotent. One deliberate gap: an invoice whose status flips because a payment landed does not emit invoice.updated. Hydrate the invoice after a payment.created instead.

Event catalog

There are 33 events, one created, updated, and deleted for each of the eleven record types:

Connection test

Call GET /me to check a key and see which workspace and plan it belongs to. It is the quickest way to confirm a key works before wiring up the rest.

GET https://app.belvak.com/api/v1/me

{
  "ok": true,
  "workspace": { "name": "Acme Studio" },
  "plan": { "name": "Professional" },
  "key": {
    "label": "Zapier",
    "prefix": "bv_live_a1b2",
    "last_used_at": "2026-07-18T09:41:00Z"
  }
}

plan.name is your plan name when it is set, and can be null for a legacy workspace. Likewise last_used_at is null until the key's first use.