Match Companies

Match Companies

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

POST /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 set to 100.

  • The minimum acceptable rate value is 80, regardless of whether a lower threshold is specified.

  • Valid rate values range from 80 to 100, in increments of 5.

  • Any rate value exceeding 100 will automatically be capped at 100.

• 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.

• 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*	String	application/json
x-http-authorization*	String	API Key received from https://www.iafcertsearch.org/api-verification Example: x-http-authorization: <<API KEY>>

Request Body

Name	Type	Description
company_country*	String	Country/Economy of the main entity address for the Certified Entity. Supports full country name, alpha-2 and alpha-3 format (click for more information) Example: Australia | AU | AUS
company_name	String	Certified Entity Name (Company Name) as detailed on the Certificate.
company_identifiers	Object	Additional Company Fields Format: "company_identifiers": { "vat": "string", "tax_id": "string", "business_registration_number": "string", "duns_number": "string", "company_id_number": "string" }
match_rate	Number / String	The percentage or similarity score indicating how closely the details of two companies match during the verification process. Example: 100 | "100%"
match_result_count	Number / String	The maximum count of returned matched results. Example: 10

Example Payload Request

Required Fields Only - Company Name

{
  "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
}

Required Fields Only - Company Identifiers

{
  "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
}

Some Fields Are Null

{
  "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
}

All Fields Have Values

{
  "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
}

cURL

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
}'

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

Python

import http.client
import json

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': '<API_KEY>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/match-companies", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

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;

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();

Node.js

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);
});

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))
}

C#

 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);

Responses

200: OK - With Results

{
  "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": {
        "vat": "string",
        "tax_id": "string",
        "business_registration_number": "string",
        "duns_number": "string",
        "company_id_number": "string"
      },
      "certified_entity_addresses": [
        {
          "state": string,
          "country": string
        }
      ],
    },
    ...
  ]
}

200: OK - No Results

{
  "data": []
}

400: Bad Request - Validation Errors

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

401: Unauthorized Access

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

403: Forbidden Access

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

429: Too Many Requests

{
    "type": "string",
    "title": "Too many requests.",
    "status": 429,
    "detail": "Too many requests. Please try again later.",
    "instance": "/match-companies",
    "code": "too_many_requests"
}