> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://documentation.sayari.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://documentation.sayari.com/_mcp/server. # Screen GET https://api.sayari.com/v1/projects/{project_id}/entities/{project_entity_id}/screen Screen a project entity against watchlist records to identify potential matches. Requires the `screened_risk` role. Reference: https://documentation.sayari.com/api/api-reference/screen/screen ## Authentication - OAuth2 — send the obtained token as `Authorization: Bearer ` ## Servers - `https://api.sayari.com` (Production, default) - `https://api.internal.sayari.com` (Dev) - `https://api.uk.sayari.com` (Production_UK) ## Request ### Path parameters - `project_id` (string, required) — Project identifier. - `project_entity_id` (string, required) — Project entity identifier. ### Query parameters - `type` (string, optional) — Comma-separated list of watchlist record types to filter by. - `release_name` (string, optional) — Watchlist release name to filter by. ## Response ### 200 - `request` (ScreenResponseRequest, required) - `project_entity_attributes` (map from string to ScreenResponseAttribute, required) - `data` (list of ScreenResponseItem, required) ## Errors ### 400 Bad Request - `any` ### 401 Unauthorized - `any` ### 403 Forbidden - `status` (integer, required) - `message` (list of string, required) - `success` (boolean, required) ### 404 Not Found - `status` (integer, required) - `message` (list of string, required) - `success` (boolean, required) ### 422 Unprocessable Content - `status` (integer, required) - `message` (list of string, required) - `success` (boolean, required) ### 405 Method Not Allowed - `status` (integer, required) - `message` (list of string, required) - `success` (boolean, required) ### 406 Not Acceptable - `status` (integer, required) - `message` (list of string, required) - `success` (boolean, required) ### 429 Rate Limit Exceeded - `any` ### 500 Internal Server Error - `any` ## Types ### ScreenResponseRequest - `project_id` (string, required) - `project_entity_id` (string, required) - `org_id` (string, optional) - `type` (list of string, optional) - `release_name` (string, optional) ### ScreenResponseAttribute - `match_resolution` (boolean, required) - `values` (list of ScreenResponseAttributeValue, required) ### ScreenResponseItem - `reference_id` (string, required) - `org_id` (string, required) - `release_name` (string, required) - `name_matches` (list of ScreenResponseMatch, required) - `type` (string, optional) - `entity_match` (WatchlistEntityMatch, optional) — The watchlist entity associated with a screening match, as stored at ingestion time. All attribute fields follow the Sayari ontology: each is an array of attribute records (WatchlistAttributeValue). All known attribute fields are always present in the response — fields with no data are returned as null rather than omitted. Empty arrays may also be returned for attributes with no values. - `risk_factor_keys` (list of string, optional) — Risk factor granular key mapped from Risk Intelligence ### ScreenResponseAttributeValue - `value` (string, required) ### ScreenResponseMatch - `name` (string, required) - `similarity_score` (double, required) - `confidence_score` (double, optional) - `explanation` (string, optional) ### WatchlistEntityMatch The watchlist entity associated with a screening match, as stored at ingestion time. All attribute fields follow the Sayari ontology: each is an array of attribute records (WatchlistAttributeValue). All known attribute fields are always present in the response — fields with no data are returned as null rather than omitted. Empty arrays may also be returned for attributes with no values. - `entity_reference_id` (string, required) — Unique identifier for the watchlist entity. - `type` (string, required) — Entity type (e.g. "company", "person", "vessel"). - `additional_information` (list of map from string to any, optional) — Miscellaneous information not covered by other attribute types. Records typically contain "value" and optional "type" and "extra" fields. - `address` (list of map from string to any, optional) — Physical location descriptions parsed via the Libpostal ontology. Each record contains "value" (full address string) plus structured sub-fields: "city", "state", "country", "postcode", "road", "house", "house_number", "unit", "x", "y", "near", "level", "building", "suburb", "island", "po_box", "entrance", "staircase", "category", "world_region", "city_district", "metro_station", "country_region", "state_district", "precision_code", "date", "from_date", "to_date", "language", "translated", "transliterated", and "extra" (array of WatchlistKeyValue with source attribution). - `business_purpose` (list of map from string to any, optional) — Text or code (NAICS, NACE, ISIC, etc.) describing what the entity is legally permitted to do or produce. - `company_type` (list of map from string to any, optional) — Legal entity type in a given jurisdiction (e.g. "LLC", "Sociedad Anonima"). - `contact` (list of map from string to any, optional) — Contact information such as phone numbers, email addresses, or URLs. - `country` (list of map from string to any, optional) — Country affiliation through residence, nationality, registration, etc. - `date_of_birth` (list of map from string to any, optional) — Birth date of a person. Records typically contain a "value" field with the date string. - `finances` (list of map from string to any, optional) — Financial figures such as share capital (deprecated — use financials). - `financials` (list of map from string to any, optional) — Financial information at a point in time (e.g. revenue, assets). - `gender` (list of map from string to any, optional) — Gender of a person. - `generic` (list of map from string to any, optional) — Placeholder attribute for data that does not fit any other attribute type. - `identifier` (list of map from string to any, optional) — ID numbers that uniquely identify an entity when value and type are both considered (e.g. registration number, tax ID). - `measurement` (list of map from string to any, optional) — Numerical measurement of an entity dimension using a standard unit. - `monetary_value` (list of map from string to any, optional) — Financial value of an asset (e.g. FOB, CIF values). - `name` (list of map from string to any, optional) — Entity name records. Each record contains at minimum a "value" field with the name string. - `person_status` (list of map from string to any, optional) — Key life events for a person, usually temporal. - `position` (list of map from string to any, optional) — Title or designation associated with a relationship (e.g. "Secretary of the Board"). - `risk_intelligence` (list of WatchlistRiskIntelligenceValue, optional) — Risk or sanctions program data. Records contain structured fields (list, type, program, authority, from_date, to_date, score, reason, extra) — there is no "value" field on these records. - `risk_factors` (list of string, optional) — Risk factor umbrella values mapped from Risk Intelligence - `shares` (list of map from string to any, optional) — Shareholding information. - `status` (list of map from string to any, optional) — Status of the entity (e.g. active, dissolved). - `translated_name` (list of map from string to any, optional) — Translated or transliterated name records. - `weak_identifier` (list of map from string to any, optional) — Identifiers that are not unique on their own and require additional context to disambiguate. - `risk_event` (list of map from string to any, optional) — Risk events associated with the entity — ESG controversies, enforcement actions, adverse media, etc. Records may contain fields such as "category", "subcategory", "event_type", "title", "source_url", "credibility", "event_stage", "penalty_and_restriction", and "dismissal_and_clearance". ### WatchlistRiskIntelligenceValue A single risk intelligence record. Unlike other attribute records, this type does NOT contain a "value" field. Risk label information is in the "list" and "program" fields. - `list` (string, optional) — Name of the sanctions or risk list (e.g. "OFAC Specially Designated Nationals (SDN) List"). - `type` (string, optional) — Risk category (e.g. "sanctions", "export_controls", "pep"). - `score` (double, optional) — Risk score, if provided by the source list. - `reason` (string, optional) — Reason for designation or listing. - `program` (string, optional) — Sanctions program or sub-program name (e.g. "CUBA", "IRAN"). - `authority` (string, optional) — Issuing authority (e.g. "OFAC", "Department of the Commerce - International Trade Administration"). - `from_date` (string, optional) — Date the listing took effect (ISO 8601 date string). - `to_date` (string, optional) — Date the listing was removed, if applicable. - `date` (string, optional) — Generic date field for sources that do not distinguish from/to dates. - `extra` (list of WatchlistKeyValue, optional) — Supplemental metadata as key-value pairs (e.g. license requirements, federal register notices). ### WatchlistKeyValue Key-value pair used in the extra field of attribute records. - `key` (string, required) - `value` (string, required) ## Examples **Response** ```json { "request": { "project_id": "YVB88Y", "project_entity_id": "YVodz6" }, "project_entity_attributes": { "name": { "match_resolution": true, "values": [ { "value": "AEROCARIBBEAN AIRLINES" } ] } }, "data": [ { "reference_id": "ofac-sdn-48846", "org_id": "ofac", "release_name": "2024-01-01", "name_matches": [ { "name": "AEROCARIBBEAN AIRLINES", "similarity_score": 0.4, "confidence_score": 0.5, "explanation": "High name similarity with matching organization type" } ], "type": "company", "entity_match": { "entity_reference_id": "ofac-sdn-48846", "type": "company", "additional_information": [ { "value": "Designated pursuant to Executive Order 13224", "type": "Designation Basis", "date": null, "to_date": null, "from_date": null, "extra": null } ], "address": [ { "value": "Calle 23 No. 64, Havana, Cuba", "city": "Havana", "state": null, "country": "CU", "postcode": "10400", "road": null, "house": "Calle 23 No. 64", "house_number": null, "type": null, "unit": null, "x": null, "y": null, "near": null, "level": null, "building": null, "suburb": null, "island": null, "po_box": null, "entrance": null, "staircase": null, "category": null, "world_region": null, "city_district": null, "metro_station": null, "country_region": null, "state_district": null, "precision_code": null, "date": null, "to_date": null, "from_date": null, "language": null, "translated": null, "transliterated": null, "extra": [ { "key": "Country Field Added By", "value": "libpostal" } ] } ], "business_purpose": [ { "value": "Air transportation", "date": null, "to_date": null, "from_date": null, "extra": null } ], "company_type": [ { "value": "State-owned enterprise", "date": null, "to_date": null, "from_date": null, "extra": null } ], "contact": [ { "value": "+53 7 835-0216", "type": "phone", "date": null, "to_date": null, "from_date": null, "extra": null }, { "value": "info@aerocaribbean.cu", "type": "email", "date": null, "to_date": null, "from_date": null, "extra": null } ], "country": [ { "value": "CU", "context": "domicile", "state": null, "date": null, "to_date": null, "from_date": null, "extra": null } ], "finances": [ { "value": "1500000", "currency": "USD", "type": "share_capital", "date": null, "to_date": null, "from_date": null, "extra": null } ], "financials": [ { "value": "12000000", "currency": "USD", "type": "annual_revenue", "year": "2019", "date": null, "to_date": null, "from_date": null, "extra": null } ], "gender": null, "generic": [ { "value": "CUBA", "type": "program", "date": null, "to_date": null, "from_date": null, "extra": null } ], "identifier": [ { "value": "48846", "type": "SDN ID", "date": null, "to_date": null, "from_date": null, "extra": null }, { "value": "CU-1234567", "type": "registration_number", "date": null, "to_date": null, "from_date": null, "extra": null } ], "measurement": [ { "value": "750", "unit": "employees", "type": "headcount", "date": null, "to_date": null, "from_date": null, "extra": null } ], "monetary_value": [ { "value": "2500000", "currency": "USD", "type": "FOB", "date": null, "to_date": null, "from_date": null, "extra": null } ], "name": [ { "value": "AEROCARIBBEAN AIRLINES", "context": "primary", "date": null, "extra": null, "to_date": null, "language": null, "from_date": null, "translated": null, "transliterated": null } ], "person_status": null, "position": [ { "value": "Minister of Transportation", "type": "oversight", "date": null, "to_date": null, "from_date": null, "extra": null } ], "risk_intelligence": [ { "list": "OFAC Specially Designated Nationals (SDN) List", "type": "sanctioned", "score": null, "reason": null, "program": "CUBA", "authority": "OFAC", "from_date": "2002-01-01", "to_date": null, "date": null, "extra": [ { "key": "License Policy", "value": "Presumption of denial." } ] } ], "risk_factors": [ "sanctioned" ], "shares": [ { "value": "100", "unit": "%", "type": "government_owned", "date": null, "to_date": null, "from_date": null, "extra": null } ], "status": [ { "value": "active", "date": "2020-01-01", "to_date": null, "from_date": null, "extra": null } ], "translated_name": [ { "value": "Aerolíneas AeroCaribbean", "context": null, "date": null, "extra": null, "to_date": null, "language": "es", "from_date": null, "translated": null, "transliterated": null } ], "weak_identifier": [ { "value": "AEROCARIBBEAN", "type": "common_name", "date": null, "to_date": null, "from_date": null, "extra": null } ], "risk_event": [ { "category": "Law Enforcement", "subcategory": "Sanctions", "event_type": "SDN Designation", "title": "OFAC SDN Designation — CUBA Sanctions Program", "source_url": "https://sanctionssearch.ofac.treas.gov/Details.aspx?id=48846", "credibility": "Official", "event_stage": "Active", "penalty_and_restriction": "Asset freeze; prohibit US persons from transacting", "dismissal_and_clearance": null } ] } } ] } ``` **SDK Code** ```python Example 1 import requests url = "https://api.sayari.com/v1/projects/YVB88Y/entities/YVodz6/screen" querystring = {"type":"company"} headers = {"Authorization": "."} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript Example 1 const url = 'https://api.sayari.com/v1/projects/YVB88Y/entities/YVodz6/screen?type=company'; const options = {method: 'GET', headers: {Authorization: '.'}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Example 1 package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.sayari.com/v1/projects/YVB88Y/entities/YVodz6/screen?type=company" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", ".") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Example 1 require 'uri' require 'net/http' url = URI("https://api.sayari.com/v1/projects/YVB88Y/entities/YVodz6/screen?type=company") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = '.' response = http.request(request) puts response.read_body ``` ```java Example 1 import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.sayari.com/v1/projects/YVB88Y/entities/YVodz6/screen?type=company") .header("Authorization", ".") .asString(); ``` ```php Example 1 request('GET', 'https://api.sayari.com/v1/projects/YVB88Y/entities/YVodz6/screen?type=company', [ 'headers' => [ 'Authorization' => '.', ], ]); echo $response->getBody(); ``` ```csharp Example 1 using RestSharp; var client = new RestClient("https://api.sayari.com/v1/projects/YVB88Y/entities/YVodz6/screen?type=company"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "."); IRestResponse response = client.Execute(request); ``` ```swift Example 1 import Foundation let headers = ["Authorization": "."] let request = NSMutableURLRequest(url: NSURL(string: "https://api.sayari.com/v1/projects/YVB88Y/entities/YVodz6/screen?type=company")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```