Skip to content

API requests, responses and errors

Send each call as a POST to /api/<role>/<module>/<call> with the parameters as a JSON object and the Content-Type: application/json header. Form fields work too. A call without parameters takes {}. Parameter names are the ones in the API reference.

Terminal window
curl --silent --user "admin:$CLIENTFENCE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"id": 42}' \
https://billing.example.com/api/admin/invoice/get

Body JSON that cannot be read answers Malformed JSON input with the reason.

Every answer is a JSON object with two fields:

{ "result": { "id": 42, "status": "unpaid", "total": 25.5 }, "error": null }
  • result: what the call returns (an object, a list, true, an id). The reference describes it for each call.
  • error: null when the call worked, otherwise an object with message and code.
{ "result": null, "error": { "message": "Invoice not found", "code": 9999 } }

Always check error: many errors answer with HTTP status 200. An error without a code of its own has code 9999. These codes set the HTTP status:

HTTP status Codes Meaning
401 201-206 Authentication Failed: no key, a wrong key or a wrong user name. See Authentication.
401 1002 Unauthorized IP: the key is used from an address not on the API key access list.
403 403 A missing permission, a wrong CSRF token, or an action the account may not do.
404 740 The call does not exist in that module and role.
200 715 The module is not installed or not active.
400 701, 879 The URL is not an API call (a wrong role or path).
429 429 Rate limit exceeded. Wait the seconds in the Retry-After header. See Rate limits.
503 503 An update is waiting to be finalized.

Other errors explain the problem in message (a missing parameter, an invalid value, a record not found) and answer HTTP 200. Show message to the person using your integration or log it. For client and guest calls, an unexpected server error answers An unexpected error occurred. Please try again later. and the details go to the logs (System Activity and the files under data/log/).

Calls that list records (most get_list calls) return one page at a time:

Parameter Default
page 1 The page number, from 1.
per_page 100 Rows per page, 1 to 500. A larger number is an error.
{ "pages": 3, "page": 1, "per_page": 100, "total": 245, "list": [ { "id": 1 }, { "id": 2 } ] }

An empty object, such as a record’s config or translations with nothing in it, comes back as an empty list [], so treat [] and {} alike.

total is the number of rows over all pages and pages the number of pages. Ask for the next page until it is greater than pages. Each call’s filters (status, client, dates) are in the reference.

  • Dates and times are strings like 2026-11-17 09:30:00, in the time zone of the billing server.
  • In list filters and statistics, date_to includes that whole day: 2026-11-17 also finds records from 23:00 that day. A date ClientFence cannot read, in a filter or in an order, invoice or promotion date, is refused with Enter a valid date. The API log list ignores it instead.
  • Amounts are numbers, such as 25.5, in the currency of the record: an invoice’s currency field, or the client’s currency. They are not formatted and carry no currency sign.
  • Ids are numbers. Yes/no values are true/false or 1/0, as the reference says for each call.
Calls Limit
Admin and client calls 1,000 an hour for each account when signed in with a session; 1,000 an hour for each address otherwise, such as with an API key
Guest calls 100 a minute for each address
Failed sign-in calls (staff/login, client/login and passkey sign-in) 10 an hour for each address

Some guest calls have lower limits of their own, such as sign-up, domain search, promo codes and invoice links. Over a limit the call answers code 429 with a Retry-After header. Requests from the addresses in Never rate limited (Security → Settings → Access lists) skip every limit: add your integration server there. See Proxies, access lists and sessions. Every limit, and how to reset one, is on Rate limits.