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.

• Match Rate Value:

  • The default rate value is set to 100.

  • The minimum acceptable rate value is 80, regardless of whether a lower threshold is specified.

  • Valid rate values range from 80 to 100, in increments of 5.

  • Any rate value exceeding 100 will automatically be capped at 100.

• 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_identifiers	Object	Additional Company Fields Format: "company_identifiers": { "vat": "string", "tax_id": "string", "business_registration_number": "string", "duns_number": "string", "company_id_number": "string" }
match_rate	Number / String	The percentage or similarity score indicating how closely the details of two companies match during the verification process. Example: 100 | "100%"

Example Payload Request

Required Fields Only - Company Name

{
    "companies": [
        {
          "company_name": "IAF",
          "company_country": "Australia",
          "company_identifiers": {
            "vat": null,
            "tax_id": null,
            "business_registration_number": null,
            "duns_number": null,
            "company_id_number": null
          }          
        }
    ],
    "match_rate": 90
}

Required Fields Only - Company Identifiers

{
    "companies": [
        {
          "company_name": null,
          "company_country": "Australia",
          "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
}

Some Fields Are Null

{
    "companies": [
        {
          "company_name": "IAF",
          "company_country": "Australia",
          "company_identifiers": {
            "vat": null,
            "tax_id": null,
            "business_registration_number": null,
            "duns_number": "DUNS NUMBER",
            "company_id_number": "COMPANY ID NUMBER"
          }
        }
    ],
    "match_rate": 100
}

All Fields Have Values

{
    "companies": [
        {
          "company_name": "QualityTrade",
          "company_country": "Australia",
          "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

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_identifiers": {
            "vat": "string",
            "tax_id": "string",
            "business_registration_number": "string",
            "duns_number": "string",
            "company_id_number": "string"
          }
        }
    ],
    "match_rate": 90
}'

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_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

Python

import http.client
import json

conn = http.client.HTTPSConnection("{API_URL}")
payload = json.dumps({
  "companies": [
    {
      "company_name": "string",
      "company_country": "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

<?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_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;

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_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();

Node.js

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

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

C#

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_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

200

Request Successful

{
  "data": [
    {
        "companies_request_index": integer,
        "ce_id": string,
        "matched_certified_entity_name": string,
        "match_status": string,
        "match_type": string,
        "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
          }
        ]
      }
  ]
}

200

Some data are Confidential

{
  "data": [
    {
        "companies_request_index": integer,
        "ce_id": string,
        "matched_certified_entity_name": string,
        "match_status": string,
        "match_type": string,
        "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
          }
        ]
      }
  ]
}

200

No Results

{
  "data": []
}

401

Unauthorized Access

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

403

Forbidden Access

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

403

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 [e-mail].",
  "instance": "/bulk-companies",
  "code": "insufficient_credit"
}

403

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 [e-mail].",
    "instance": "/bulk-companies",
    "code": "api_request_limit_reached"
}