Company and person screening

Screening a company for KYC means screening more than the company: also the people who run it and the people who own it. Screen a company does all of it in one call from the company’s ID, and Screen a person screens one person the same way. You do not supply names or identity numbers; they come from the registers.

Every screening is stored. Hits are marked as new or already seen, and decisions you record on hits follow the person into later screenings. See Reviewing hits.

Who is screened

A company screening always includes the company itself. Besides the company it includes these role groups, set with roles:

Positions are the current ones, the same as in representatives. To screen only some groups, list them:

curl -X POST "https://lens-api.tic.io/screening/companies/3508351" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "roles": ["board", "management", "beneficialOwner"] }'

Choosing who to screen

Plan a company screening lists everyone a screening can include, with their positions and, for beneficial owners, the extent and kind of control, and what it costs, without screening anyone. Send the subjectKey of the people and companies you want in subjects; the company itself is always screened:

curl -X POST "https://lens-api.tic.io/screening/companies/3508351" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subjects": ["P1234567", "P2345678"] }'

subjects picks from every role group, auditors included; roles narrows the groups first. A subjectKey the company no longer has (the board or the owners changed after the plan was fetched) returns 400 with code unknown_subjects: fetch the plan again.

Everyone is screened once. A chair who is also a beneficial owner is one subject with both roles, and is billed once. A person registered twice without a personal identity number, with the same name and birth date, is also one subject.

When there are no owners, beneficialOwnerStatus says why:

A company screening can include at most 250 people and companies. Above that the call returns 400 with code too_many_subjects; narrow roles or pick subjects. Limited partnerships with hundreds of limited partners can be screened without partner.

How each person is matched

Two rules of the lists shape how a person has to be screened (see How matching works):

• Every word of the name must be on the list entry. A full legal name with all given names misses an entry listed under fewer names.
• A list entry whose identity number differs from the one in the query is left out, also from name matching. A person whose personal identity number has changed is only found under the old number by a query with the old number.

So the API sends one or more queries per person, depending on what is registered:

The family name with the birth date finds an entry however many given names it lists. But it also finds entries with the same family name that have only a birth year, or no birth date at all, so a hit that did not match on the identity number (hitRating below 5) is kept only when the entry or one of its aliases shares a given name with the person. The family name searched on does not count as a given name, also when the person has it among the given names.

screenedOn on each subject says what its strongest query used: identityNumber, nameAndBirthDate or name. A subject screened on name gets more false positives; review those hits against the birth date and countries on the entry. With includeQueries=true every query is listed with its reason:

Lists: every sanctions list (including the financial supervisors’ warning lists) and PEP list; serviceScope narrows that. Adverse media is not screened.

Companies are screened on their organisation number and their name without the legal form (AB, Aktiebolag, (publ), HB, …) when at least two words remain, plus previous names and names in foreign languages.

Billing and reuse

• Each call places one order. A company screening costs your screening price times the number of people and companies screened (summary.screenedSubjectCount); those not screened are not billed. A company screened with anyone else is its own order type, priced per screened subject; the company alone is priced as a single screening. A person screening costs your screening price.
• The same screening within 24 hours is free. It returns the earlier result with reused true and places no order. The same means the same company or person, the same people, roles and queries, the same options and the same test mode. A change in the board or the owners gives new queries and therefore a new screening.
• Add refresh=true to screen again within the 24 hours. That screening is billed.
• Test mode screenings are free.

The response

The response is compact: every subject with its roles and one short line per hit. onlyWithHits=true leaves out subjects without hits (they are still counted in summary), and includeQueries=true adds the queries sent. The full list entry behind a hit is fetched with Get a screening hit. A screening of many people can have thousands of hits: includeHits=false returns the subjects with their hit counts only, and List a subject’s hits pages the hits of one subject.

{
  "screeningId": "243446ba-09c1-4ceb-b49f-d11806214a74",
  "type": "company",
  "companyId": 3508351,
  "screenedAtUtc": "2026-10-07T14:10:05",
  "testMode": false,
  "reused": false,
  "order": { "documentOrderGuid": "59e84a7a-7e13-4986-8d0b-af224bd5b8be", "orderedAtUtc": "2026-10-07T14:10:05", "price": 15.00, "currency": "SEK" },
  "summary": {
    "subjectCount": 4, "screenedSubjectCount": 3, "notScreenedCount": 1, "queryCount": 4,
    "subjectsWithHits": 1, "hitCount": 1, "newHitCount": 1, "pendingHitCount": 1,
    "hitCountByCategory": { "pep": 1 }
  },
  "beneficialOwnerStatus": "FINNS",
  "subjects": [
    {
      "subjectId": 101, "type": "company", "companyId": 3508351, "name": "Exempel AB", "identityNumber": "5560000000",
      "screenedOn": "identityNumber", "roles": [{ "group": "target" }], "queryCount": 1, "hitCount": 0, "newHitCount": 0, "hits": []
    },
    {
      "subjectId": 102, "type": "person", "personId": 2954253, "name": "Anna Maria Exempelsson",
      "screenedOn": "identityNumber",
      "roles": [
        { "group": "board", "code": "OF", "description": "ORDFÖRANDE" },
        { "group": "beneficialOwner", "code": "ART10", "description": "Personen har kontroll genom aktier, andelar, medlemskap, avtal eller bestämmelse i exempelvis bolagsordning eller stadgar.", "extentCode": "INTERVALL5", "extentDescription": "100 %" }
      ],
      "queryCount": 2, "hitCount": 1, "newHitCount": 1, "maxHitRating": 5,
      "hits": [
        {
          "hitId": 9001, "category": "pep", "name": "Anna Exempelsson", "birthDate": "1975-04-12", "isEntity": false,
          "sourceName": "PEP_Edge", "listType": "PEP", "externalId": "SE-113942", "hitRating": 5, "tier": 2,
          "matchedVia": "otherIdentityNumber", "isNew": true, "resolution": "pending", "listEntryUpdatedAtUtc": "2026-08-30T02:15:07"
        }
      ]
    },
    {
      "subjectId": 103, "type": "person", "personId": 2954254, "name": "Erik Exempelsson", "screenedOn": "identityNumber",
      "roles": [{ "group": "board", "code": "SU", "description": "STYRELSESUPPLEANT" }], "queryCount": 1, "hitCount": 0, "newHitCount": 0, "hits": []
    },
    {
      "subjectId": 104, "type": "person", "notScreenedReason": "protectedIdentity",
      "roles": [{ "group": "board", "code": "LE", "description": "STYRELSELEDAMOT" }], "queryCount": 0, "hitCount": 0, "newHitCount": 0, "hits": []
    }
  ]
}

Screening

Summary

Subject

Role

Hit

HTTP status codes