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
companiesmust 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_nameorcompany_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_rateis provided.If an invalid (non-numeric)
match_rateis 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:
BandScore Rangematch_typeVery High
94 – 100
exactly_matchedHigh
80 – 93
loosely_matchedMedium
60 – 79
loosely_matchedLow
30 – 59
loosely_matchedVery Low
0 – 29
not matched
Match Type:
match_typeis 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_factorsis an object of booleans indicating which submitted fields contributed to the match. Each flag istruewhen 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_matchingis 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_indexfield in the response to correlate which item from thecompaniesrequest data array the Certified Entity was matched with. The first element of thecompaniesrequest data array starts with the index 0. (i.e., The corresponding matched record will have a value ofcompanies_request_index: 0)
Headers
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
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