Skip to content
Connect API Catalog/
/
Companies
/
Search and Report Process
Last updated

Companies Endpoint Suite

The Companies Endpoint Suite provides a set of Endpoints to:

  • Authenticate
  • Search for companies
  • Retrieve detailed company reports

Below is a flow diagram guide on how to use these endpoints effectively. Including optional endpoints for identifying additional options for the user.

Flow Diagram

Authenticate
Search Criteria Endpoint
Company Search
Company Report Response Schemas
Available Company Report Languages
Company Report

Diagram summary (accessibility): Authenticate first, retrieve search criteria, run company search, optionally review report response schemas and available report languages, then request the company report.

1. Authenticate

Before using any of the endpoints, you need to authenticate. This ensures that you have the necessary permissions to access the data.

Example Request

POST /authenticate

2. Search Criteria Endpoint

The Search Criteria endpoint allows you to retrieve parameters that you can use to search for a company in the selected country. This is the first step in narrowing down your search.

Searching for more than one country in the query, will return the common parameters across the countries queried.

Searching on one country, will get all available parameters for that one country.

Example Request

GET companies/searchCriteria?countries=us

Example Response

These examples are only a snippet of the full responses, it is to demonstrate that a single response will generally respond with a higher number of available properties. Single Country Search

{
"countries": [
        "US"
    ],
    "languages": [
        "EN"
    ],
    "criteriaSets": [
        {
            "id": {
                "validationRegExp": "(X)-US.+",
                "required": true
            }
        },
        {
            "regNo": {
                "required": true
            }
        },
        {
            "vatNo": {
                "required": true
            }
        },
        {
            "searchMode": {
                "allowedValues": [
                    "Default",
                    "IncludeCoefficient",
                    "IncludeThinRecords",
                    "IncludeCoefficient_IncludeThinRecords"
                ],
                "required": false
            },
            "safeNo": {
                "validationRegExp": "US.+",
                "required": true
            }
        },
        {
            "safeNo": {
                "validationRegExp": "US.+",
                "required": true
            }
        },
        {
            "website": {
                "required": false
            },
            "address": {
                "postCode": {
                    "required": false
                },
                "province": {
                    "required": false
                },
            },

        }
}

Multiple Country Search

{
    "countries": [
        "GB",
        "US",
        "DE",
        "SE",
        "NO",
        "JP"
    ],
    "languages": [
        "EN"
    ],
    "criteriaSets": [
        {
            "id": {
                "required": true
            }
        },
        {
            "safeNo": {
                "required": true
            }
        },
        {
            "regNo": {
                "required": true
            }
        },
        {
            "address": {
                "city": {
                    "required": false
                },
                "postCode": {
                    "required": false
                }
            },
            "name": {
                "required": false
            },
            "phoneNo": {
                "required": false
            },
            "status": {
                "allowedValues": [
                    "Active",
                    "NonActive"
                ],
                "required": false
            }
        }
    ]
}

Using the parameters obtained from the Search Criteria endpoint, you can now search for the required company.

Example Request

GET /companies?country=US&name=ExampleCompany

Example Response

{
    "companies": [
            {
                "id": "GB-0-12297233",
                "country": "GB",
                "regNo": "12297233",
                "safeNo": "UK17866117",
                "name": "CREDITSAFE SERVICES LIMITED",
                "address": {
                    "simpleValue": "CASPIAN POINT ONE PIERHEAD STREET, CARDIFF, SOUTH GLAMORGAN, CF10 4PH",
                    "street": "PIERHEAD STREET",
                    "city": "CARDIFF",
                    "postCode": "CF10 4PH"
                },
            }
    ]
}

4. Company Report Response Schemas

This endpoint allows you to request the response schema for a report for a given country. It provides a full detailed breakdown on the property structure of the report.

Example Request

GET /companies/US?section=CompanyReportResponse

Example Response

{
  "schema": {
    "companyName": "string",
    "registrationNumber": "string",
    "address": "object",
    "financials": "object"
  }
}

5. Available Company Report Languages

This endpoint allows you to clarify what languages a company report will be available, as per selected country.

Example Request

GET /access/countries/{countryCode}/reportLanguages
GET /access/countries/BR/reportLanguages

Example Response

{
    "reportLanguages": [
        "PT"
    ],
    "correlationId": "e90e0934-06d9-4cf8-94a5-8e1fa568bd02"
}

6. Company Report

Using the company ID obtained from the Company Search endpoint, you can now request a detailed company report.

Example Request

GET /companies/{connectId}
GET /companies/12345

Example Response

{
  "companyName": "ExampleCompany",
  "registrationNumber": "12345",
  "address": {
    "street": "123 Main St",
    "city": "ExampleCity",
    "country": "US"
  },
  "financials": {
    "revenue": "1000000",
    "profit": "100000"
  }
}
Previous page
Next page