Credit Balance API

Documentation for the public website describing the new Credit Balance endpoint.

It lets customers check how many credits remain on their subscription, using their API key.

Note: All API keys shown below are placeholders. Never publish real API keys.

Overview


Method	GET
Produces	application/json
Path	/rest/v5.3/accounting/creditbalance
Authentication	Via the apiKey query parameter

The endpoint returns the remaining credits for the given API key. Two summary fields answer the most common question directly:

hasCredits — true if the account can still make calls, i.e. at least one credit of any kind is left.
totalRemaining — the total number of credits that can be spent right now: free + monthly + one-time.

The rest of the response gives the breakdown:

Free credits — the remaining free credits on the account.
Monthly balances — one entry per active monthly subscription contract, with the monthly allowance, the credits remaining in the current period, and the date the current period ends (when the allowance resets). A monthly contract is listed even when its credits for the current period are used up, so that the reset date stays visible.
One-time balances — one entry per purchased one-time credit package that still has credits left, with the total purchased credits, the credits remaining, and the expiry date (if any). Packages that are used up or have expired are not listed.

Request

Query parameters

Parameter	Type	Required	Description
apiKey	string	yes	The api-key, also known as user-id. Authentication and accounting are performed on the server for this key.
envelope	boolean	no	Set to true to wrap the result in a JSON envelope. Defaults to false.

Example request

GET /rest/v5.3/accounting/creditbalance?apiKey=YOUR-API-KEY

With curl:

curl "https://api.nameapi.org/rest/v5.3/accounting/creditbalance?apiKey=YOUR-API-KEY"

Response

Fields

Field	Type	Description
hasCredits	boolean	true if calls can still be made, i.e. totalRemaining is greater than 0.
totalRemaining	number	Sum of all credits that can be spent right now: free + monthly + one-time.
freeCreditsRemaining	number	Remaining free credits on the account.
monthlyBalances	array	One entry per active monthly subscription contract.
monthlyBalances[].maxPerMonth	number	The credit allowance per month for this contract.
monthlyBalances[].remaining	number	Credits remaining in the current billing period.
monthlyBalances[].periodEnd	string	Date (YYYY-MM-DD) when the current billing period ends and the allowance resets.
oneTimeBalances	array	One entry per purchased one-time credit package that still has credits left. Used-up and expired packages are not listed.
oneTimeBalances[].totalCredits	number	Total credits originally purchased in this package.
oneTimeBalances[].remaining	number	Credits remaining in this package. Always greater than 0.
oneTimeBalances[].endDate	string or null	Expiry date (YYYY-MM-DD) of the package, or null if it does not expire.

Example: account with a monthly subscription and a one-time package

Request:

GET /rest/v5.3/accounting/creditbalance?apiKey=YOUR-API-KEY

Response 200 OK:

{
  "freeCreditsRemaining": 13000,
  "monthlyBalances": [
    {
      "maxPerMonth": 100000,
      "remaining": 100000,
      "periodEnd": "2026-10-09"
    }
  ],
  "oneTimeBalances": [
    {
      "totalCredits": 1000000,
      "remaining": 607785,
      "endDate": null
    }
  ],
  "totalRemaining": 720785,
  "hasCredits": true
}

This account can still make calls (hasCredits is true) and has 720,785 credits in total: 13,000 free credits, a monthly subscription of 100,000 credits/month (untouched in the current period, which resets on 2026-07-07), and a one-time package of 1,000,000 credits with 607,785 remaining and no expiry date.

The response always has the same shape — only the sections that apply to the account are populated:

Free account (no paid contracts): only freeCreditsRemaining is set; monthlyBalances and oneTimeBalances are empty arrays. totalRemaining equals freeCreditsRemaining.
Monthly subscription only: monthlyBalances contains one entry per active contract; oneTimeBalances is empty.
One-time packages only: oneTimeBalances contains one entry per package with credits left; monthlyBalances is empty. If a package has an expiry date, endDate is set to that date (YYYY-MM-DD) instead of null.
All credits used up: hasCredits is false and totalRemaining is 0. Monthly contracts are still listed with remaining: 0 so the next reset date is visible; oneTimeBalances is empty.

Example: with envelope

Request:

GET /rest/v5.3/accounting/creditbalance?apiKey=YOUR-API-KEY&envelope=true

Response 200 OK — the payload is wrapped in a success envelope. The result field contains the credit balance as a JSON-encoded string:

{
  "success": true,
  "result": "{\"freeCreditsRemaining\":13000,\"monthlyBalances\":[{\"maxPerMonth\":100000,\"remaining\":100000,\"periodEnd\":\"2026-07-07\"}],\"oneTimeBalances\":[{\"totalCredits\":1000000,\"remaining\":607785,\"endDate\":null}],\"totalRemaining\":720785,\"hasCredits\":true}",
  "error": null
}

Error responses

Status	Meaning	When
400 Bad Request	Invalid API key format	The apiKey value does not match the expected key format. The response body contains the text Invalid API key format.
401 Unauthorized	Unknown API key or inactive account	The key is syntactically valid but is not known to the system, or the account is not active. The response body is empty.

Example: invalid key format

GET /rest/v5.3/accounting/creditbalance?apiKey=not-a-valid-key

Response 400 Bad Request:

Invalid API key format

Example: unknown key

GET /rest/v5.3/accounting/creditbalance?apiKey=00000000000000000000000000000000-nobody

Response 401 Unauthorized (empty body).

Notes

Querying the credit balance does not consume credits.
To know whether calls can still be made, read hasCredits; to show a single number, read totalRemaining. The arrays are only needed for a detailed breakdown.
The endpoint is read-only (GET) and safe to poll, e.g. for usage dashboards or low-balance alerts.
Swagger/OpenAPI documentation for this endpoint is also available in the server's Swagger UI under the /accounting tag.