Time	Status	User Agent
Retrieving recent requests…

Time

Status

User Agent

Retrieving recent requests…

Overview

Use this method to search for companies matching specific parameters across available registry packs.

📘
Note
The set of input search parameters varies depending on the connected sources.

Required permissions

To use this method:

Your app token must have the Change applicant's personal data permission.
Your account must also have at least one of the following features enabled: KYB Auto AML & Registry or full KYB.

Both conditions are required — missing the permission, or having neither feature enabled, returns a 403 Forbidden. If neither feature is enabled for your account, contact your CSM or Sumsub support.

Request example

curl -X POST \
     'https://api.sumsub.com/resources/api/companies/63e2428232f67079df800000/search?offset=0&limit=10' \
     -H 'content-type: application/json' \
     -H 'X-App-Token: <your-app-token>' \
     -H 'X-App-Access-Sig: <your-signature>' \
     -H 'X-App-Access-Ts: <unix-timestamp>' \
     -d '{
            "companyName": "Super Company Ltd",
            "country": "USA",
            "number": "1234567890",
            "state": "NV"
          }'

Response explained

The response is a JSON file representing the list of companies with related metadata.

The following is the root-level attribute:

Field	Type	Description
`list`	Object	Includes data with `items`, `totalItems`, `pageInfo`.

`list` attributes

The following table explains the list attributes.

Field	Type	Description
`items`	Array of objects	Each item is an object representing an individual company with its details.
`totalItems`	Integer	Total number of the companies found.
`pageInfo`	Object	Applied limit and offset settings.

`items` element fields

The following table explains the items element fields representing the note details.

Field	Type	Description
`id`	String	Unique identifier (`searchItemId`) of the company in the search results. You can use this identifier later with the Get company details by search item ID method.
`country`	String	Alpha-3 code of the country where the company is legally registered (for example, `DEU`, `GBR`, `CYP`).
`state`	String	Two-letter code representing a state, province, region, jurisdiction, or similar administrative area. Applicable to the USA and Canada.
`registrationNumber`	String	Unique number that is assigned to the company when it was registered as a legal entity.
`companyName`	String	Name of the company.
`address`	String	Address in a human-readable format. For example, `Suite 502, Meridian Square Business Centre, 14 Kingsway Wharf, London NW0 0AA, United Kingdom`.

`pageInfo` attributes

The following table explains the pageInfo attributes.

Field	Type	Description
`limit`	Integer	Applied to the response limit.
`offset`	Integer	Applied to the response offset.

Response examples

If the request is successfully sent and processed, you will get a response like the following:

{
  "list": {
    "items": [
      {
        "id": "521bfb53-4484-4842-9746-8e6bc337d101:0",
        "country": "CYP",
        "state": null,
        "registrationNumber": "99999999",
        "companyName": "Demo Company With Beneficiaries Ltd",
        "address": "Suite 502, Meridian Square Business Centre, 14 Kingsway Wharf, London NW0 0AA, United Kingdom"
      },
      {
        "id": "521bfb53-4484-4842-9746-8e6bc337d101:1",
        "country": "CYP",
        "state": null,
        "registrationNumber": "88888888",
        "companyName": "Demo Company Ltd",
        "address": "Suite 502, Meridian Square Business Centre, 14 Kingsway Wharf, London NW0 0AA, United Kingdom"
      },
      {
        "id": "521bfb53-4484-4842-9746-8e6bc337d101:2",
        "country": "CYP",
        "state": null,
        "registrationNumber": "777777777",
        "companyName": "Demo Company Inactive Ltd",
        "address": "Suite 502, Meridian Square Business Centre, 14 Kingsway Wharf, London NW0 0AA, United Kingdom"
      }
    ],
    "totalItems": 3,
    "pageInfo": {
      "limit": 10,
      "offset": 0
    }
  }
}

If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:

{
  "code": 403,
  "correlationId": "82ce8a0f21e4cfa06637f837e0f95493",
  "description": "User not authorized."
}

If no companies have been found, the response returns an empty items array:

{
  "list": {
    "items": [],
    "totalItems": 0,
    "pageInfo": {
      "limit": 10,
      "offset": 0
    }
  }
}

Possible errors

Error code	Description
9501	No data source is enabled for the selected country.
9105	Company search limit was reached.
9100	Input is not supported.
9504	External service failure.

Overview

Note

Required permissions

Request example

Response explained

list attributes

items element fields

pageInfo attributes

Response examples

Possible errors

`list` attributes

`items` element fields

`pageInfo` attributes