Skip to main content
POST
/
api
/
gateway
/
execute
/
{project_hash}
/
init
Initiate Company Verification (async)
curl --request POST \
  --url https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/init \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "company_name": "Acme Holdings Ltd",
  "registration_number": "12345678",
  "country": "GB",
  "company_type": "<string>",
  "incorporation_date": "2023-12-25",
  "industry": "<string>",
  "address_line_1": "<string>",
  "city": "<string>",
  "postcode": "<string>",
  "annual_revenue": "<string>",
  "employee_count": "<string>",
  "sic_codes": "<string>",
  "status": "<string>",
  "external_reference": "<string>",
  "directors": [
    {
      "first_name": "<string>",
      "last_name": "<string>",
      "date_of_birth": "2023-12-25",
      "nationality": "<string>",
      "role": "<string>",
      "appointed_date": "2023-12-25",
      "zenoo_entity_id": "<string>"
    }
  ],
  "ubos": [
    {
      "first_name": "<string>",
      "last_name": "<string>",
      "date_of_birth": "2023-12-25",
      "nationality": "<string>",
      "ownership_percentage": 123,
      "role": "<string>",
      "zenoo_entity_id": "<string>"
    }
  ]
}
'
import requests

url = "https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/init"

payload = {
    "company_name": "Acme Holdings Ltd",
    "registration_number": "12345678",
    "country": "GB",
    "company_type": "<string>",
    "incorporation_date": "2023-12-25",
    "industry": "<string>",
    "address_line_1": "<string>",
    "city": "<string>",
    "postcode": "<string>",
    "annual_revenue": "<string>",
    "employee_count": "<string>",
    "sic_codes": "<string>",
    "status": "<string>",
    "external_reference": "<string>",
    "directors": [
        {
            "first_name": "<string>",
            "last_name": "<string>",
            "date_of_birth": "2023-12-25",
            "nationality": "<string>",
            "role": "<string>",
            "appointed_date": "2023-12-25",
            "zenoo_entity_id": "<string>"
        }
    ],
    "ubos": [
        {
            "first_name": "<string>",
            "last_name": "<string>",
            "date_of_birth": "2023-12-25",
            "nationality": "<string>",
            "ownership_percentage": 123,
            "role": "<string>",
            "zenoo_entity_id": "<string>"
        }
    ]
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    company_name: 'Acme Holdings Ltd',
    registration_number: '12345678',
    country: 'GB',
    company_type: '<string>',
    incorporation_date: '2023-12-25',
    industry: '<string>',
    address_line_1: '<string>',
    city: '<string>',
    postcode: '<string>',
    annual_revenue: '<string>',
    employee_count: '<string>',
    sic_codes: '<string>',
    status: '<string>',
    external_reference: '<string>',
    directors: [
      {
        first_name: '<string>',
        last_name: '<string>',
        date_of_birth: '2023-12-25',
        nationality: '<string>',
        role: '<string>',
        appointed_date: '2023-12-25',
        zenoo_entity_id: '<string>'
      }
    ],
    ubos: [
      {
        first_name: '<string>',
        last_name: '<string>',
        date_of_birth: '2023-12-25',
        nationality: '<string>',
        ownership_percentage: 123,
        role: '<string>',
        zenoo_entity_id: '<string>'
      }
    ]
  })
};

fetch('https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/init', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/init",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'company_name' => 'Acme Holdings Ltd',
    'registration_number' => '12345678',
    'country' => 'GB',
    'company_type' => '<string>',
    'incorporation_date' => '2023-12-25',
    'industry' => '<string>',
    'address_line_1' => '<string>',
    'city' => '<string>',
    'postcode' => '<string>',
    'annual_revenue' => '<string>',
    'employee_count' => '<string>',
    'sic_codes' => '<string>',
    'status' => '<string>',
    'external_reference' => '<string>',
    'directors' => [
        [
                'first_name' => '<string>',
                'last_name' => '<string>',
                'date_of_birth' => '2023-12-25',
                'nationality' => '<string>',
                'role' => '<string>',
                'appointed_date' => '2023-12-25',
                'zenoo_entity_id' => '<string>'
        ]
    ],
    'ubos' => [
        [
                'first_name' => '<string>',
                'last_name' => '<string>',
                'date_of_birth' => '2023-12-25',
                'nationality' => '<string>',
                'ownership_percentage' => 123,
                'role' => '<string>',
                'zenoo_entity_id' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/init"

	payload := strings.NewReader("{\n  \"company_name\": \"Acme Holdings Ltd\",\n  \"registration_number\": \"12345678\",\n  \"country\": \"GB\",\n  \"company_type\": \"<string>\",\n  \"incorporation_date\": \"2023-12-25\",\n  \"industry\": \"<string>\",\n  \"address_line_1\": \"<string>\",\n  \"city\": \"<string>\",\n  \"postcode\": \"<string>\",\n  \"annual_revenue\": \"<string>\",\n  \"employee_count\": \"<string>\",\n  \"sic_codes\": \"<string>\",\n  \"status\": \"<string>\",\n  \"external_reference\": \"<string>\",\n  \"directors\": [\n    {\n      \"first_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"date_of_birth\": \"2023-12-25\",\n      \"nationality\": \"<string>\",\n      \"role\": \"<string>\",\n      \"appointed_date\": \"2023-12-25\",\n      \"zenoo_entity_id\": \"<string>\"\n    }\n  ],\n  \"ubos\": [\n    {\n      \"first_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"date_of_birth\": \"2023-12-25\",\n      \"nationality\": \"<string>\",\n      \"ownership_percentage\": 123,\n      \"role\": \"<string>\",\n      \"zenoo_entity_id\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/init")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"company_name\": \"Acme Holdings Ltd\",\n  \"registration_number\": \"12345678\",\n  \"country\": \"GB\",\n  \"company_type\": \"<string>\",\n  \"incorporation_date\": \"2023-12-25\",\n  \"industry\": \"<string>\",\n  \"address_line_1\": \"<string>\",\n  \"city\": \"<string>\",\n  \"postcode\": \"<string>\",\n  \"annual_revenue\": \"<string>\",\n  \"employee_count\": \"<string>\",\n  \"sic_codes\": \"<string>\",\n  \"status\": \"<string>\",\n  \"external_reference\": \"<string>\",\n  \"directors\": [\n    {\n      \"first_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"date_of_birth\": \"2023-12-25\",\n      \"nationality\": \"<string>\",\n      \"role\": \"<string>\",\n      \"appointed_date\": \"2023-12-25\",\n      \"zenoo_entity_id\": \"<string>\"\n    }\n  ],\n  \"ubos\": [\n    {\n      \"first_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"date_of_birth\": \"2023-12-25\",\n      \"nationality\": \"<string>\",\n      \"ownership_percentage\": 123,\n      \"role\": \"<string>\",\n      \"zenoo_entity_id\": \"<string>\"\n    }\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/init")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"company_name\": \"Acme Holdings Ltd\",\n  \"registration_number\": \"12345678\",\n  \"country\": \"GB\",\n  \"company_type\": \"<string>\",\n  \"incorporation_date\": \"2023-12-25\",\n  \"industry\": \"<string>\",\n  \"address_line_1\": \"<string>\",\n  \"city\": \"<string>\",\n  \"postcode\": \"<string>\",\n  \"annual_revenue\": \"<string>\",\n  \"employee_count\": \"<string>\",\n  \"sic_codes\": \"<string>\",\n  \"status\": \"<string>\",\n  \"external_reference\": \"<string>\",\n  \"directors\": [\n    {\n      \"first_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"date_of_birth\": \"2023-12-25\",\n      \"nationality\": \"<string>\",\n      \"role\": \"<string>\",\n      \"appointed_date\": \"2023-12-25\",\n      \"zenoo_entity_id\": \"<string>\"\n    }\n  ],\n  \"ubos\": [\n    {\n      \"first_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"date_of_birth\": \"2023-12-25\",\n      \"nationality\": \"<string>\",\n      \"ownership_percentage\": 123,\n      \"role\": \"<string>\",\n      \"zenoo_entity_id\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "tokens": {
    "pull": "<string>",
    "start": "<string>"
  }
}
{
  "error": {
    "message": "<string>",
    "request_id": "req_9k4m2n1p3q",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}
{
  "error": {
    "message": "<string>",
    "request_id": "req_9k4m2n1p3q",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}
{
  "error": {
    "message": "<string>",
    "request_id": "req_9k4m2n1p3q",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}
{
  "error": {
    "message": "<string>",
    "request_id": "req_9k4m2n1p3q",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}
{
  "error": {
    "message": "<string>",
    "request_id": "req_9k4m2n1p3q",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

Authorizations

​
X-API-KEY
string
header
required

Project-scoped API key for server-to-server authentication. Obtain keys from the Zenoo dashboard under Project Settings > API Keys. Staging and production environments use separate keys.

Headers

​
X-API-KEY
string
required

Project-scoped API key.

​
Idempotency-Key
string

Unique key for idempotent request handling.

Path Parameters

​
project_hash
string
required

Project identifier from Zenoo Studio.

Body

application/json

Request body for Company Verification. Zenoo accepts three tiers of data — more data produces richer results and fewer false positives.

TierFieldsResult Quality
Minimumcompany_name, registration_number, countryRegistry lookup + company screening
Standard+ directors[], ubos[], addressIndividual screening for each person
Full+ external_reference, annual_revenue, sic_codesIdempotency, enriched risk scoring
​
company_name
string
required

Legal name as registered with the company registry.

Example:

"Acme Holdings Ltd"

​
registration_number
string
required

Official company registration number.

Example:

"12345678"

​
country
string
required

Country of incorporation. ISO 3166-1 alpha-2 code.

Example:

"GB"

​
company_type
string

Legal entity type (e.g., Private Limited Company (Ltd), PLC, LLP).

​
incorporation_date
string<date>

Date of incorporation. ISO 8601 format (YYYY-MM-DD).

​
industry
string

Industry sector or classification.

​
address_line_1
string

Registered address street.

​
city
string

Registered address city.

​
postcode
string

Postal code.

​
annual_revenue
string

Annual revenue in base currency. Pass as a string.

​
employee_count
string

Number of employees. Pass as a string.

​
sic_codes
string

SIC codes, comma-separated (e.g., "64110,64191").

​
status
string

Current company status: Active, Dissolved, Struck Off.

​
external_reference
string

Your internal reference ID. Enables idempotency — submitting the same external_reference returns the existing result without creating a duplicate.

Maximum string length: 255
​
directors
object[]

Known directors. Each person is automatically screened for PEP/sanctions.

​
ubos
object[]

Known beneficial owners. Each person is automatically screened.

Response

Verification initiated. Use tokens to retrieve results.

Response from async initiation endpoints (/init). Contains tokens for retrieving results and constructing verification URLs.

​
tokens
object