# 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


```mermaid
graph TD
    A(Authenticate) --> B(Search Criteria Endpoint)
    B --> C(Company Search)
    C --> D(Company Report Response Schemas)
    C --> E(Available Company Report Languages)
    D --> F
    C --> F(Company Report)
    E --> F
```

> *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


```http
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


```http
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**


```json
{
"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**


```json
{
    "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
            }
        }
    ]
}
```

## 3. Company Search

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

### Example Request


```http
GET /companies?country=US&name=ExampleCompany
```

### Example Response


```json
{
    "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


```http
GET /companies/US?section=CompanyReportResponse
```

### Example Response


```json
{
  "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


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

### Example Response


```json
{
    "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


```http
GET /companies/{connectId}
GET /companies/12345
```

### Example Response


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