Skip to main content

Run a Company screening check using the API

  • Environment:
  • EU
  • UAE
  • US

This developer guide takes you through the steps to run a Company screening check in the Maxsight API 4.0 to get a list of a company's potential matches to sanctioned companies, politically exposed persons (PEPs), instances of adverse media, and, if available from your data provider, companies on a watchlist or internal watchlist.

The Company screening check can be run on the following task:

Choose a profile and get the profile ID

Company screening checks are run on profiles with the COMPANY entity type.

Choose a company profile to run the check on, and take note of the profile's ID number, for example, a2c4393a-e219-67a4-5ab4-2186952e9038. You'll need it to confirm it has the required fields and also to run the check later.

If you haven't created the profile yet, follow the steps to create a profile using the API. If you have access to the full Maxsight product, you can also create a profile via the portal. To get the profile ID, view the profile in the portal and copy the string of letters and numbers after /profiles/ in the URL.

Confirm the profile has the required fields for the check

To see data on the profile, make a request to the following endpoint.

Required endpoint:

GET https://{api_region}/4.0/profiles/{profile_id}

Where {api_region} represents the part of the API URL specific to your region. Use api.us.maxsight.com for the US region, api.eu.maxsight.com for the EU region, or api.ae.maxsight.com for the UAE region.

In this example, data is returned for a company profile named "Aerial Traders."

Sample response:

{
    "id": "a9676678-3393-4b21-b38f-832c44a42e77",
    "creation_date": "2025-01-21 17:02:47",
    "role": "COMPANY_CUSTOMER",
    "collected_data": {
        "entity_type": "COMPANY",
        "metadata": {
            "country_of_incorporation": "GBR",
            "name": "Aerial Traders",
            "number": "1"
        }
    },
    "events": [],
    "checks": []
}

Use the response to:

Confirm the profile has data for these required keys, which are in the collected_data object:

  • metadata.country_of_incorporation: The country in which the company is incorporated.

  • metadata.name: The legal name of the company.

  • metadata.number: The company registration number.

If the required fields do not exist on the profile or do not contain valid data, the check returns an error when you run it.

To learn how to add/update the fields in the profile's collected_data, see Update Maxsight's profile data.

If you're using the full Maxsight product, you should also take this opportunity to confirm the profile has the tasks you want to run the check on and note the task ID (tasks.id). Use the corresponding task alias (tasks.variant.alias) to confirm you're looking at the right task. If there is more than one task with the same alias (which happens when a task has more than one version), use the task with "is_expired": "false".

Run the Company screening check

To run the Company screening check, send a request to the following endpoint.

Request endpoint:

POST https://{api_region}/4.0/profiles/{profile_id}/checks

Where {api_region} represents the part of the API URL specific to your region. Use api.us.maxsight.com for the US region, api.eu.maxsight.com for the EU region, or api.ae.maxsight.com for the UAE region.

By default, the Company screening check runs asynchronously. You can also send mode as a query parameter to run a check synchronously.

Body parameters:

When you make the POST request, include the following parameters in the body.

Key

Value

Description

check_type 

*Required

string

COMPANY_SCREENING 

The type of check that's being run.

variant.alias 

*Required

string

This key is optional if variant.id is provided. We recommend sending the alias whenever possible.

Sample value:

screening_company 

The check variant alias.

variant.id 

Optional

string

This key is required if variant.alias is not provided.

Sample value:

ea70ade9-3de3-1785-203b-68044cd3ecbb 

The unique identifier for the check variant.

In the following example, we'll run the check.

Sample request body:

{
  "check_type": "COMPANY_SCREENING",
  "variant": {
    "alias": "company_screening"
  }
}

Sample response:

{
  "check_type": "COMPANY_SCREENING",
  "disable_initial_screen": false,
  "disable_monitoring": false,
  "id": "fdb2d487-9af2-4880-a71f-932c774fdbc4",
  "instructed_on": "2025-01-21 17:16:14",
  "performed_on": "2025-01-21 17:16:19",
  "providers": [],
  "state": "PENDING",
  "task_ids": [
    "a30cb706-74a7-4152-b65b-b115c666a3c7"
  ],
  "variant": {
    "id": "26726d37-2304-4f68-9ea8-b4f93fab4f3d",
    "name": "Screening"
  }
}

Take note of the check id in the response because you'll need it for the next steps to get the check result.

Because this check runs asynchronously, the check state is expected to be PENDING in the response.

Get the check result

Listen to the Check completed webhook to get a notification when the check is finished running and to learn what the result is.

This webhook sends a payload whenever results are returned from any check, including checks other than Company screening.

Payloads from this webhook have several important keys:

  • secret: Authenticate the request by ensuring this secret matches your secret.

  • id: The check ID. Use it to confirm the payload is for your check by matching it to the check ID you captured when you ran the check.

  • data.check.check_type: The type of check that was run. When the Company screening is run, the value is COMPANY_SCREENING.

  • data.check.result: The result of the check. The result is determined by analyzing the events and their flag types in this order:

    • If there is an error, the result is Error

    • If there are no events for the match, the result is Pass

    • If there are any sanction events for the match, the result is Sanction

    • If there are any PEP events for the match, the result is PEP

    • If there are any Media events for the match, the result is Media

    • If there are any other events, including Refer, Watchlist, or Internal watchlist, the result is Refer

    For example, if a check returns multiple events with different flag types, this order determines the final result. If a match has both Sanction and Adverse media flags, the result is Sanction because Sanction takes precedence over Adverse media in the check result order.

    The check decision is computed from the result:

    • Pass becomes PASS

    • Refer becomes WARN

    • PEP becomes WARN

    • Adverse media becomes WARN

    • Sanction becomes FAIL

    • Any other result becomes an ERROR

    To learn what causes these check results, see Configuring Moody's Screening .

In the following example, the Company screening check discovered at least one sanction result for the business.

Sample payload:

{
    "id": "fdb2d487-9af2-4880-a71f-932c774fdbc4",
    "event": "CHECK_COMPLETED", 
    "secret": "yourSecret",
    "timestamp": 1620300390,
    "data": {
        "check": {
            "check_type": "COMPANY_SCREENING",
            "id": "fdb2d487-9af2-4880-a71f-932c774fdbc4",
            "result": "Sanction",
            "variant": {
                "alias": "company_screening",
                "id": "26726d37-2304-4f68-9ea8-b4f93fab4f3d",
                "name": "Screening"
            }
        },
        "customer_ref": null,
        "profile_id": "a9676678-3393-4b21-b38f-832c44a42e77"
    }
}

Get more information about the check result

If you want to get more information about the check result, make a call to the following endpoint.

In the request body, include the profile ID and the check ID.

Request endpoint:

GET https://{api_region}/4.0/profiles/{profile_id}/checks/{check_id}

Where {api_region} represents the part of the API URL specific to your region. Use api.us.maxsight.com for the US region, api.eu.maxsight.com for the EU region, or api.ae.maxsight.com for the UAE region.

Sample response:

{
  "check_type": "COMPANY_SCREENING",
  "completed_on": "2025-01-21 17:16:19",
  "errors": [],
  "id": "fdb2d487-9af2-4880-a71f-932c774fdbc4",
  "instructed_on": "2025-01-21 17:16:14",
  "performed_on": "2025-01-21 17:16:19",
  "providers": [
    {
      "instructed_on": "2025-01-21 17:16:14",
      "provider_name": "Company Screening Reference",
      "variant_name": "Screening",
      "primary": false
    }
  ],
  "started_on": "2025-01-21 17:16:14",
  "state": "COMPLETE",
  "task_ids": [
    "a30cb706-74a7-4152-b65b-b115c666a3c7"
  ],
  "variant": {
    "id": "26726d37-2304-4f68-9ea8-b4f93fab4f3d",
    "name": "Screening"
  },
  "result": "Sanction",
  "decision": "FAIL",
  "input_data": {
    "entity_type": "COMPANY",
    "metadata": {
      "country_of_incorporation": "GBR",
      "name": "Aerial Traders"
    }
  },
  "output_data": {
    "entity_type": "COMPANY"
  },
  "disable_initial_screen": false,
  "disable_monitoring": false
}

Use the response to see:

  • input_data: Shows which information about the company was sent to the data provider.

  • providers: Shows which data provider was used to run the check.

See the latest matches

If you want to see the latest PEPs, sanctions, watchlist, internal watchlist, and adverse media matches a company has, make a call to the following endpoint. In the API, matches are called events.

GET https://{api_region}/4.0/profiles/{profile_id}/checks/{check_id}/snapshots/latest

Where {api_region} represents the part of the API URL specific to your region. Use api.us.maxsight.com for the US region, api.eu.maxsight.com for the EU region, or api.ae.maxsight.com for the UAE region.

In the following example, the company has five matches.

Sample response:

{
  "id": "a78528d9-09ee-4749-8ca5-c1c2f7109344",
  "result": {
    "decision": "FAIL"
  },
  "output_data": {
    "entity_type": "COMPANY",
    "screening_hits": [
      {
        "data": {
          "aliases": [
            "Aerial Traders"
          ],
          "confidence_score": 0.4,
          "countries": [
            {
              "country": "GBR",
              "type": "REGISTRATION"
            }
          ],
          "name": "Aerial Traders",
          "pep": {
            "roles": [
              {
                "name": "State owned business",
                "pep_classification_code": "GOE",
                "tenure": {
                  "tenure_type": "CURRENT"
                },
                "tier": 1
              }
            ],
            "tier": 1
          }
        },
        "flags": [
          {
            "detail_code": "PEP",
            "id": "84482d6b-3844-594f-948c-9acce99b9ea2",
            "ref": "F0001",
            "source": {
              "description": "List of PEPs",
              "name": "PEP List"
            },
            "stage": {
              "date": "2019-08-29",
              "stage_code": "ASC"
            },
            "type": "PEP"
          }
        ],
        "id": "2725b8a8-d2e1-58c2-982a-a0fabcb75e8a",
        "provider": {
          "hit_id": "12345-01",
          "label": "screening-ref",
          "name": "Screening reference integration"
        }
      },
      {
        "data": {
          "aliases": [
            "Aerial Traders Limited",
            "Aerial Traders Limited"
          ],
          "confidence_score": 0.72,
          "countries": [
            {
              "country": "BGD",
              "type": "REGISTRATION"
            },
            {
              "country": "BRA",
              "type": "REGISTRATION"
            },
            {
              "country": "CHL",
              "type": "REGISTRATION"
            },
            {
              "country": "CHN",
              "type": "REGISTRATION"
            },
            {
              "country": "GBR",
              "type": "REGISTRATION"
            },
            {
              "country": "IND",
              "type": "REGISTRATION"
            },
            {
              "country": "JOR",
              "type": "REGISTRATION"
            },
            {
              "country": "MEX",
              "type": "REGISTRATION"
            },
            {
              "country": "MUS",
              "type": "REGISTRATION"
            },
            {
              "country": "TCA",
              "type": "REGISTRATION"
            },
            {
              "country": "USA",
              "type": "REGISTRATION"
            },
            {
              "country": "ZAF",
              "type": "REGISTRATION"
            }
          ],
          "media": [
            {
              "date": "2019-08-29",
              "snippet": "https://www.theguardian.com/politics/2016/jun/24/david-cameron-resigns-after-uk-votes-to-leave-european-union",
              "title": "David Cameron resigns after UK votes to leave European union",
              "flag_ref": "F0003"
            }
          ],
          "name": "Aerial Traders Ltd",
          "sanctions": [
            {
              "flag_ref": "F0002",
              "list": {
                "name": "US Treasury Dept. OFAC Consolidated Non-SDN Sanctions List"
              },
              "name": "Aerial Traders Ltd",
              "time_periods": [
                {
                  "tenure_type": "CURRENT",
                  "start": "2019-08-29"
                }
              ]
            }
          ]
        },
        "flags": [
          {
            "detail_code": "WLT",
            "id": "f72acd2d-6c78-5050-9695-5a1c677c8689",
            "ref": "F0002",
            "source": {
              "description": "List of US Sanctioned entities",
              "name": "US Treasury Dept. OFAC Consolidated Non-SDN Sanctions List"
            },
            "stage": {
              "date": "2019-08-29",
              "stage_code": "SAN"
            },
            "type": "SANCTION"
          },
          {
            "detail_code": "MIS",
            "id": "31d93f76-d3b0-5d1e-98a5-cef005389832",
            "ref": "F0003",
            "source": {
              "description": "Media Organisation A",
              "name": "Media Org A"
            },
            "stage": {
              "date": "2019-08-29",
              "stage_code": "ALL"
            },
            "type": "ADVERSE_MEDIA"
          }
        ],
        "id": "63611177-1b0b-51d5-ba71-b2bf36f7c4e1",
        "provider": {
          "hit_id": "12345-02",
          "label": "screening-ref",
          "name": "Screening reference integration"
        }
      },
      {
        "data": {
          "aliases": [
            "Aerial Traders Limited",
            "Aerial Traders Limited"
          ],
          "confidence_score": 0.92,
          "countries": [
            {
              "country": "CAN",
              "type": "REGISTRATION"
            }
          ],
          "name": "Example"
        },
        "flags": [
          {
            "detail_code": "DPP",
            "id": "59ba92ba-7968-5949-9391-c952a7e0410a",
            "ref": "F0004",
            "source": {
              "description": "Country A's Data Regulation Authority",
              "name": "Data Regulator"
            },
            "stage": {
              "date": "2019-08-29",
              "stage_code": "FIM"
            },
            "type": "REFER"
          }
        ],
        "id": "26a7ba29-2809-5137-91d7-ac903cc729b2",
        "provider": {
          "hit_id": "12345-03",
          "label": "screening-ref",
          "name": "Screening reference integration"
        }
      },
      {
        "data": {
          "confidence_score": 0.81,
          "countries": [
            {
              "country": "GBR",
              "type": "REGISTRATION"
            }
          ],
          "name": "Aerial Charities"
        },
        "flags": [
          {
            "id": "2185ed43-34d9-567a-a08b-970939ce5688",
            "ref": "F0005",
            "source": {
              "description": "Customer's we don't do business with",
              "name": "Aerial Charities Blocklist"
            },
            "type": "INTERNAL_WATCHLIST"
          }
        ],
        "id": "196372f0-69f8-5af3-9b5b-e2cdc149e43f",
        "provider": {
          "hit_id": "12345-04",
          "label": "screening-ref",
          "name": "Screening reference integration"
        }
      },
      {
        "data": {
          "confidence_score": 0.6,
          "countries": [
            {
              "country": "GBR",
              "type": "REGISTRATION"
            }
          ],
          "name": "The Example Company"
        },
        "flags": [
          {
            "detail_code": "SEC",
            "id": "e04b8df4-d662-5083-a2a0-b41890eeabc3",
            "ref": "F0006",
            "source": {
              "description": "NGO's list of companies",
              "name": "NGO Warning List",
              "url": "https://www.ngo.com/12346"
            },
            "stage": {
              "date": "2019-08-29",
              "stage_code": "ARB"
            },
            "type": "WATCHLIST"
          }
        ],
        "id": "f6b39734-250b-5ec9-a689-c3b8dd89e9bd",
        "provider": {
          "hit_id": "12346-05",
          "label": "screening-ref",
          "name": "Screening reference integration"
        }
      }
    ]
  },
  "occurred_at": "2025-01-21T16:34:03Z",
  "errors": [],
  "warnings": [],
  "external_resources": []
}

The information in the data object shows the match information returned by the data provider, including company name, country of incorporation, sanctions data, media references, and alert score, called confidence score in the API. This information should help you make your decision about whether the match is a true match to the company or whether it should be ignored.

The response contains the events for the profile, not just the latest results from your check.

Each of the flags objects in the response corresponds to a screening event for the match.

The flags type could be any of the following event categories:

  • PEP: The match is a politically exposed person (PEP).

  • SANCTION: The match is a sanctioned company.

  • ADVERSE_MEDIA: There is an instance of adverse media about the company.

  • WATCHLIST: There is a match from a government or other official watchlist.

  • INTERNAL_WATCHLIST: There is a match from the client's own watchlist.

  • REFER: The match does not fall into any of these categories. For example, the match has a criminal record.

Each of the flags objects may include the following additional details about the event:

  • detail_code: A three-letter event code to further define the event under the event category.

  • stage_code: A three-letter stage code to indicate the event’s current phase.

  • stage date: The date the event changed to the current stage.

For PEPs, additional information can be found within data.pep, including roles with their corresponding pep_classification_code, tenure details, and tier information.

Your data provider may group adverse media matches with refer matches. For more information, see Maxsight's data providers.

The data provider returns potential matches, and it's up to you to decide if these are true matches to the profile or if they should be ignored.

Monitored screening

Some data providers offer ongoing monitoring for new matches that could be imported to the check results. This means that after the check has been run the first time, the profile is monitored for any new matches that could be imported to the check results.

To find out how to enable ongoing monitoring in the Policy Builder, see the configuration options for screening checks.

Additional information

The automated processes that can be used to complete or assist in passing tasks.

A politically exposed person is someone who is at a higher risk of bribery or corruption because they may hold a public or high-profile position. This term may also apply to someone affiliated with a high-profile person. Regulated industries must identify PEPs when onboarding.

The service used to provide data for checks, for example, GBG ID3global, Companies House, or Onfido.

The due diligence measures that must be taken to onboard a profile successfully. Tasks are displayed on the profile’s product application.

The alert score represents the confidence level of an unresolved sanctions match from 0.00 to 1.00. A score closer to 1 signals that it's more likely to be a confirmed match.