> For the complete documentation index, see [llms.txt](https://support.iafcertsearch.org/verification-users-api-developer-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.iafcertsearch.org/verification-users-api-developer-guide/api-integration/verification-apis/match-companies.md).

# Match Companies

## Match Companies

Find up to 10 company matches by name and match rate. Result includes IAF IDs.

<mark style="color:green;">**`POST`**</mark> **`/match-companies`**

Fields that are marked with an asterisk (`*`) are mandatory.

* The API can match multiple Certified Entities from IAFCertSearch per request.
* **Company Information Requirements**:
  * At least one of the two fields, `company_name` or `company_identifiers`, must be provided.
* **Match Rate Value**:
  * The default rate value is **94** when no `match_rate` is provided.
  * If an invalid (non-numeric) `match_rate` is submitted, it falls back to **30**.
  * The minimum accepted value is **30**; values below **30** are enforced to **30**.
  * Valid rate values range from **30** to **100**.
  * Any rate value exceeding **100** will automatically be capped at **100**.
* **Match Score Bands**:

  * The match score (0–100) is grouped into bands that determine the `match_type`:

  | Band      | Score Range | match\_type       |
  | --------- | ----------- | ----------------- |
  | Very High | 94 – 100    | `exactly_matched` |
  | High      | 80 – 93     | `loosely_matched` |
  | Medium    | 60 – 79     | `loosely_matched` |
  | Low       | 30 – 59     | `loosely_matched` |
  | Very Low  | 0 – 29      | not matched       |
* **Match Type**:
  * `match_type` is derived from the match score band:
    * **`exactly_matched`** — score 94–100 (Very High band).
    * **`loosely_matched`** — score 30–93 (High, Medium, or Low band).
* **Match Factors**:
  * `match_factors` is an object of booleans indicating which submitted fields contributed to the match. Each flag is `true` when that field matched the Certified Entity:
    * `company_name` — the submitted company name matched the Certified Entity name.
    * `company_english_name` — matched the Certified Entity's English name.
    * `company_trading_name` — matched the Certified Entity's trading name.
    * `company_identifiers` — one or more submitted identifiers matched.
    * `country` — the submitted country matched.
    * `city` — the submitted city matched.
* **Match Result Count Value**:
  * The default value is set to **3**.
  * The minimum acceptable value is **1**.
  * The maximum acceptable value is **10**.
  * Any value exceeding 10 will automatically be capped at 10.
* **Credits & Persistence**:
  * No credits are consumed and no data is saved to the company's default list, regardless of `match_type`.
* **Enhanced Fuzzy Matching**:
  * `enhanced_fuzzy_matching` is an optional boolean. The default is **false**.
  * **Results**: when **true**, matches are graded by how closely the name really matches, so results land in the correct band. Weak matches that are not the same company drop to the Very Low band (not matched) instead of coming back as loose matches. Turning it off does not stop loose matching; it keeps the current scoring.
  * **Performance**: this setting trades a little speed for more precise scoring. Exact matches are unaffected, but every name that is not an exact match goes through an additional pass that scores how closely it matches the Certified Entity.<br>

    The impact depends on your request:

    * **Single requests**: barely noticeable, since only one name is scored.
    * **Bulk requests**: slower, and the more names in the batch that are not exact matches, the longer it takes, because each one is scored individually.
* **Response Value**:
  * The API will return multiple matched Certified Entity records without its Certificates.
    * If `company_identifiers` are provided, it will be included in the response.

### Headers

| Name                                                   | Type   | Description                                                                                                                                            |
| ------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Content-Type<mark style="color:red;">\*</mark>         | String | application/json                                                                                                                                       |
| x-http-authorization<mark style="color:red;">\*</mark> | String | <p>API Key received from <https://www.iafcertsearch.org/api-verification><br></p><p>Example:</p><p><code>x-http-authorization: <\<API KEY>></code></p> |

### Request Body

<table><thead><tr><th width="236.9453125">Name</th><th width="144">Type</th><th>Description</th></tr></thead><tbody><tr><td>company_country<mark style="color:red;">*</mark></td><td>String</td><td>Country/Economy of the main entity address for the Certified Entity.<br><br><a href="https://www.iban.com/country-codes"><em>Supports full country name, alpha-2 and alpha-3 format</em></a> <em>(click for more information)</em><br><br>Example:<br><strong>Australia | AU | AUS</strong></td></tr><tr><td>company_name</td><td>String</td><td>Certified Entity Name (Company Name) as detailed on the Certificate.</td></tr><tr><td>company_city</td><td>String</td><td>Optional city of the main entity address. When provided, companies in that city receive a higher match score.</td></tr><tr><td>company_identifiers</td><td>Object</td><td><p>Additional Company Fields<br></p><p>Format:<br><code>"company_identifiers": {</code></p><p><code>"vat": "string",</code></p><p><code>"tax_id": "string",</code></p><p><code>"business_registration_number": "string",</code></p><p><code>"duns_number": "string",</code></p><p><code>"company_id_number": "string"</code></p><p><code>}</code></p><p><br>Country-aware identifiers (<code>vat</code>, <code>tax_id</code>, <code>business_registration_number</code>) are matched within the specified <code>company_country</code>.<br>Global identifiers (<code>duns_number</code>, <code>company_id_number</code>) match across all countries.</p></td></tr><tr><td>match_rate</td><td>Number / String</td><td>The minimum match score threshold for a result to be returned.<br><br>Example:<br><code>100 | "100%"</code></td></tr><tr><td>match_result_count</td><td>Number / String</td><td>The maximum count of returned matched results.<br><br>Example:<br><code>10</code></td></tr><tr><td>enhanced_fuzzy_matching</td><td>Boolean</td><td><p>Optional, Default is <code>false</code>.</p><p>Improves how name matches are scored. When <code>true</code>, each candidate is scored by how closely it matches, so loose matches are ranked more precisely by real closeness and borderline names are sorted more sharply into a match or no match. Use it when you want the most precise ranking. When omitted or set to <code>false</code>, matching behaves as it does today.</p><p>Example: <strong>true | false</strong></p></td></tr></tbody></table>

### Example Payload Request

{% tabs %}
{% tab title="Required Fields Only - Company Name" %}

```json
{
  "company_name": "IAF",
  "company_country": "Australia",
  "company_city": null,
  "company_identifiers": {
    "vat": null,
    "tax_id": null,
    "business_registration_number": null,
    "duns_number": null,
    "company_id_number": null
  },
  "match_rate": 90,
  "match_result_count": 10,
  "enhanced_fuzzy_matching": false
}
```

{% endtab %}

{% tab title="Required Fields Only - Company Identifiers" %}

```json
{
  "company_name": null,
  "company_country": "Australia",
  "company_city": null,
  "company_identifiers": {
    "vat": "VAT",
    "tax_id": "TAX ID",
    "business_registration_number": "BUSINESS REGISTRATION NUMBER",
    "duns_number": "DUNS NUMBER",
    "company_id_number": "COMPANY ID NUMBER"
  },
  "match_rate": 90,
  "match_result_count": 10,
  "enhanced_fuzzy_matching": false
}
```

{% endtab %}

{% tab title="Some Fields Are Null" %}

```json
{
  "company_name": "IAF",
  "company_country": "Australia",
  "company_city": null,
  "company_identifiers": {
    "vat": null,
    "tax_id": null,
    "business_registration_number": null,
    "duns_number": "DUNS NUMBER",
    "company_id_number": "COMPANY ID NUMBER"
  },
  "match_rate": 100,
  "match_result_count": 10,
  "enhanced_fuzzy_matching": false
}
```

{% endtab %}

{% tab title="All Fields Have Values" %}

```json
{
  "company_name": "QualityTrade",
  "company_country": "Australia",
  "company_city": "Sydney",
  "company_identifiers": { // Have priority over company_name
    "vat": "VAT",
    "tax_id": "TAX ID",
    "business_registration_number": "BUSINESS REGISTRATION NUMBER",
    "duns_number": "DUNS NUMBER",
    "company_id_number": "COMPANY ID NUMBER"
  },
  "match_rate": 100,
  "match_result_count": 10,
  "enhanced_fuzzy_matching": false
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="cURL" %}

```url
curl --location --request POST '{API_URL}/match-companies' \
--header 'x-http-authorization: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "company_country": "string",
    "company_name": "string",
    "company_city": "string",
    "company_identifiers": {
        "vat": "string",
        "tax_id": "string",
        "business_registration_number": "string",
        "duns_number": "string",
        "company_id_number": "string"
    },
    "match_rate": 90,
    "match_result_count": 10,
    "enhanced_fuzzy_matching": false
}'
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "uri"
require "json"
require "net/http"

url = URI("{API_URL}/match-companies")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["x-http-authorization"] = "<API_KEY>"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "company_country": "string",
  "company_name": "string",
  "company_city": "string",
  "company_identifiers": {
    "vat": "string",
    "tax_id": "string",
    "business_registration_number": "string",
    "duns_number": "string",
    "company_id_number": "string"
  },
  "match_rate": 90,
  "match_result_count": 10,
  "enhanced_fuzzy_matching": false
})

response = http.request(request)
puts response.read_body
```

{% endtab %}

{% tab title="Python" %}

<pre class="language-python"><code class="lang-python">import http.client
<strong>import json
</strong>
conn = http.client.HTTPConnection("{API_URL}")
payload = json.dumps({
  "company_country": "string",
  "company_name": "string",
  "company_city": "string",
  "company_identifiers": {
    "vat": "string",
    "tax_id": "string",
    "business_registration_number": "string",
    "duns_number": "string",
    "company_id_number": "string"
  },
  "match_rate": 90,
  "match_result_count": 10,
  "enhanced_fuzzy_matching": false
})
headers = {
  'x-http-authorization': '&#x3C;API_KEY>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/match-companies", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
</code></pre>

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{API_URL}/match-companies',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "company_country": "string",
    "company_name": "string",
    "company_city": "string",
    "company_identifiers": {
        "vat": "string",
        "tax_id": "string",
        "business_registration_number": "string",
        "duns_number": "string",
        "company_id_number": "string"
    },
    "match_rate": 90,
    "match_result_count": 10,
    "enhanced_fuzzy_matching": false
}',
  CURLOPT_HTTPHEADER => array(
    'x-http-authorization: <API_KEY>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}

{% tab title="Java" %}

```java
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"company_country\": \"string\",\n    \"company_name\": \"string\",\n    \"company_city\": \"string\",\n    \"company_identifiers\": {\n        \"vat\": \"string\",\n        \"tax_id\": \"string\",\n        \"business_registration_number\": \"string\",\n        \"duns_number\": \"string\",\n        \"company_id_number\": \"string\"\n    },\n    \"match_rate\": 90,\n    \"match_result_count\": 10,\n    \"enhanced_fuzzy_matching\": false\n}");
Request request = new Request.Builder()
  .url("{API_URL}/match-companies")
  .method("POST", body)
  .addHeader("x-http-authorization", "<API_KEY>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const axios = require('axios');
let data = JSON.stringify({
  "company_country": "string",
  "company_name": "string",
  "company_city": "string",
  "company_identifiers": {
    "vat": "string",
    "tax_id": "string",
    "business_registration_number": "string",
    "duns_number": "string",
    "company_id_number": "string"
  },
  "match_rate": 90,
  "match_result_count": 10,
  "enhanced_fuzzy_matching": false
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{API_URL}/match-companies',
  headers: { 
    'x-http-authorization': '<API_KEY>', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "{API_URL}/match-companies"
  method := "POST"

  payload := strings.NewReader(`{
    "company_country": "string",
    "company_name": "string",
    "company_city": "string",
    "company_identifiers": {
        "vat": "string",
        "tax_id": "string",
        "business_registration_number": "string",
        "duns_number": "string",
        "company_id_number": "string"
    },
    "match_rate": 90,
    "match_result_count": 10,
    "enhanced_fuzzy_matching": false
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("x-http-authorization", "<API_KEY>")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
 var options = new RestClientOptions("{API_URL}")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("/match-companies", Method.Post);
request.AddHeader("x-http-authorization", "<API_KEY>");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@"    ""company_country"": ""string""," + "\n" +
@"    ""company_name"": ""string""," + "\n" +
@"    ""company_city"": ""string""," + "\n" +
@"    ""company_identifiers"": {" + "\n" +
@"        ""vat"": ""string""," + "\n" +
@"        ""tax_id"": ""string""," + "\n" +
@"        ""business_registration_number"": ""string""," + "\n" +
@"        ""duns_number"": ""string""," + "\n" +
@"        ""company_id_number"": ""string""" + "\n" +
@"    }," + "\n" +
@"    ""match_rate"": 90," + "\n" +
@"    ""match_result_count"": 10," + "\n" +
@"    ""enhanced_fuzzy_matching"": false" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
```

{% endtab %}
{% endtabs %}

### Responses

{% tabs %}
{% tab title="200" %}
**With Results**

```json
{
  "data": [
    {
      "ce_id": string,
      "matched_certified_entity_name": string,
      "match_status": string,
      "match_type": string,
      "match_rate": integer,
      "match_factors": {
        "company_name": boolean,
        "company_english_name": boolean,
        "company_trading_name": boolean,
        "company_identifiers": boolean,
        "country": boolean,
        "city": boolean
      },
      "certified_entity_english_name": string,
      "certified_entity_trading_name": string,
      "country": string,
      "company_identifiers": { // Only present when company_identifiers were provided in the request
        "vat": "string",
        "tax_id": "string",
        "business_registration_number": "string",
        "duns_number": "string",
        "company_id_number": "string"
      },
      "certified_entity_addresses": [
        {
          "street": string,
          "city": string,
          "state": string,
          "post_code": string,
          "full_address": string,
          "country": string
        }
      ],
    },
    ...
  ]
}
```

{% endtab %}

{% tab title="200" %}
**Some data are Confidential**

```json
{
  "data": [
    {
      "ce_id": string,
      "matched_certified_entity_name": string,
      "match_status": string,
      "match_type": string,
      "match_rate": integer,
      "match_factors": {
        "company_name": boolean,
        "company_english_name": boolean,
        "company_trading_name": boolean,
        "company_identifiers": boolean,
        "country": boolean,
        "city": boolean
      },
      "certified_entity_english_name": "Confidential",
      "certified_entity_trading_name": "Confidential",
      "country": string,
      "company_identifiers": { // Only present when company_identifiers were provided in the request
        "vat": "string",
        "tax_id": "string",
        "business_registration_number": "string",
        "duns_number": "string",
        "company_id_number": "string"
      },
      "certified_entity_addresses": [
        {
          "street": "Confidential",
          "city": "Confidential",
          "state": "Confidential",
          "post_code": "Confidential",
          "full_address": "Confidential",
          "country": string
        }
      ],
    },
    ...
  ]
}
```

{% endtab %}

{% tab title="200" %}
**No Results**

```json
{
  "data": []
}
```

{% endtab %}

{% tab title="400" %}
**Bad Request - Validation Errors**

```json
{
  "type": "string",
  "title": "Validation errors.",
  "status": 400,
  "detail": "The request body has validation errors.",
  "instance": "/match-companies",
  "code": "validation",
  "errors": [
    {
      "field": "field_name",
      "detail": "error_message"
    }
  ]
}
```

{% endtab %}

{% tab title="401" %}
**Unauthorized Access**

```json
{
  "type": "string",
  "title": "Unauthorized access.",
  "status": 401,
  "detail": "Authentication failed due to invalid credentials or missing token.",
  "instance": "/match-companies",
  "code": "unauthorized"
}
```

{% endtab %}

{% tab title="403" %}
**Forbidden Access**

```json
{
  "type": "string",
  "title": "Forbidden access.",
  "status": 403,
  "detail": "You do not have access to this resource.",
  "instance": "/match-companies",
  "code": "forbidden"
}
```

{% endtab %}

{% tab title="403" %}
**API Request Limit Reached**

```json
{
    "type": "string",
    "title": "API request limit reached.",
    "status": 403,
    "detail": "API request limit reached. To increase your API request limit, contact us at info@iafcertsearch.org.",
    "instance": "/match-companies",
    "code": "api_request_limit_reached"
}
```

{% endtab %}
{% endtabs %}