Sanctions Search API
API Response

API Response

Responses from the Search API consist of any sanction targets that are similar to the search query. The response structure supports batch requests by returning a result object for each case in your request.

If performing a batch search, you may provide an id in each case that will be returned in the response. This id can be used to map the case in the request to results in the response.

Endpoint
POST https://api.ofac-api.com/v4/search

Response Object

Attributes

sources Array of Source objects
The Search API returns information about the sanction lists that were used, including: list name, country, publish and download date.

results Array of SearchResult objects
The search result for each case. SearchResult objects contain:

  • name - The name that was searched.
  • The id of the case (if one was provided). Read more about the id field.
  • matches - An array of Sanction objects (hits) that were found.

Sanction
Represents a matching sanction target (hit) found by the Search API.
The type field indicates the type of entity and can be either person, organization, vessel or aircraft.\

Note Each type contains specific data fields, for example a person may contain a date of birth, while an organization will not.\

These type specific fields are provided under the sanction.personDetails, sanction.organizationDetails, sanction.vesselDetails and sanction.aircraftDetails items, and are displayed in the JSON sample to the right.

The categories field specifies why an entity exists in a given dataset or list, and describes the type of risk associated with the entity.
categories include sanction, debarment, pep and ban.

Sanction Object

sanction.id string
The sanction's unique ID.
Note This ID can be used to retrieve the sanction target's full data from the Entity API.

sanction.alias Array of Alias objects

Alias Object

alias.name string
alias.firstName string
alias.lastName string
alias.comment string

sanction.addresses Array of Address objects

Address Object

address.address1 string
address.address2 string
address.city string
address.stateOrProvince string
address.postalCode string
address.country string

sanction.identifications Array of Identification objects.
IDs such as passport, drivers license, military ID numbers, etc. No attempt is made to normalize id.type values among the santion lists, these values are returned exactly as they appear in the sanction data.

Identification Object

id.type string
id.idNumber string
id.country string
id.issueDate string
id.expirationDate string

sanction.cryptoWallets Array of CryptoWallet objects

CryptoWallet Object

cryptoWallet.publicKey string

sanction.additionalInformation Array of AdditionalInformation objects
Addition information contains any miscellaneous information from the sanction lists that does not fit elsewhere in the API respose. This information is in the form of label-value pairs. The label field is copied directly from the sanction list and no attempt is made to normalize this label between the various santion lists.

AdditionalInformation Object

additionalInformation.label string
additionalInformation.value string

Response JSON
{
  "error": false,
  "errorMessage": "string",
  "sources": [
    {
      "source": "string",
      "name": "string",
      "country": "string",
      "publishDate": "date",
      "downloadDate": "date-time"
    }
  ],
  "results": [
    {
      "id": "string",
      "name": "string",
      "matchCount": 1,
      "matches": [
        {
          "id": "string",
          "type": "string",
          "categories": ["string"],
          "name": "string",
          "nameFormatted": "string",
          "entityLink": "string",
          "source": "string",
          "sourceId": "string",
          "description": "string",
          "remarks": "string",
          "effectiveDate": "string",
          "expirationDate": "string",
          "lastUpdate": "string",
          "alias": [],
          "addresses": [],
          "identifications": [],
          "emailAddresses": ["string"],
          "phoneNumbers": ["string"],
          "websites": ["string"],
          "cryptoWallets": [],
          "sourceLinks": ["string"],
          "programs": ["string"],
          "additionalSanctions": ["string"],
          "additionalInformation": [],
          "personDetails": {
            "firstName": "string",
            "middleName": "string",
            "lastName": "string",
            "title": "string",
            "gender": "string",
            "birthDates": ["string"],
            "citizenships": ["string"],
            "nationalities": ["string"],
            "positions": ["string"],
            "education": ["string"]
          },
          "organizationDetails": {
            "registrationNumbers": ["string"]
          },
          "vesselDetails": {
            "vesselType": "string",
            "callSign": "string",
            "flag": "string",
            "owner": "string",
            "imoNumber": "string",
            "tonnage": "string",
            "grossTonnage": "string"
          },
          "aircraftDetails": {
            "icaoCode": "string",
            "serialNumber": "string"
          }
        }
      ]
    }
  ]
}

Error Codes and Messages

The Sanctions Screening API returns error status using both HTTP codes and errorMessages within the response body.

The error and errorMessage Properties

API responses contain an error field of type boolean and an optional errorMessage field of type string. These fields are used to report problems such as account overage and invalid search parameters and can be useful in troubleshooting problems.

đź’ˇ

Always check error and errorMessage fields
An error status and errorMessage may be returned regardless of HTTP status code, and should always be examined.
For example, the API may return a succesful search result but indicidate the account is currently over its monthly limit.

HTTP Status Codes

The API also returns success and error status via the HTTP status codes below.


CodeStatusDescription
200SuccessSuccesfully screened and returned any match results. error and errorMessage may still be present.
400Bad RequestSomething is wrong with request and it cannot be processed. This can be invalid JSON, missing Content-Type header or invalid parameters options.
401UnauthorizedInvalid or unauthorized API key.
500Internal Server ErrorA server error occured and the request was not able to be processed.
API RequestExamples