API FAQ

For an introduction to the API, start with the getting started guide. Commercial terms are covered in the commercial FAQ.

Should I use the /match or the /search API?  #

Use the /match API to build any sort of screening or cross-referencing mechanism. It supports several scoring modes that can be used to customize the ratio of false and true matches for a given use case. The /match API works particularly well if you can include multiple descriptors for an entity: a name, date of birth, nationality, or even a tax registration number.

Think of the /search/<scope> API instead as a user-facing search function, i.e. the kind of search mechanism you would use to build a Google-style, interactive search feature for a web site. You can find detailed guidance in the search API documentation.

While Elasticsearch internally generates result scores for /search results, these are not exposed via the API. The search scores would change with each re-index (i.e. every few hours), and revealing them in the API would create a false sense that this API can be used to conduct screening activities.

Why do results in the /match and /search endpoints not include relationships?  #

When you receive result entities from the /search and /match endpoints, the returned data is limited to properties of the entity itself: its name, identifiers, key dates, etc.

However, adjacent entities — such as family or business relationships, and detailed records regarding per-country sanctions designations — are not included in this "shallow" representation of each entity. In order to receive the "nested" version of each entity (which contains relationships and data from nested entities), you need to use the /entities/<result_id> endpoint of the API.

The rationale for serving shallow entities is that computing and returning the nested representation produces a significant database overhead and would make the /search and /match endpoints an order of magnitude slower.

What is the API key quota, and how can I change the quota?  #

Both trial and paid API keys have a default limit of how many requests per month a key can perform. These limits (quotas) are set to avoid abuse of the service and unexpected cost overruns. If you exceed the allocated quota in a given calendar month, requests will be rejected with a 429 HTTP status code until the beginning of the next month.

Of course, we're more than happy to increase a quota: the quota is meant as a safety stop, not a limitation. Contact our support team and indicate what limit you would like to see applied to the key (if any). You can review your quota, the number of calls used, and your remaining balance in the API console.

Making efficient use of your quota #

To make efficient use of your API quota and reduce costs, consider the following strategies:

• Caching results: Implement caching in your application to store frequently accessed data, reducing the need for repeated API calls.
• Efficient querying: Refine your search queries to retrieve only the necessary data. Use filters and parameters to limit the scope of your requests.
• Error handling: Ensure your application correctly handles errors and retries only when appropriate. Avoid loops that may cause excessive calls due to unhandled exceptions.

If your application is making more API calls than you expect, review its logic to identify loops or recursive calls that generate unnecessary requests, and use logging to track API call patterns. If you need assistance diagnosing excessive call volumes or optimizing your integration, contact our support team.

What uses of the API are metered and cost money?  #

The API bills usage per logical query, not per HTTP request:

A /match request can bundle up to 100 queries — one per entity you are screening — and each query in the batch is billed individually. Batching queries into fewer HTTP requests is a technical convenience, not a way to reduce cost: screening 1,000 entities counts as 1,000 billable queries whether you submit them one at a time or in batches of 100.

Only successful calls (HTTP response code 200) are billed. Non-successful calls, whether caused by client or server errors, are always free. You can review your API usage costs in the API console.

Can the API absorb a high request volume?  #

Our service is built to be scalable and handle high request volumes. If your use is likely to exceed 2 million queries per month, or you're planning to bring high loads in a very short time window (more than 200,000 requests per hour), reach out to us to make sure we know your traffic is legitimate.

Can I embed OpenSanctions entity profiles as an iframe?  #

Yes, OpenSanctions allows you to embed its content into other web applications using an <iframe>. For entity profiles, you can also access a minimalistic profile suitable for pop-up embeds by replacing /entities/ in the URL with /entities/preview/.

For security reasons, the embedding of pages which require authentication and allow account actions is disabled.