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

    • loosely_matched — score 30–93 (High, Medium, or Low band).

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

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

• Credits & Persistence:

  • No credits are consumed and no data is saved to the company's default list, regardless of match_type.

• 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_city	String	Optional city of the main entity address. When provided, companies in that city receive a higher match score.
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%"
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_city": null,
  "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

Some Fields Are Null

All Fields Have Values

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_city": "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

Python

PHP

Java

Node.js

Go

C#

Responses

200

With Results

{
  "data": [
    {
      "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,
      "company_identifiers": { // Only present when company_identifiers were provided in the request
        "vat": "string",
        "tax_id": "string",
        "business_registration_number": "string",
        "duns_number": "string",
        "company_id_number": "string"
      },
      "certified_entity_addresses": [
        {
          "street": string,
          "city": string,
          "state": string,
          "post_code": string,
          "full_address": string,
          "country": string
        }
      ],
    },
    ...
  ]
}

200

200

400

401

403

403