> ## Documentation Index > Fetch the complete documentation index at: https://docs.tic.io/llms.txt > Use this file to discover all available pages before exploring further. # Screening results > The data model of a LENS API screening result - subjects, hits, roles, relationships, hit ratings, warnings and errors, with reference values for role types, legal forms and operational status. A screening response has one entry per subject, and each entry carries the list entries that matched it. This page describes every property so hits can be interpreted correctly. Property names are camelCase and properties with a `null` value are omitted. ## Top level | Property | Type | Description | | ---------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------- | | `requestedAtUtc` | date-time | When the screening was performed. | | `source` | string | Fixed identifier of the list data source. | | `testMode` | boolean | `true` when the screening ran against the test environment. See [Test mode](/api-lens/screening/test-mode). | | `order` | Order | The order this screening was placed as. | | `summary` | Summary | Counts and the lists that were actually screened. | | `results` | array of SubjectResult | One entry per subject, in the order submitted. | | `warnings` | array of string | Warnings from the list provider, if any. Absent when there are none. | | `errors` | array of string | Errors from the list provider for individual subjects, if any. Absent when there are none. | ### Order | Property | Type | Description | | ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- | | `documentOrderGuid` | guid | Use this to look the screening up again through the [orders API](/api-lens/orders/get-metadata-for-a-single-document-order). | | `orderedAtUtc` | date-time | When the order was placed. | | `price` | number | Price of the screening according to your agreement. `0` in test mode. | | `currency` | string | Always `SEK`. | ### Summary | Property | Type | Description | | -------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `subjectCount` | integer | Number of subjects in the request. | | `individualHitCount` | integer | Number of person entries returned across all subjects. | | `entityHitCount` | integer | Number of organisation entries returned across all subjects. | | `totalHitCount` | integer | `individualHitCount` plus `entityHitCount`. | | `servicesQueried` | array of string | The lists that were screened against. Compare this with what you expect; a misspelled `serviceScope` or a list missing from your account shows up here. | ### SubjectResult | Property | Type | Description | | ---------------- | ------------ | ------------------------------------------------------- | | `reference` | string | The `reference` you supplied for the subject. | | `name` | string | The `name` you supplied. | | `identityNumber` | string | The `identityNumber` you supplied. | | `hitCount` | integer | Number of hits for this subject. | | `hits` | array of Hit | The matching list entries, strongest `hitRating` first. | ## Hit One list entry that matched a subject. A person entry and an organisation entry share the same shape; properties that only apply to one of them are marked. | Property | Type | Description | | ---------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | string | `individual` for a person, `entity` for an organisation. | | `name` | string | The name of the list entry. | | `identityNumber` | string | Personnummer of a person or organisationsnummer of an organisation, when the list holds one. Always absent when `isProtectedIdentity` is true. | | `birthDate` | string | Person only. `yyyy-MM-dd`, `yyyy-MM` or `yyyy`. If the list reports more than one birth date this is a comma-separated list, for example `1957-01-01, 1956-12-31`. If the source only has an approximate year, such as "circa 1966", the list holds every year in a span of plus or minus three years. | | `hitRating` | integer | What the entry matched on, 1 to 5. See [Hit rating](/api-lens/screening/introduction#hit-rating). | | `hitRatingDescription` | string | The hit rating in words, in Swedish. | | `nameMatchScore` | number | Name similarity between 0 and 1. Only present when `minimumNameMatchScore` was set. | | `listType` | string | The group the list belongs to: `SANCTION`, `PEP` or `INFO`. | | `listItemDataType` | string | `Individual` or `Entity`, as reported by the list. | | `sourceName` | string | The list that produced the hit, for example `EU_GLOBAL`. See [Lists](/api-lens/screening/lists). | | `externalId` | string | The list's own identifier for the entry. Stable across screenings and useful for de-duplicating hits over time. | | `lastUpdatedUtc` | date-time | When the entry was last updated on the list. | | `tier` | integer | Person only. PEP seniority tier where 1 is the most senior. Only populated by the global PEP list. | | `isProtectedIdentity` | boolean | Person only. The person has a protected identity. The identity number is then never returned. | | `isMale` | boolean | Person only. Absent when the sex is not known. | | `title` | string | Person only. Title of the person. | | `comment` | string | Free-text comment from the list, when there is one. | | `legalForm` | string | Organisation only. See [Legal forms](#legal-forms). | | `operationalStatus` | string | Organisation only. See [Operational status](#operational-status). | | `countries` | array of string | Every country registered to the entry, as ISO 3166-1 alpha-3 codes. Includes citizenship, residence, jurisdiction and registration countries, and countries taken from roles and addresses. | | `citizenships` | array of string | Person only. The subset of `countries` registered as citizenships. | | `aliases` | array of string | Every name the entry is known by. For organisations this is usually just the name. | | `externalUrls` | array of string | Links to source documents, when the list provides them. | | `roles` | array of Role | Person only. Political or public roles. This is what makes a person a PEP. | | `engagements` | array of Engagement | Reserved for company engagements such as board positions and ownership. Not populated by the lists today. | | `relationships` | array of Relationship | Family members and close associates, mainly on PEP entries. | ### Role A public or political function held by a person. Present on PEP entries. | Property | Type | Description | | --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ | | `roleType` | string | Category of the role. See [Role types](#role-types). | | `roleTypeDescription` | string | The role type in words, in Swedish. | | `title` | string | Title of the role, for example the position held. | | `organization` | string | The organisation the role belongs to, when known. | | `countryCode` | string | ISO 3166-1 alpha-3 country the role applies to. Usually absent, since the relevant country is on the entry itself. | | `from` | string | Date the role became active, as `yyyyMMdd`. | | `to` | string | Date the role ended, as `yyyyMMdd`. Absent while the role is active. | | `comment` | string | Description of the role. | ### Relationship A connection between the list entry and another person or organisation. | Property | Type | Description | | ------------------ | ------ | ---------------------------------------------------------------------------------------------------- | | `name` | string | Name of the related person or organisation. | | `relationshipType` | string | `Child`, `ChildsSpouse`, `CloseAssociate`, `FamilyMember`, `Parent`, `Sibling`, `Spouse` or `Other`. | | `title` | string | The nature of the connection. | | `comment` | string | Description of the relationship. | ### Engagement Reserved for a role or ownership in a company. The lists do not populate this data today, so the array is empty or absent. | Property | Type | Description | | ---------------- | --------- | ------------------------------------------------------ | | `engagementType` | string | See [Engagement types](#engagement-types). | | `name` | string | Name of the engagement holder. | | `corporateId` | string | Organisation number of the company. | | `ownershipStake` | number | Ownership share in percent, for ownership engagements. | | `from` | date-time | Date the engagement was registered. | | `to` | date-time | Date the engagement ended, if it is no longer active. | ## Example response Two subjects were screened. The first produced one PEP hit, the second produced nothing. ```json theme={null} { "requestedAtUtc": "2026-09-03T09:14:22.318Z", "testMode": false, "order": { "documentOrderGuid": "3f1c9b2e-7d44-4a1b-9c0e-2b6f0a8d5e71", "orderedAtUtc": "2026-09-03T09:14:22.301Z", "price": 5.00, "currency": "SEK" }, "summary": { "subjectCount": 2, "individualHitCount": 1, "entityHitCount": 0, "totalHitCount": 1, "servicesQueried": ["EU_GLOBAL", "UN_CONSOLIDATED", "OFAC", "PEP_Edge"] }, "results": [ { "reference": "cust-1001", "name": "Anna Exempelsson", "hitCount": 1, "hits": [ { "type": "individual", "name": "Anna Exempelsson", "birthDate": "1975-04-12", "hitRating": 4, "hitRatingDescription": "Träff på namn och födelseår eller födelsedatum", "listType": "PEP", "listItemDataType": "Individual", "sourceName": "PEP_Edge", "externalId": "SE-113942", "lastUpdatedUtc": "2026-08-30T02:15:07", "isMale": false, "countries": ["SWE"], "citizenships": ["SWE"], "aliases": ["Anna Exempelsson", "Anna Maria Exempelsson"], "roles": [ { "roleType": "NationalLegislature", "roleTypeDescription": "Nationalförsamling", "title": "Riksdagsledamot", "organization": "Sveriges riksdag", "from": "20220926" } ], "relationships": [ { "name": "Karl Exempelsson", "relationshipType": "Spouse" } ] } ] }, { "reference": "cust-1002", "identityNumber": "5560000000", "hitCount": 0, "hits": [] } ] } ``` ## Warnings and errors A `200 OK` response can still carry warnings and errors from the list provider. Both are arrays of strings. Each message starts with the subject's `reference` (or its name or identity number if no reference was given) so it can be tied back to a subject. * **Warning** - the subject was screened, but part of its data was ignored. An invalid country code such as `SWD` produces a warning and the code is disregarded. * **Error** - the subject was not screened. The other subjects in the call were. Always check `errors` before treating a subject with zero hits as cleared. ### HTTP status codes | Status | Meaning | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `200 OK` | The screening ran. Check `warnings` and `errors`. | | `400 Bad Request` | The request failed validation. The `code` property of the problem document is `no_subjects`, `too_many_subjects` or `subject_not_identifiable`. | | `401 Unauthorized` | Missing or invalid API key. | | `403 Forbidden` | The API key's plan does not include screening. | | `429 Too Many Requests` | Rate limit exceeded. See [Rate limits](/api-lens/rate-limits). | ## Reference values ### Role types Values of `roleType` on a Role. `roleTypeDescription` carries the Swedish wording. | `roleType` | Description | | --------------------- | ----------------------------------- | | `Government` | Government or ministry | | `NationalLegislature` | National parliament | | `CivilServant` | Senior civil servant | | `EmbassyAndConsular` | Diplomatic or consular post | | `ArmedForces` | Armed forces | | `Judiciary` | Courts and judiciary | | `StateCorporation` | State-owned company | | `StateAgency` | State agency | | `Political` | Political office | | `PoliticalParty` | Political party | | `Organization` | International or other organisation | | `Other` | Other | ### Legal forms Values of `legalForm` on an organisation hit. `LimitedCompany`, `PrivateBusinessGovCtrl`, `ForeignCompany`, `Bank`, `SoleProprietorship`, `GeneralPartnership`, `Society`, `Foundation`, `HousingCompany`, `StateCountyCompany`, `ReligiousOrganization`, `InsuranceCompany`, `Collaborations` ### Operational status Values of `operationalStatus` on an organisation hit. `Active`, `InactiveSleeping`, `UnderLiquidation`, `Liquidated`, `UnderBankruptcy`, `Bankrupt`, `Dissolved`, `Merged`, `Unregistered`, `Unknown`, `Dissolving`, `DissolvingByForce`, `DissolvedByForce`, `UnderReconstruction`, `CompanyDataOutOfDate` ### Engagement types Values of `engagementType` on an Engagement, for when the lists start populating engagements. `Accountant`, `AssistantStatistician`, `Associate`, `Bearer`, `BeneficialOwner`, `BoardMember`, `CEO`, `Chairman`, `Commissioner`, `CompanyStructureOwner`, `Deputy`, `DeputyAccountant`, `DeputyBoardMember`, `DeputyCEO`, `DeputyChairman`, `DeputyCommissioner`, `DeputyLaymanAccountant`, `DeputyLiquidator`, `EmployeeRepresentative`, `ExternalCEO`, `ExternalCompanySignatory`, `ExternalDeputyCEO`, `GeneralPartner`, `InsuranceRepresentative`, `KeyPerson`, `LaymanAccountant`, `LiableAccountant`, `LimitedPartner`, `Liquidator`, `Manager`, `ManagingClerk`, `NotificationRecipient`, `NotKnown`, `Owner`, `Procurator` ### Country types The `countries` array on a hit merges every country registered to the entry. The underlying registrations are typed as `Citizenship`, `Jurisdiction`, `Registration`, `Residential` or `Other`. Only the `Citizenship` type is broken out separately, as `citizenships`. ## Data not returned The list entries hold more data than the API returns today. The following is available on the underlying entries but not exposed: postal addresses, additional identity documents such as passport numbers, images, the original list an entry was consolidated from, adverse media evidence records, and for organisations the registered owners, representatives, beneficial owners, industry codes, foundation date and signatory rules. Contact [support](mailto:support@tic.io) if your use case needs any of it.