# Search company

`POST https://api.foxentry.com/company/search`

This enpoint mainly serves as autocomplete but can be used to search for specific companies based on filter criteria as well. Foxentry will automatically offer you suggestions to complete the company you are writing down. Pay attention to the client section in the request body. You can specify the user's location in order to receive more relevant suggestions.

## Headers

| Header | Value |
|---|---|
| `Api-Version` | `2.1` or `2.0` |
| `Authorization` | `Bearer <your API key>` |
| `Content-Type` | `application/json` |

## Request body

### request.query

Parameters you want to validate or search for.

| Field | Type | Description |
|---|---|---|
| `type` | string | Type of search. One of: `name`, `registrationNumber`, `taxNumber`, `vatNumber`. |
| `value` | string | Searched value. |
| `filter.name` | string | Company name. |
| `filter.country` | string | Country code in format ISO-3166-1 alpha-2. |
| `filter.registrationNumber` | string | Company registration number (ID). |
| `filter.taxNumber` | string | Company national TAX number. Currently available only for SK subjects. |
| `filter.vatNumber` | string | Company VAT number. |

### request.options

Options that change how the endpoint behaves.

| Field | Type | Description |
|---|---|---|
| `dataScope` | string | Data scope of returned data. One of: `basic`, `extended`, `full`. Default: `"basic"`. |
| `dataSource` | array[string] | Array of allowed data sources, which restricts countries the module searches. Although we use the request.client object to provide most relevant results, it is generally recommended to to limit this option to only the necessary sources - especially if you don't utilize the request.client object. Default: `["CZ", "SK", "PL"]`. |
| `includeTerminatedSubjects` | boolean | Whether or not to include entities that have already ended their existence in the output. Default: `false`. |
| `zipFormat` | boolean | Whether to return locally formatted ZIP code or not. (130 00 vs 13000). Default: `false`. |
| `cityFormat` | string | This option determines the format in which the city is returned. Minimal = Praha, basic = Praha 8, extended = Praha 8 - Karlín. One of: `minimal`, `basic`, `extended`. Default: `"basic"`. |
| `countryFormat` | string | This option determines the format in which the country is returned. Supported formats: alpha2 = CZ, alpha3 = CZE, local = Česká republika, international = Czech republic, localShortened = Česko, internationalShortened = Czechia. One of: `alpha2`, `alpha3`, `local`, `localShortened`, `international`, `internationalShortened`. Default: `"alpha2"`. |
| `legalFormType` | string or null | This option filters results by the legal form type. One of: `juridical`, `physical`, `any`. Default: `"any"`. |
| `filterMode` | string | Prefer = prefer results matching the filter parameters, limit = limit to results matching the filter parameters. One of: `limit`, `prefer`. Default: `"limit"`. |
| `resultsLimit` | integer | Limits number of results returned by the endpoint. Default: `10`. |
| `filterAcceptFormat` | boolean | If true, values with different format would be accepted. (Uppercase and diacritics). Default: `true`. |
| `filterAcceptAlternatives` | boolean | If true, alternative values for filter types would be accepted. Currently used mainly for the Polish companies names. (for example name of company: ELBI-WROCŁAW SP.Z O.O. ; alternative name: ELBI-WROCŁAW SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ). Default: `true`. |
| `filterExactMatch` | boolean | If true, only exact match would be accepted. For example filter registrationID "0499" would return 0 results, since no company with the exact registration ID exists. Default: `true`. |

### request.client

Information about your user, to make results more relevant.

| Field | Type | Description |
|---|---|---|
| `ip` | string |  |
| `country` | string | Country code in ISO-3166-1 alpha-2 format. |
| `location.lat` | number | Client's latitude |
| `location.lon` | number | Client's longitude |

### Example

```json
{
  "request": {
    "query": {
      "type": "name",
      "value": "ava",
      "filter": {
        "country": "CZ"
      }
    },
    "options": {
      "dataScope": "basic",
      "resultsLimit": 10,
      "includeTerminatedSubjects": false,
      "filterMode": "limit",
      "filterAcceptFormat": true,
      "filterExactMatch": true,
      "cityFormat": "basic",
      "zipFormat": false
    },
    "client": {
      "country": "CZ",
      "location": {
        "lat": 50.0628,
        "lon": 13.9271
      }
    }
  }
}
```

## Responses

- `200` Successful response. Examples: `searchName`, `searchRegistrationNumber`, `searchTaxNumber`, `searchVatNumber`
- `400` Bad Request
- `401` Unauthorized
- `402` Payment Required
- `403` Forbidden
- `404` Not Found
- `405` Method Not Allowed
- `429` Too Many Requests
- `500` Internal Server Error
- `503` Service Unavailable