EasyOFAC API

Build enterprise-class OFAC compliance into your application with our easy to understand API.

API Documentation

Getting Started

The EasyOFAC API allows you to access the EasyOFAC from within your own software platform. Using the API endpoints provided by the API, you can integrate your own application with EasyOFAC.

This API is a REST/JSON type webservice, and is defined by a set of endpoints, each one serving a specific function. The following documents the purpose of each endpoint, what parameters are required, and what you can expect in return.

To learn more about the EasyOFAC platform itself, please refer to the EasyOFAC Overview.

Connecting

There are a number of ways you can connect to the EasyOFAC API. Most programming languages have some mechanism for making HTTP calls with GET or POST parameters. All of the EasyOFAC API endpoints live under this web address:

https://easyofac.com/api/{endpoint}

Parameters can be passed to endpoints via either GET or POST (or any combination of the two). All endpoints require an API key, which you can get simply by signing up.

If all this sounds intimidating, or you are new to the idea of REST or APIs in general, we encourage you learn a bit more about them before diving in to this documentation. There is a great tutorial for REST available at http://www.restapitutorial.com/.

API Keys

In order to connect to the EasyOFAC API, you will need an API Key. You can get one for free by signing up. Once logged into your account, look on the left for "Manage" under the "API Keys" section. You can copy your API Key from there. You can also add or remove keys, and update existing keys. Note that your API key allows you to access most of the information in your account, so you should treat it like a username/password.

https://easyofac.com/api/{endpoint}?api_key={your key here}

Within the documentation you will see a demo API key provided for example purposes. Note that this demo key only searches a fraction of the overall records available on the EasyOFAC system. If you have a key of your own, we advise using it.

Authentication

There are two ways to authenticate on the EasyOFAC API: passing an API key via the GET Query, or by using HTTP Basic Authentication.

Authenticate via GET Query

The easiest way to authenticate is via the GET query. Simply pass your API key as the api_key parameter on the GET query along with the other parameters required for your API request.

https://easyofac.com/api/{endpoint}?api_key={your key here}

HTTP Basic Authentication

The EasyOFAC API also supports the HTTP Basic Authentication scheme. As this method requires both a username and password, you will need to provide the account email address as the username, and the API key as the password.

https://{email}:{api_key}@easyofac.com/api/{endpoint}?api_key={your key here}

Your programming language likey provides a mechanism to pass a HTTP auth username/password. However, since the underlying mechanism used to perform this authentication is the Authorization HTTP header, it can be used directly as follows:

Authorization: Basic {token}

In this case, {token} is the base-64 encoded username and password, separated by a colon. In pseudo-code, the token would be calculated as:


// Generate the HTTP Authorization token
token = base64( email + ':' + api_key );

Unauthorized Requests

Note that passing an unknown or invalid API key via GET query, or omitting the api_key parameter from the GET query string without substituting HTTP Basic Authentication, will cause the EasyOFAC API to fall back to HTTP Basic Authentication scheme.

Free vs Metered

There are two types of endpoints available on the EasyOFAC API: free and metered. Free endpoints don't count towards API limits and/or quotas. Metered endpoints are logged and count towards API limits and quotas. It is important to know which type of endpoint you are accessing, as billed accounts may have overage charges once you reach monthly usage caps.

If you are testing the API, be sure to use Test Mode.

Test Mode

Any valid API key can be used in test mode simply by passing the parameter test with a value of 1 along with the other parameters required by the endpoint. This will do two things. First, the endpoint usage will not be logged and the one-per-second rate limit will be lifted. Second, and most importantly, the result set searched will only include SDN records with entity numbers ≤ 4000, which works out to be less than 2% of the database. For your testing purposes, we have provided a list of all SDN records that should be visible in test mode here: EasyOFAC SDN Test List (CSV format).

Because usage of metered endpoints counts towards your billable usage (or towards your monthly quota on free accounts), you will want to enable test mode during testing to avoid being billed for API usage.

Endpoints

Free Endpoints

quota

Check the number of remaining searches on your API Key's quota.

stats

View usage statistics for the current billing cycle.

addSearch

Search for address records matching the given search criteria.

altSearch

Search for alternate name records matching the given search criteria.

sdnSearch

Search for SDN records matching the given search criteria.

adds

Retrieve a complete list of address records given a SDN entity number.

alts

Retrieve a complete list of alternate name records given a SDN entity number.

sdn

Retrieve a single SDN record given its entity number.

addCustomer

Add a customer to be monitored

addCustomerFullName

Add a customer to be monitored, using an unparsed full name. The API will automatically parse the name as the customer is added, and return a parsed version for your records.

inspectCustomer

Inspect the specified customer, and return any potential matches found along with all related records.

updateCustomerStatus

Update a customer's status to 'safe', 'unsafe' or 'exception'. Possible use cases might be: After reviewing potential matches on a customer with a status of 'inspect', mark the customer as an 'exception' (in the case where the potential match was a false positive), or 'unsafe' (in the case where the potential match was correct). A customer marked as 'exception' or 'unsafe' may be updated to 'safe', which will automatically trigger a reverification of the record. Note that a reverification may result in the record being flagged as 'inspect', in which case you will need to review the potential matches via the inspectCustomer endpoint, or by logging in.

getCustomers

Search for customer records matching the given search criteria.

removeCustomer

Remove a customer from monitoring, typically when you no longer do business with the customer, or the customer has updated their first and/or last name in your records. Note that removing a customer will purge any historic log information for that customer, along with all other associated records.

addCompany

Add a company to be monitored

inspectCompany

Inspect the specified company, and return any potential matches found along with all related records.

updateCompanyStatus

Update a company's status to 'safe', 'unsafe' or 'exception'. Possible use cases might be: After reviewing potential matches on a company with a status of 'inspect', mark the company as an 'exception' (in the case where the potential match was a false positive), or 'unsafe' (in the case where the potential match was correct). A company marked as 'exception' or 'unsafe' may be updated to 'safe', which will automatically trigger a reverification of the record. Note that a reverification may result in the record being flagged as 'inspect', in which case you will need to review the potential matches via the inspectCompany endpoint, or by logging in.

getCompanies

Search for company records matching the given search criteria.

removeCompany

Remove a company from monitoring, typically when you no longer do business with the company, or the company has updated their name in your records. Note that removing a company will purge any historic log information for that customer, along with all other associated records.