API basics and rate limits

The REST API lets your stack read customers and invoices, record payments, and inspect the message log — within the scopes on the key. Rate limits do not change when you change plan.

Before you start

1. An Admin has issued a key (see Issue and use API keys).
2. You stored the secret on a server. PayBlah cannot show it again.

Prove the key

1. Send GET /api/v1/me with Authorization: Bearer plus the secret.
2. Read the account name, the key label, the prefix, the effective scopes, and that key’s hourly limit.

What the API can reach

These are the live resources:

• GET /api/v1/me — no extra scope; proves the key and names the account.
• GET or POST /api/v1/debtors, GET /api/v1/debtors/{id} (Customers in the product nav).
• GET or POST /api/v1/invoices, GET /api/v1/invoices/{id}
• GET or POST /api/v1/payments
• GET /api/v1/messages — read only. There is no send-a-reminder endpoint.

Writes are JSON only (Content-Type: application/json). Amounts are integer minor units with an explicit currency. Recording a payment requires an Idempotency-Key header so a retry cannot record the money twice.

Rate limits

• Settings foot, on every plan: “Each key is limited to 600 requests per hour; every response carries X-RateLimit-Remaining, and going over gets a 429 saying when to retry.”
• GET /api/v1/me reports that key’s hourly figure under key.rate_limit.
• Authenticated responses also carry X-RateLimit-Limit and X-RateLimit-Reset.
• Over the limit: 429, a message such as “Rate limit of 600 requests per hour reached. Try again in N seconds.”, and a Retry-After header. Back off. Do not spin.

Expected result

A valid key returns JSON. Remaining counts down through the hour. At the cap, further calls wait for the window to reset.

If something goes wrong

• 401 — missing, malformed, or revoked key. Issue a new one if the secret is gone.
• 403 insufficient_scope — this key does not carry that scope. An Admin issues a new key with the needed ticks; you cannot add scopes to an existing key.
• 415 — send JSON, not a form body.
• 423 — the account is read-only (suspended, cancelled, or a trial that still needs resume). GET still works; writes do not.
• 429 — wait for Retry-After.

Habits that stay inside the rails

• Prefer webhooks for “something happened” instead of polling every minute.
• Use read-only scopes for reporting tools.
• The API cannot skip the kill switch, Firm/Final approval, demo refusal, or stop-on-payment. See API cannot bypass safety rails.