Bulk Retrieve Companies & Certificates

Find multiple companies and certificates by name and match rate.

POST /bulk-companies

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

The API accepts multiple Company Information and can match multiple Certified Entities from IAFCertSearch per request.
Companies:
- The companies must be provided.
- The maximum number of company data that this endpoint accepts is 100.
- Companies Information Requirements
  - At least one of the two fields, company_name or company_identifiers, must be provided.
- Companies that fail validation or produce no match are silently skipped — the bulk operation continues and omits those entries from the response.
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). Credits are consumed and the verified data is saved to the company's default list.
  - loosely_matched — score 30–93 (High, Medium, or Low band). The result is returned for review but is not saved to the default list and does not consume credits.
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.
Response Value:
- The API will return a list of matched Certified Entities with its Certificates.
  - You may use the companies_request_index field in the response to correlate which item from the companies request data array the Certified Entity was matched with. The first element of the companies request data array starts with the index 0. (i.e., The corresponding matched record will have a value of companies_request_index: 0 )

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

companies

Array of Objects

Array of companies to be matched The maximum number of company data that this endpoint accepts is 100

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

companies.*.company_name

String

Certified Entity Name (Company Name) as detailed on the Certificate.

companies.*.company_city

String

Optional city of the main entity address. When provided, companies in that city receive a higher match score.

companies.*.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"

}

Country-aware identifiers (vat, tax_id, business_registration_number) are matched within the specified company_country. Global identifiers (duns_number, company_id_number) match across all countries.

match_rate

Number / String

The minimum match score threshold for a result to be returned. Example: 100 | "100%"

Example Payload Request

{
    "companies": [
        {
          "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
}

{
    "companies": [
        {
          "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
}

{
    "companies": [
        {
          "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
}

{
    "companies": [
        {
          "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
}

curl --location --globoff --request POST '{API_URL}/bulk-companies' \
--header 'x-http-authorization: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "companies": [
        {
          "company_name": "string",
          "company_country": "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
}'

require "uri"
require "json"
require "net/http"

url = URI("{API_URL}/bulk-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({
  "companies": [
    {
      "company_name": "string",
      "company_country": "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
})

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

import http.client
import json

conn = http.client.HTTPSConnection("{API_URL}")
payload = json.dumps({
  "companies": [
    {
      "company_name": "string",
      "company_country": "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
})
headers = {
  'x-http-authorization': '{API_KEY}',
  'Content-Type': 'application/json'
}
conn.request("POST", "/bulk-companies", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{API_URL}/bulk-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 =>'{
    "companies": [
        {
          "company_name": "string",
          "company_country": "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
}',
  CURLOPT_HTTPHEADER => array(
    'x-http-authorization: {API_KEY}',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"companies\": [\n        {\n          \"company_name\": \"string\",\n          \"company_country\": \"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        }\n    ],\n    \"match_rate\": 90\n}");
Request request = new Request.Builder()
  .url("{API_URL}/bulk-companies")
  .method("POST", body)
  .addHeader("x-http-authorization", "{API_KEY}")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');
let data = JSON.stringify({
  "companies": [
    {
      "company_name": "string",
      "company_country": "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
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{API_URL}/bulk-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);
});

package main

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

func main() {

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

  payload := strings.NewReader(`{
    "companies": [
        {
          "company_name": "string",
          "company_country": "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
}`)

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

var options = new RestClientOptions("{API_URL}/bulk-companies")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("x-http-authorization", "{API_KEY}");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@"    ""companies"": [" + "\n" +
@"        {" + "\n" +
@"          ""company_name"": ""string""," + "\n" +
@"          ""company_country"": ""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" +
@"        }" + "\n" +
@"    ]," + "\n" +
@"    ""match_rate"": 90" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);

Responses

Request Successful

{
  "data": [
    {
        "companies_request_index": integer,
        "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,
        "certified_entity_addresses": [
          {
            "street": string,
            "city": string,
            "state": string,
            "post_code": string,
            "full_address": string,
            "country": string
          }
        ],
        "certificates": [
          {
            "cert_id": string,
            "accreditation_bodies_name": string,
            "certification_bodies_name": string,
            "certification_number": string,
            "certification_status": string,
            "certification_scope": string,
            "certification_standards_scheme": [
              {
                "standard_name": string,
                "scheme_name": string,
                "is_accredited_mla": boolean
              }
            ],
            "certification_main_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_additional_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_sectors": [
              {
                "sector_name": string,
                "sector_code": string
              }
            ],
            "updated_at": integer
          }
        ]
      }
  ]
}

Request Successful with Standards Group

{
  "data": [
    {
        "companies_request_index": integer,
        "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,
        "certified_entity_addresses": [
          {
            "street": string,
            "city": string,
            "state": string,
            "post_code": string,
            "full_address": string,
            "country": string
          }
        ],
        "certificates": [
          {
            "cert_id": string,
            "accreditation_bodies_name": string,
            "certification_bodies_name": string,
            "certification_number": string,
            "certification_status": string,
            "certification_scope": string,
            "certification_standards_scheme": [
              {
                "standard_name": string,
                "scheme_name": string,
                "is_accredited_mla": boolean,
                "standard_group": string | null
              }
            ],
            "certification_main_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_additional_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_sectors": [
              {
                "sector_name": string,
                "sector_code": string
              }
            ],
            "updated_at": integer
          }
        ]
      }
  ]
}

Request Successful with Certification Issuance Dates

{
  "data": [
    {
        "companies_request_index": integer,
        "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,
        "certified_entity_addresses": [
          {
            "street": string,
            "city": string,
            "state": string,
            "post_code": string,
            "full_address": string,
            "country": string
          }
        ],
        "certificates": [
          {
            "cert_id": string,
            "accreditation_bodies_name": string,
            "certification_bodies_name": string,
            "certification_number": string,
            "certification_status": string,
            "certification_scope": string,
            "certification_issuance_dates": {
              "certification_original_issued_date": string,
              "certification_issued_date": string,
              "certification_expiry_date": string
            },
            "certification_standards_scheme": [
              {
                "standard_name": string,
                "scheme_name": string,
                "is_accredited_mla": boolean
              }
            ],
            "certification_main_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_additional_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_sectors": [
              {
                "sector_name": string,
                "sector_code": string
              }
            ],
            "updated_at": integer
          }
        ]
      }
  ]
}

Request Successful with Standards Group and Certification Issuance Dates

{
  "data": [
    {
        "companies_request_index": integer,
        "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,
        "certified_entity_addresses": [
          {
            "street": string,
            "city": string,
            "state": string,
            "post_code": string,
            "full_address": string,
            "country": string
          }
        ],
        "certificates": [
          {
            "cert_id": string,
            "accreditation_bodies_name": string,
            "certification_bodies_name": string,
            "certification_number": string,
            "certification_status": string,
            "certification_scope": string,
            "certification_issuance_dates": {
              "certification_original_issued_date": string,
              "certification_issued_date": string,
              "certification_expiry_date": string
            },
            "certification_standards_scheme": [
              {
                "standard_name": string,
                "scheme_name": string,
                "is_accredited_mla": boolean,
                "standard_group": string | null
              }
            ],
            "certification_main_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_additional_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_sectors": [
              {
                "sector_name": string,
                "sector_code": string
              }
            ],
            "updated_at": integer
          }
        ]
      }
  ]
}

Some data are Confidential

{
  "data": [
    {
        "companies_request_index": integer,
        "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,
        "certified_entity_addresses": [
          {
            "street": "Confidential",
            "city": "Confidential",
            "state": "Confidential",
            "post_code": "Confidential",
            "full_address": "Confidential",
            "country": string
          }
        ],
        "certificates": [
          {
            "cert_id": string,
            "accreditation_bodies_name": string,
            "certification_bodies_name": string,
            "certification_number": string,
            "certification_status": string,
            "certification_scope": string,
            "certification_standards_scheme": [
              {
                "standard_name": string,
                "scheme_name": string,
                "is_accredited_mla": boolean
              }
            ],
            "certification_main_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_additional_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_sectors": [
              {
                "sector_name": string,
                "sector_code": string
              }
            ],
            "updated_at": integer
          }
        ]
      }
  ]
}

Some data are Confidential with Certification Issuance Dates

{
  "data": [
    {
        "companies_request_index": integer,
        "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,
        "certified_entity_addresses": [
          {
            "street": "Confidential",
            "city": "Confidential",
            "state": "Confidential",
            "post_code": "Confidential",
            "full_address": "Confidential",
            "country": string
          }
        ],
        "certificates": [
          {
            "cert_id": string,
            "accreditation_bodies_name": string,
            "certification_bodies_name": string,
            "certification_number": string,
            "certification_status": string,
            "certification_scope": string,
            "certification_issuance_dates": {
              "certification_original_issued_date": string,
              "certification_issued_date": string,
              "certification_expiry_date": string
            },
            "certification_standards_scheme": [
              {
                "standard_name": string,
                "scheme_name": string,
                "is_accredited_mla": boolean
              }
            ],
            "certification_main_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_additional_sites": [
              {
                "street": string,
                "city": string,
                "state": string,
                "post_code": string,
                "full_address": string,
                "scope": string,
                "country": string
              }
            ],
            "certification_sectors": [
              {
                "sector_name": string,
                "sector_code": string
              }
            ],
            "updated_at": integer
          }
        ]
      }
  ]
}

Unauthorized Access

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

Forbidden Access

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

Insufficient Credit

{
  "type": "string",
  "title": "Insufficient credit.",
  "status": 403,
  "detail": "You are trying to access data that exceeds your available credits. To increase your available credits, please contact us at info@iafcertsearch.org.",
  "instance": "/bulk-companies",
  "code": "insufficient_credit"
}

API Request Limit Reached

{
    "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": "/bulk-companies",
    "code": "api_request_limit_reached"
}

PreviousRetrieve Company & Certificates NextAPI Credit Consumption

Last updated 16 days ago