Global Biz Verify API – Technical documentation

The Global Biz Verify API explained

This API provides a unified interface to 30+ business registries and is designed to help automate KYB corporate processes.

It offers three endpoints:

  • /check_registration_number
  • /check_business
  • /get_result

To verify a company is registered in its registration country business registry proceed as follows:

  • Use the /check_registration_number endpoint to verify if the structure of the Business Registration ID (number or code depending on the country) is correct. This is designed to avoid calling the much more expensive /check_business endpoint if we can determine from the structure only that the Business Registration ID is invalid.
  • Trigger a check against the business registry data using a combination of the "Country" + "Business Registration ID" + "Company Name" using the /check_business API endpoint. This API will return a /request_id parameter to be used as an input parameter to the /get_result API endpoint.
  • After a few seconds retrieve the result using the /get_result API endpoint.

To retrieve the check result we need to allow the target registries and our backend some time. Indeed, many registries impose rate limits on checks. Our API knows what the constraints of the target business registry are and performs the checks accordingly.

The suggested result retrieval approach for the API under normal operation is the following:

  • Wait 10 seconds after the call to the /check_business endpoint before calling the /get_result endpoint. The API will return a result in 99% of cases after 10 seconds.
  • Wait 20 more seconds (30 seconds after the call to the /check_business endpoint) if the previous /get_result call returns a "The result is not ready yet, please wait longer" message. The API will return a result in 99.5% of cases after 30 seconds.
  • Wait 1 hour (after the call to the /check_business endpoint) if the previous /get_result call returns a "The result is not ready yet, please wait longer" message. This is for cases where the API is processing large batches of checks and results are delayed due to rate limit constraints by either the target registry or our backend infrastructure.
  • Wait 24 hours (after the call to the /check_business endpoint) if the previous /get_result call returns a "The result is not ready yet, please wait longer" message. This is for cases where the API is under exceptionally high load and the processing queue is extremely large.

If the /get_result API endpoint still returns a "The result is not ready yet, please wait longer" message after 24 hours contact our support team at https://open-automation.io/contact/ for assistance.


The /check_registration_number/ endpoint

This API endpoint is used to check if a Business Registration ID (BR_ID) has a valid structure. If the structure is valid, it can be used with the /check_business endpoint. If it is not, it will not make sense to call the /check_business endpoint as it will always return a "match" = 0 result.

/check_registration_number/{country}/{BR_ID}

Response sample

{
  "br_id_valid": 0,
  "message": "string",
}
              
PATH PARAMETERS
country
required
string
Example: BRA
The country of the Business Registration ID number in either Alpha-2 or Alpha-3 format of the ISO 3166-1 specification.
BR_ID
required
string
Example: 51.885.242/0001-40
The type of the Business Registration ID of the company.
Responses
200 response
Response Headers
Content-Type
string
application/json
Response Schema: application/json
br_id_valid
integer
0 - the BR_ID format is invalid, any registry query will return "match" = 0
1 - the BR_ID format is valid a query using the /check_business API endpoint can be made
-1 - A technical error occurred, usually means the request or the BR_ID is not correctly formatted.
message
string
A human-readable explanation of the API response
The /check_business endpoint

This API endpoint queries the target country business registry data to verify the submitted company is indeed actively registered.

The API returns a "request_id" string identifier which can be used to retrieve the registry check once it is processed by the API backend.

/check_business

Request sample

{
  "registration_number": "35742739", 
  "business_name": "APPLE SLOVAKIA", 
  "country": "SK"
}
              

Response sample

{
  "request_id": "1749407497620978713",
}
              
PATH PARAMETERS
country
required
string
Example: SK
The country of the Business Registration ID number in either Alpha-2 or Alpha-3 format of the ISO 3166-1 specification.
registration_number
required
string
Example: 35742739
The Business Registration ID of the company.
The search is always done using the Business Registration ID.
business_name
required
string
Example: APPLE SLOVAKIA
The name of the company. The name will be used if a company with the provided Business Registration ID is found in the target registry data. If a company is found, the name is used to check if the provided company name matches the name in the target business registry.
Responses
200 response
Response Headers
Content-Type
application/json
Response Schema: application/json
request_id
string
Example: 1749407497620978713 - the unique identifier of the request, it will be used as a parameter in the /get_result API endpoint
The /get_result endpoint

This API endpoint is used to asynchronously retrieve the result of the business registry check.

The main result parameter is the "match" parameter.

/get_result

Request sample

{
  "request_id": "1749407497620978713"
}
              

Response sample

{
  "match": 1,
  "message": "Match / Found registration number in the national business registry",
  "matching_details": ["100% <-- APPLE SLOVAKIA / APPLE SLOVAKIA", "40% <-- APPLE SLOVAKIA / APPLE COMPUTERS SLOVAKIA"],
}
              
PATH PARAMETERS
request_id
required
string
Example: 1749407497620978713
The unique identifier of the request as returned by the /check_business API endpoint
Responses
200 response
Response Headers
Content-Type
application/json
Response Schema: application/json
match
string
1 - The company is registered in the target country business registry and is active.
0 - The company was either not found when searching using the Business Registration ID or the name of the company found doesn't match the expected name.
-1 - A technical error occurred, contact our support if this happens.
message
string
Example: Match / Found registration number in the national business registry
A human-readable explanation of the API result.
matching_details
array of string
Example: ["100% <-- APPLE SLOVAKIA / APPLE SLOVAKIA", "40% <-- APPLE SLOVAKIA / APPLE COMPUTERS SLOVAKIA"]
A list of matching results. Sometimes a company can have several names in the target business registry. In this case a fuzzy matching is done between the expected company name and the name found in the business registry. If the result of the fuzzy matching exceeds 50% for at least one of the names, we consider that the company name matches. This parameter is returned to allow users to use a personalized matching accuracy. For example, we could be much more restrictive and only accept 100% matches.
# Global Biz Verify API full example code

# Step 1: Check if the business registration format is valid avoid useless business registry checks

curl \
-H "Authorization: Bearer <access-token--contact-us-for-test-tokens>" \
https://eu-central-1.global-biz-verify-api.open-automation.io/check_registration_number/SK/35742739

# Step 2: Request a buisiness registry check and get back a request_id 
#         or the result directly if it is ready immediately

curl \
-H "Authorization: Bearer <access-token--contact-us-for-test-tokens>" \
-H "Content-Type: application/json" \
-d '{"registration_number": "35742739", "business_name": "APPLE SLOVAKIA", "country": "SK"}' \
https://eu-central-1.global-biz-verify-api.open-automation.io/check_business

# Step 3: Get the result using the previously provided result_id

curl \
-H "Authorization: Bearer <access-token--contact-us-for-test-tokens<" \
-H "Content-Type: application/json" \
-d '{"request_id": "1749407497620978713"}' \
https://eu-central-1.global-biz-verify-api.open-automation.io/get_result

# Check the technical documentation for detailed exaplanation of the 3 endpoints
 
import requests
import time

# Replace this with your actual token
access_token = "<access-token--contact-us-for-test-tokens<"
headers = {
    "Authorization": f"Bearer {access_token}"
}

# Step 1: Validate business registration format
country_code = "SK"
registration_number = "35742739"

response_step1 = requests.get(
    f"https://eu-central-1.global-biz-verify-api.open-automation.io/check_registration_number/{country_code}/{registration_number}",
    headers=headers
)
print("Step 1 - Registration Format Validation:")
print(response_step1.json())

# Step 2: Perform business registry check
headers_with_content_type = {
    **headers,
    "Content-Type": "application/json"
}

payload_step2 = {
    "registration_number": "35742739",
    "business_name": "APPLE SLOVAKIA",
    "country": "SK"
}

response_step2 = requests.post(
    "https://eu-central-1.global-biz-verify-api.open-automation.io/check_business",
    headers=headers_with_content_type,
    json=payload_step2
)
print("\nStep 2 - Business Check Request:")
step2_result = response_step2.json()
print(step2_result)

# Extract request_id if present
request_id = step2_result.get("request_id")
if request_id:
    # Step 3: Get result using request_id
    payload_step3 = {
        "request_id": request_id
    }

    time.sleep(10)
    response_step3 = requests.post(
        "https://eu-central-1.global-biz-verify-api.open-automation.io/get_result",
        headers=headers_with_content_type,
        json=payload_step3
    )
    print("\nStep 3 - Get Result:")
    print(response_step3.json())
else:
    print("\nStep 3 skipped: No request_id returned; result might be immediate.")
    
# Check the technical documentation for detailed exaplanation of the 3 endpoints

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var accessToken = "<access-token--contact-us-for-test-tokens>";
        var client = new HttpClient();

        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

        // Step 1: Validate business registration format
        var countryCode = "SK";
        var registrationNumber = "35742739";

        var step1Url = $"https://eu-central-1.global-biz-verify-api.open-automation.io/check_registration_number/{countryCode}/{registrationNumber}";
        var responseStep1 = await client.GetAsync(step1Url);
        var step1Json = await responseStep1.Content.ReadAsStringAsync();

        Console.WriteLine("Step 1 - Registration Format Validation:");
        Console.WriteLine(step1Json);

        // Step 2: Perform business registry check
        var step2Url = "https://eu-central-1.global-biz-verify-api.open-automation.io/check_business";
        var payloadStep2 = new
        {
            registration_number = "35742739",
            business_name = "APPLE SLOVAKIA",
            country = "SK"
        };
        var step2Content = new StringContent(JsonSerializer.Serialize(payloadStep2), Encoding.UTF8, "application/json");
        var responseStep2 = await client.PostAsync(step2Url, step2Content);
        var step2Json = await responseStep2.Content.ReadAsStringAsync();

        Console.WriteLine("\nStep 2 - Business Check Request:");
        Console.WriteLine(step2Json);

        // Parse step2 JSON and extract request_id
        using var doc = JsonDocument.Parse(step2Json);
        if (doc.RootElement.TryGetProperty("request_id", out var requestIdElement))
        {
            string requestId = requestIdElement.GetString();

            // Step 3: Get result using request_id
            var step3Url = "https://eu-central-1.global-biz-verify-api.open-automation.io/get_result";
            var payloadStep3 = new
            {
                request_id = requestId
            };
            await Task.Delay(10000); // sleep for 10 seconds
            var step3Content = new StringContent(JsonSerializer.Serialize(payloadStep3), Encoding.UTF8, "application/json");
            var responseStep3 = await client.PostAsync(step3Url, step3Content);
            var step3Json = await responseStep3.Content.ReadAsStringAsync();

            Console.WriteLine("\nStep 3 - Get Result:");
            Console.WriteLine(step3Json);
        }
        else
        {
            Console.WriteLine("\nStep 3 skipped: No request_id returned; result might be immediate.");
        }
    }
}

// Check the technical documentation for detailed exaplanation of the 3 endpoints