> 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/bulk-retrieve-companies-and-certificates.md). # Bulk Retrieve Companies & Certificates ## 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. * **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.
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 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
NameTypeDescription
Content-Type*Stringapplication/json
x-http-authorization*String

API Key received from https://www.iafcertsearch.org/api-verification

Example:

x-http-authorization: <<API KEY>>

### Request Body
NameTypeDescription
companiesArray of ObjectsArray of companies to be matched

The maximum number of company data that this endpoint accepts is 100
companies.*company_country*StringCountry/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_nameStringCertified Entity Name (Company Name) as detailed on the Certificate.
companies.*.company_cityStringOptional city of the main entity address. When provided, companies in that city receive a higher match score.
companies.*.company_identifiersObject

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_rateNumber / StringThe minimum match score threshold for a result to be returned.

Example:
100 | "100%"
enhanced_fuzzy_matchingBoolean

Optional, Default is false.

Improves how name matches are scored. When true, 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 false, matching behaves as it does today.

Example: true | false

### Example Payload Request {% tabs %} {% tab title="Required Fields Only - Company Name" %} ```json { "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, "enhanced_fuzzy_matching": false } ``` {% endtab %} {% tab title="Required Fields Only - Company Identifiers" %} ```json { "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, "enhanced_fuzzy_matching": false } ``` {% endtab %} {% tab title="Some Fields Are Null" %} ```json { "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, "enhanced_fuzzy_matching": false } ``` {% endtab %} {% tab title="All Fields Have Values" %} ```json { "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, "enhanced_fuzzy_matching": false } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="cURL" %} ```url 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, "enhanced_fuzzy_matching": false }' ``` {% endtab %} {% tab title="Ruby" %} ```ruby 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 ``` {% endtab %} {% tab title="Python" %} ```python 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")) ``` {% endtab %} {% tab title="PHP" %} ```php '{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; ``` {% endtab %} {% tab title="Java" %} ```java 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(); ``` {% endtab %} {% tab title="Node.js" %} ```javascript 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); }); ``` {% endtab %} {% tab title="Go" %} ```go 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)) } ``` {% endtab %} {% tab title="C#" %} ```csharp 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); ``` {% endtab %} {% endtabs %} ### Responses {% tabs %} {% tab title="200" %} **Request Successful** ```json { "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 } ] } ] } ``` {% endtab %} {% tab title="200" %} **Request Successful with Standards Group** ```json { "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 } ] } ] } ``` {% endtab %} {% tab title="200" %} **Request Successful with Certification Issuance Dates** ```json { "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 } ] } ] } ``` {% endtab %} {% tab title="200" %} **Request Successful with Standards Group and Certification Issuance Dates** ```json { "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 } ] } ] } ``` {% endtab %} {% tab title="200" %} **Some data are Confidential** ```json { "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 } ] } ] } ``` {% endtab %} {% tab title="200" %} **Some data are Confidential with Certification Issuance Dates** ```json { "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 } ] } ] } ``` {% endtab %} {% tab title="200" %} **No Results** ```json { "data": [] } ``` {% 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": "/bulk-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": "/bulk-companies", "code": "forbidden" } ``` {% endtab %} {% tab title="403" %} **Insufficient Credit** ```json { "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" } ``` {% 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": "/bulk-companies", "code": "api_request_limit_reached" } ``` {% endtab %} {% endtabs %}