Sanctions Screening API
API Response

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 screening cases in a batch, you may provide an externalId in your request that will be returned in the response which can be used to map each 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 screened, including: list name, country, publish and download date, and current total records contained in the list.


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

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

matchSummary Array of MatchSummary obects
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.

Sanction Object

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.ids Array of ID 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 exactly as they are within the sanction list.

ID 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",
      "totalRecords": 1000,
      "publishDate": "date",
      "downloadDate": "date-time"
    }
  ],
  "results": [
    {
      "name": "string",
      "externalId": "string",
      "matchCount": 1,
      "matches": [
        {
          "score": 100,
          "matchSummary": {
            "matchFields": [
              {
                "similarity": "string",
                "fieldName": "string",
                "caseField": "string",
                "sanctionField": "string",
                "sanctionFieldNote": "string"
              }
            ]
          },
          "sanction": {
            "id": "string",
            "type": "string",
            "name": "string",
            "nameFormatted": "string",
            "entityLink": "string",
            "source": "string",
            "sourceId": "string",
            "description": "string",
            "remarks": "string",
            "effectiveDate": "string",
            "expirationDate": "string",
            "lastUpdate": "string",
            "alias": [],
            "addresses": [],
            "ids": [],
            "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.