API Response

Responses from the Screening API consist of any matches with a greater score than the minScore parameter of your request. The response structure supports batch requests by returning a result item for each case in your request.

If performing a batch screening, 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.

Each match contains an explanation within the matchSummary field.

Endpoint

POST https://api.ofac-api.com/v4/screen

Response Object

Attributes

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

results Array of Result objects
The result for each screened case. Result objects contain:

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

matchSummary Array of MatchSummary objects
Explanation of a match.
It may not be obvious why a match was returned by the Screening API, especially if you provide optional case information such as address, ID, date of birth, etc.

To help quickly identify the similarity between your screened case and a matching sanction target, the matchSummary object lists which fields triggered the match. The matchSummary can be useful in providing an explanation to front end users.

sanction
Represents a matching sanction target (hit) found by the Screening API. The type field indicates the type of target 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.address3 string
address.address4 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": [
        {
          "score": 100,
          "matchSummary": {
            "matchFields": [
              {
                "similarity": "string",
                "fieldName": "string",
                "caseField": "string",
                "sanctionField": "string",
                "sanctionFieldNote": "string"
              }
            ]
          },
          "sanction": {
            "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.

Code	Status	Description
200	Success	Succesfully screened and returned any match results. `error` and `errorMessage` may still be present.
400	Bad Request	Something is wrong with request and it cannot be processed. This can be invalid JSON, missing `Content-Type` header or invalid parameters options.
401	Unauthorized	Invalid or unauthorized API key.
500	Internal Server Error	A server error occured and the request was not able to be processed.

API Request Examples

API Response

Response Object

Error Codes and Messages

The error and errorMessage Properties

HTTP Status Codes

The `error` and `errorMessage` Properties