Reviewing screening hits

Every screening is stored: company and person screenings and searches alike. A stored screening can be fetched again, its hits reviewed, and the decisions are remembered, so the next screening of the same person shows only what is new.


Fetch a screening	`GET /screening/{screeningId}`
Full details of a hit	`GET /screening/{screeningId}/hits/{hitId}`
Record a decision	`PUT /screening/{screeningId}/hits/{hitId}/resolution`
History	`POST /screening/history`
Access	The `pep` scope on the API key, Pro+ tier

New or already seen

Each hit has isNew: true when your team has not seen this list entry for this person or company in an earlier screening. The comparison is per person or company, not per screening, so it holds across screenings: a person screened as a board member of one company and later as the owner of another is the same subject, and so is a person screened on their own.

People and companies without a record in the platform (e.g. a foreign board member registered with only a name and a birth date) are recognised by their name and birth date.

summary.newHitCount counts the new hits. On a repeat screening that is usually the only number that needs attention.

Recording a decision

Review a hit against the full entry (Get a screening hit): birth date, countries, roles and aliases. Then record what you concluded:

curl -X PUT "https://lens-api.tic.io/screening/{screeningId}/hits/{hitId}/resolution" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "resolution": "falsePositive", "comment": "Different person: born 1962, not 1975." }'

`resolution`	Meaning
`pending`	No decision yet. Every new hit starts here; setting it again undoes a decision.
`truePositive`	The subject is the person or organisation on the list.
`falsePositive`	A different person or organisation with a similar name.
`escalated`	Passed on for a decision, e.g. to a compliance officer.
`noMatch`	Not relevant for another reason.

comment is optional, at most 2,000 characters, and is kept for the audit trail with the time of the decision.

Decisions carry into later screenings

A decision follows the person or company. When the same list entry turns up for them in a later screening, the hit comes with isNew false and the latest decision, its time and comment. Decisions are the team’s: a decision recorded by one user applies to everyone’s later screenings.

When the list entry changes, the hit is reviewed again. If the list updated the entry after the decision (listEntryUpdatedAtUtc later than resolvedAtUtc), the hit is pending again, still with isNew false.

Full details for 24 hours

The summary of a hit in the screening (name, list, birth date, rating, decision) is always available. The full list entry, with aliases, roles, relationships, countries and identity numbers, is shown for 24 hours after the screening, the same time a repeated screening returns the stored one. After that, Get a screening hit returns the summary with detailsAvailable false. Nothing is deleted; to see the full entries again, screen again with refresh=true.

History

List screenings returns your screenings, newest first, optionally for one company (companyId) or person (personId). It is paged with the AG Grid request model (startRow, endRow).

curl -X POST "https://lens-api.tic.io/screening/history?companyId=3508351" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "startRow": 0, "endRow": 50 }'

Property	Type	Description
`screeningId`	guid	The screening.
`type`	string	`company`, `person` or `search`.
`companyId` / `personId`	integer	The screened company or person.
`name`	string	The screened company or person (the first subject of a search).
`screenedAtUtc`	date-time	When the screening ran.
`testMode`	boolean	A test screening.
`subjectCount` / `screenedSubjectCount`	integer	People and companies found, and screened.
`hitCount` / `newHitCount`	integer	Hits, and hits not seen before.
`pendingHitCount`	integer	Hits still without a decision.
`documentOrderGuid` / `price`		The order the screening was billed as.

Who sees what: an API key, and a team administrator, sees all of the team’s screenings. Other users see the screenings they ran themselves.

Test screenings

Test mode screenings are stored the same way, but only compared with other test screenings: a test hit never marks a live hit as seen, and decisions on test hits never carry into live screenings.