Usage Guidelines

Pagination

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.

Quotas

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.

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