Skip to main content
POST
/
v1
/
entities
Create person or company entity
curl --request POST \
  --url https://instance.prod.onboardapp.io/v1/entities \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "first_name": "<string>",
  "last_name": "<string>",
  "date_of_birth": "2023-12-25",
  "nationality": "<string>",
  "company_name": "<string>",
  "registration_number": "<string>",
  "country": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "external_reference": "<string>",
  "metadata": {}
}
'
import requests

url = "https://instance.prod.onboardapp.io/v1/entities"

payload = {
    "first_name": "<string>",
    "last_name": "<string>",
    "date_of_birth": "2023-12-25",
    "nationality": "<string>",
    "company_name": "<string>",
    "registration_number": "<string>",
    "country": "<string>",
    "address": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
    },
    "external_reference": "<string>",
    "metadata": {}
}
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({
    first_name: '<string>',
    last_name: '<string>',
    date_of_birth: '2023-12-25',
    nationality: '<string>',
    company_name: '<string>',
    registration_number: '<string>',
    country: '<string>',
    address: {
      line1: '<string>',
      line2: '<string>',
      city: '<string>',
      state: '<string>',
      postal_code: '<string>',
      country: '<string>'
    },
    external_reference: '<string>',
    metadata: {}
  })
};

fetch('https://instance.prod.onboardapp.io/v1/entities', 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/v1/entities",
  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([
    'first_name' => '<string>',
    'last_name' => '<string>',
    'date_of_birth' => '2023-12-25',
    'nationality' => '<string>',
    'company_name' => '<string>',
    'registration_number' => '<string>',
    'country' => '<string>',
    'address' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'city' => '<string>',
        'state' => '<string>',
        'postal_code' => '<string>',
        'country' => '<string>'
    ],
    'external_reference' => '<string>',
    'metadata' => [
        
    ]
  ]),
  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/v1/entities"

	payload := strings.NewReader("{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"date_of_birth\": \"2023-12-25\",\n  \"nationality\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"registration_number\": \"<string>\",\n  \"country\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"external_reference\": \"<string>\",\n  \"metadata\": {}\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/v1/entities")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"date_of_birth\": \"2023-12-25\",\n  \"nationality\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"registration_number\": \"<string>\",\n  \"country\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"external_reference\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://instance.prod.onboardapp.io/v1/entities")

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  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"date_of_birth\": \"2023-12-25\",\n  \"nationality\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"registration_number\": \"<string>\",\n  \"country\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"external_reference\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body
{
  "data": {
    "token": "ent_8f3k2m1n",
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "company_name": "<string>",
    "date_of_birth": "2023-12-25",
    "nationality": "GB",
    "registration_number": "<string>",
    "country": "GB",
    "address": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postal_code": "<string>",
      "country": "<string>"
    },
    "checks_summary": {
      "total": 123,
      "complete": 123,
      "pending": 123,
      "failed": 123
    },
    "alerts_summary": {
      "total": 123,
      "open": 123,
      "resolved": 123
    },
    "external_reference": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "request_id": "req_9k4m2n1p3q",
    "page": {
      "cursor": "<string>",
      "has_more": true
    }
  }
}
{
  "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

​
Idempotency-Key
string<uuid>

Unique key for idempotent request handling. If a request with the same key was already processed within the last 24 hours, the original response is returned.

Body

application/json

Request body for creating a new entity.

​
type
enum<string>
required

Entity type.

Available options:
Person,
Company
​
first_name
string

Person first name (required for Person type).

​
last_name
string

Person last name (required for Person type).

​
date_of_birth
string<date>

Person date of birth (YYYY-MM-DD).

​
nationality
string

ISO 3166-1 alpha-2 nationality code.

​
company_name
string

Company legal name (required for Company type).

​
registration_number
string

Company registration number.

​
country
string

ISO 3166-1 alpha-2 country code.

​
address
object

Structured address.

​
external_reference
string

Your internal reference ID. Used for idempotency.

Maximum string length: 255
​
metadata
object

Arbitrary key-value metadata.

Response

Entity created.

Standard response wrapper for all API endpoints. Contains the resource data and pagination metadata.

​
data
object

A person or company entity under compliance investigation. Entities are the subjects of verification checks and may generate alerts when screening matches are found. An entity can belong to multiple cases with different roles.

​
meta
object