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?  #

Every API key has a request quota, separate from your credit balance. It is a safety stop against a runaway integration, not a usage plan: requests beyond the quota are rejected with a 429 HTTP status code until the quota window resets.

The customer portal shows the quota for each key. We're more than happy to increase a quota: contact our support team and indicate what limit you would like to see applied to the key.

Making efficient use of your credits #

To use fewer credits 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.

How do API credit bundles and auto-recharge work?  #

The API is billed on prepaid credits rather than metered invoicing. It works like a prepaid SIM card: to use the service, you buy a bundle of credits up front, and every screening query consumes one credit. Larger bundles carry a lower price per query.

Credits are valid for a year from purchase and are shared across your organization's entire account, regardless of how many API keys you use. Unused credits at the end of the term are not carried over or refunded.

If you'd rather not track your balance manually, auto-recharge will automatically purchase a new bundle once your usage crosses a threshold you've defined. It's opt-in, and you'll be notified before it's ever triggered.

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

The API counts usage in credits, per logical query rather than per HTTP request:

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

Only successful calls (HTTP response code 200) count. Non-successful calls, whether caused by client or server errors, are always free.

Credits come from prepaid credit bundles and stay valid for one year from purchase. The customer portal shows your balance and purchases. Accounts that still bill monthly per query count the same operations, at the per-query rate on the account.

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. Volumes beyond the published bundles are priced individually: talk to sales.

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.