Usage Guidelines


All out endpoints that return collections can be paginated in the same way, through two optional parameters: offset and limit

  1. Offset (Starting Position)
The offset parameter indicates the starting position within the collection, starting from index 0 by default.
  2. Limit (How Many)
The limit parameter specifies the maximum number of items to be included in the response, with a default value of 10. The maximum number of items that can be returned in one go is 50.


A Trial API key is limited to the first 10 search results only. This limit doesn’t apply to non-search endpoints.

Every response from a paginated endpoint contains a top-level property called pagination, which in turn contains the offset and limit values used in the API call, as well as the total number of items in the collection. For instance:

"pagination": {
  "offset": 0,
  "limit": 10,
  "total": 12

In the example above:

  • If you send an API call with offset = 10 and limit = 10, then the 11th and 12th items in the collection will be returned.
  • However, an API call with offset = 20 and limit = 10 would return a successful response (200 HTTP code) with an empty collection. This is because there are only 12 items in total in the collection and your starting position is requesting the 21st item.

Calls with invalid offset/limit parameters, such as negative values will return an error (400 HTTP code).

The pagination parameters are useful to use when working with endpoints that have extensive responses, such as Company Financials and Company Filings.

Rate Limiting

We have a default rate limit of 30 API calls per second. This means that within any given second, a maximum of 30 requests can be processed.

It's important to note that these requests should be evenly spread out over the second; you cannot send all 30 requests at the beginning of the second and expect them to be processed successfully.

We recommend implementing a back-off and retry logic in your application to manage this effectively and avoid hitting the rate limit 429 error. This approach helps to avoid provide a stable service to all clients continuously.


Whilst we generally don’t have usage quotas for our endpoints, there are some instances where we do, such as for the Comply Advantage PEPs, Sanctions and Adverse Media endpoints.

If you’re unsure about whether you have a quota, please reach out to [email protected] for further information. Alternatively, your contract with us should state the modules and endpoints you can access and any associated quota.

If you do have a quota, you can check out the quota usage by accessing the current quota configuration endpoint.

Error Handling

FullCircl follows standardised and well-established practices for HTTP status codes.

Every API call will return a status code and a message with a description issued by a server (FullCircl) in response to a client’s request.

The below table will help you to identify the root cause and the next steps to troubleshoot an error you have encountered.

200SUCCESSThe request has succeeded.
401UNAUTHORISED'Client is not authorised' or 'Access token is not authorised’.

This error signifies that the user failed to provide a valid authentication token (API Key). Check if the authentication token is passed correctly (X-AUTH-TOKEN as a header parameter).

Contact [email protected] to obtain or check your key.
403FORBIDDEN'Access denied'.

This error indicates that your API Key has insufficient access level for the requested information. To understand what API modules you have access to, please reach out to [email protected]
400BAD REQUESTThis error indicates that the server couldn't process the request due to a client error. For common bad requests, we specify what has gone wrong.

A common bad request seen is querying a country not supported by FullCircl or is not in the correct lowercase format.




'Maximum requests per second exceeded'.

Any of these 429s' responses related to allowance signify that the given key was given an absolute call limit or premium endpoints have hit their quota limit.

For inquiries about increasing your throughput or limits, contact your Customer Success Manager or email [email protected].
405METHOD_NOT_ALLOWED'Endpoint does not support this HTTP method'.

Ensure you are using the correct request type. For more information, refer to FullCircl API Documentation.
404NOT_FOUND'There is no matching company record'.

This error is typically seen if the request made using an incorrect path or query parameters. e.g. the companyID is invalid, or the country code doesn't align with the company id or there is a typo in the request.

Refer to FullCircl API Documentation for the required format for each endpoint. If the issue persists unexpectedly, contact [email protected]
503Service UnavailableIndicates a potential server error on FullCircl's side.

Check out the FullCircl status pages for updates.
500Internal Server ErrorIndicates a server error on FullCircl's side. If the issue persists, contact [email protected]
504Gateway Timeout
Endpoint unavailable
This indicates a server timeout error on FullCircl's side. If the issue persists, contact [email protected]

Didn't find what you were looking for? Contact [email protected]