# 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 **90** when no `match_rate` is provided.
  * If an invalid (non-numeric) `match_rate` is submitted, it falls back to **80**.
  * The minimum accepted value is **80**; values below **80** are enforced to **80**.
  * Valid rate values range from **80** to **100**, in increments of **5**.
  * Any rate value exceeding **100** will automatically be capped at **100**.
  * The match rate only has a practical effect when the normalised company name contains **more than 2 words** (after legal suffixes such as "Ltd", "Inc", or "GmbH" are stripped). For names with 2 words or fewer, all words must match regardless of the rate set.
  * The match rate has **no effect** when only `company_identifiers` are provided — those always use exact identifier lookups.
* **Match Type**:
  * **`exactly_matched`** — the normalised base names (after stripping legal suffixes) are identical.
  * **`loosely_matched`** — the normalised base names differ (e.g. a word was swapped or suffix removal produced a different base).
* **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`.
* **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="222">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_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></td></tr><tr><td>match_rate</td><td>Number / String</td><td>The percentage or similarity score indicating how closely the details of two companies match during the verification process.<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></tbody></table>

### Example Payload Request

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

```json
{
  "company_name": "IAF",
  "company_country": "Australia",
  "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
}
```

{% endtab %}

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

```json
{
  "company_name": null,
  "company_country": "Australia",
  "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
}
```

{% endtab %}

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

```json
{
  "company_name": "IAF",
  "company_country": "Australia",
  "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
}
```

{% endtab %}

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

```json
{
  "company_name": "QualityTrade",
  "company_country": "Australia",
  "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
}
```

{% 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_identifiers": {
        "vat": "string",
        "tax_id": "string",
        "business_registration_number": "string",
        "duns_number": "string",
        "company_id_number": "string"
    },
    "match_rate": 90,
    "match_result_count": 10
}'
```

{% 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_identifiers": {
    "vat": "string",
    "tax_id": "string",
    "business_registration_number": "string",
    "duns_number": "string",
    "company_id_number": "string"
  },
  "match_rate": 90,
  "match_result_count": 10
})

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_identifiers": {
    "vat": "string",
    "tax_id": "string",
    "business_registration_number": "string",
    "duns_number": "string",
    "company_id_number": "string"
  },
  "match_rate": 90,
  "match_result_count": 10
})
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_identifiers": {
        "vat": "string",
        "tax_id": "string",
        "business_registration_number": "string",
        "duns_number": "string",
        "company_id_number": "string"
    },
    "match_rate": 90,
    "match_result_count": 10
}',
  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_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}");
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_identifiers": {
    "vat": "string",
    "tax_id": "string",
    "business_registration_number": "string",
    "duns_number": "string",
    "company_id_number": "string"
  },
  "match_rate": 90,
  "match_result_count": 10
});

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_identifiers": {
        "vat": "string",
        "tax_id": "string",
        "business_registration_number": "string",
        "duns_number": "string",
        "company_id_number": "string"
    },
    "match_rate": 90,
    "match_result_count": 10
}`)

  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_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" +
@"}";
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,
      "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,
      "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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.iafcertsearch.org/verification-users-api-developer-guide/api-integration/verification-apis/match-companies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.