Screen a counterparty
Recall-first restricted-party candidate retrieval with explicit match evidence. Retrieval similarity is not an identity probability and is exposed separately from match confidence.
Parameters this endpoint deliberately rejects (3)
Parameters this endpoint deliberately rejects (3)
These return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.
country→ 400 COUNTRY_FILTER_UNSUPPORTED. screening/match is a name/id matcher, not a jurisdiction browser Use instead:GET /api/v2/lists/entries?country=RUS,nationality= (evidence for a person screen).region→ 400 COUNTRY_FILTER_UNSUPPORTED. screening/match is a name/id matcher, not a jurisdiction browser Use instead:GET /api/v2/lists/entries?region=Europe.continent→ 400 COUNTRY_FILTER_UNSUPPORTED. screening/match is a name/id matcher, not a jurisdiction browser Use instead:GET /api/v2/lists/entries?continent=Europe.
Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
Counterparty name. name is an alias. Also accepts: name. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Strong entity or list identifier. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Historical list-membership date. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Minimum returned match confidence. threshold is the deprecated alias. Also accepts: threshold. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
0 <= x <= 1Attach ownership-chain exposure context. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Maximum matched entities returned. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
1 <= x <= 100Nationality / citizenship of the subject as ISO-3 codes, comma-separated (IRN,IRQ). Evidence only: compared against each candidate's country_iso3 and reported per candidate as evidence.nationality (match | mismatch | unknown); it never filters retrieval and never rejects on its own, because list country fields are inconsistently populated (see the coverage warning on /api/v2/lists/entries). An unresolvable code returns 400 INVALID_COUNTRY. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Year of birth of the subject (1900 to the current year). Evidence only, compared with a ±1 tolerance because lists publish approximate and circa dates: a candidate whose recorded year contradicts it beyond that tolerance is moved to rejected_candidates with decision_evidence: birth_year_mismatch; agreement is reported as evidence.birth_year: match and raises confidence only together with an exact name; a candidate with no recorded year is unknown and remains a candidate. There is deliberately NO date-of-birth parameter: the served person field is a birth YEAR (schema 171 stores year only, never a date), so a full DOB could not be compared to anything and would only invite callers to send PII we do not hold. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
x >= 1900Response
Screen a counterparty.
Which subject types the restricted-party corpus can speak about, per source. Machine-readable because the caller has to branch on it: a person is screened only against individual_sources, and a no_match_found for a person says nothing about the institution-only lists.
The dates this endpoint can be screened AGAINST. These are our observation dates, not designation dates — an as_of before start is refused as inconclusive rather than answered.
matches = conclusive hit. inconclusive = unresolved candidate evidence, OR no screen was possible (see inconclusive_reason). out_of_scope = the subject is a natural person and the corpus is institution-only, so nothing was screened. no_match_found = screened against the covered lists and nothing was found — which is still not compliance clearance.
matches, no_match_found, inconclusive, out_of_scope What our entity registry says the subject IS, by exact normalized name — present when the registry types it unambiguously. person with an empty subject_scope.individual_sources is why a screen is out_of_scope; person with person-bearing sources means the screen ran against exactly those. Absent when the registry does not know the name or types it both ways.
person, organization Why no determination was reached. Present on screen_status=inconclusive when the cause is structural rather than evidential.
as_of_precedes_coverage, as_of_follows_coverage