Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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%"

enhanced_fuzzy_matching

Boolean

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

Responses

Request Successful

Request Successful with Standards Group

Request Successful with Certification Issuance Dates

Request Successful with Standards Group and Certification Issuance Dates

Some data are Confidential

Some data are Confidential with Certification Issuance Dates

No Results

Unauthorized Access

Forbidden Access

Insufficient Credit

API Request Limit Reached

Last updated