Entities API

Entities represent companies or individuals in your due diligence workflows. They are the subjects of KYC assessments, screening checks, and risk profiling.

Two Entity Types

Companies: Legal entities - corporations, LLCs, partnerships, funds, and more.
Individuals: Natural persons - directors, beneficial owners, controllers, and beneficiaries.

Entity Object

Fields returned by GET /entities/{entity_id}/. Company-specific and individual-specific fields are returned only for the relevant entity type.

Common fields (all entities)

Field	Type	Description
`id`	uuid	Unique identifier
`name`	string	Computed display name (auto-calculated; cannot be set directly)
`entity_type`	string	`company` or `individual`. Immutable after creation.
`entity_subtype`	string \| null	Sub-classification. See Entity Subtypes.
`external_id`	string \| null	Your internal reference ID for this entity
`email`	string	Contact email address
`phone`	string	Contact phone number
`address_line_1`	string	Address line 1
`address_line_2`	string	Address line 2
`address_city`	string	City
`address_state`	string	State / province
`address_postal_code`	string	Postal / ZIP code
`address_country`	string	ISO 3166-1 alpha-2 country code
`is_primary`	boolean	Whether this is a primary entity for your tenant. Once set to `true`, cannot be demoted.
`screening_status`	string	Latest screening decision: `not_screened`, `not_reviewed`, `pending`, `approved`, `conditional`, `rejected`
`response_count`	integer	Number of DDQ responses linked to this entity
`risk_profiles_count`	integer	Number of risk profiles from screening
`created_at`	datetime	ISO 8601 creation timestamp
`updated_at`	datetime	ISO 8601 last-updated timestamp

Company-only fields

Field	Type	Description
`legal_name`	string	Registered legal name
`trading_name`	string	Trading / DBA name. Used as `name` when present.
`registration_number`	string	Company registration / incorporation number
`jurisdiction`	string	ISO 3166-1 alpha-2 country of incorporation
`incorporation_date`	date \| null	Date of incorporation (YYYY-MM-DD)

Individual-only fields

Field	Type	Description
`title`	string	Honorific (Mr, Ms, Dr …)
`first_name`	string	First / given name
`middle_name`	string	Middle name
`last_name`	string	Last / family name
`gender`	string	Gender
`date_of_birth`	date \| null	Date of birth (YYYY-MM-DD)
`nationality`	string	ISO 3166-1 alpha-2 nationality code
`country_of_birth`	string	ISO 3166-1 alpha-2 country of birth
`national_id_number`	string	National ID / passport number. Masked by default; use `?reveal_sensitive=true` for full value.
`tax_id`	string	Tax identification number. Masked by default.
`ssn`	string	Social Security Number (US). Masked by default.
`social_insurance_number`	string	Social Insurance Number (Canada). Masked by default.

Sensitive identity fields are masked by default

Fields national_id_number, tax_id, ssn, and social_insurance_number return only the last 4 characters unless you pass ?reveal_sensitive=true on a retrieve call. Every reveal access is audit-logged.

Create Entity

Create a new company or individual entity. The name field is computed automatically and cannot be set directly.

POST /api/v1/entities/

POST /api/v2/entities/

Request body

Field	Type	Required	Description
`entity_type`	string	Yes	`company` or `individual`. Immutable after creation.
`legal_name`	string	Company*	Registered legal name
`trading_name`	string	Company*	Trading / DBA name. Used as the entity's display name if provided.
`first_name`	string	Individual	First name (required for individuals)
`last_name`	string	Individual	Last name (required for individuals)
`middle_name`	string	No	Middle name
`title`	string	No	Honorific (Mr, Ms, Dr …)
`gender`	string	No	Gender
`date_of_birth`	date	No	YYYY-MM-DD, must be in the past
`incorporation_date`	date	No	YYYY-MM-DD
`registration_number`	string	No	Company registration number
`jurisdiction`	string	No	ISO 3166-1 alpha-2 country code
`nationality`	string	No	ISO 3166-1 alpha-2 nationality
`country_of_birth`	string	No	ISO 3166-1 alpha-2 country of birth
`national_id_number`	string	No	National ID / passport number
`tax_id`	string	No	Tax identification number
`ssn`	string	No	Social Security Number (US)
`social_insurance_number`	string	No	Social Insurance Number (Canada)
`entity_subtype`	string	No	See Entity Subtypes
`email`	string	No	Contact email address
`phone`	string	No	Contact phone number
`address_line_1`	string	No	Address line 1
`address_line_2`	string	No	Address line 2
`address_city`	string	No	City
`address_state`	string	No	State / province
`address_postal_code`	string	No	Postal / ZIP code
`address_country`	string	No	ISO 3166-1 alpha-2 country code
`external_id`	string	No	Your internal reference ID (max 255 chars)
`is_primary`	boolean	No	Default `true`. Once set to true, cannot be demoted.

* For company entities, at least one of legal_name or trading_name is required. For individual entities, both first_name and last_name are required.

Use idempotency keys

Pass Idempotency-Key to safely retry without creating duplicate entities. The SDK auto-generates one if you don't provide it.

Create Company Entity

curl -X POST https://api.kycgenie.com/api/v1/entities/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: company-acme-12345678" \
  -d '{
    "entity_type": "company",
    "legal_name": "Acme Corporation Ltd",
    "trading_name": "Acme Corp",
    "entity_subtype": "Private Limited Company",
    "jurisdiction": "GB",
    "incorporation_date": "2020-01-15",
    "registration_number": "12345678",
    "address_line_1": "123 Business Street",
    "address_city": "London",
    "address_postal_code": "SW1A 1AA",
    "address_country": "GB",
    "email": "contact@acme.com",
    "is_primary": true
  }'

curl -X POST https://api.kycgenie.com/api/v2/entities/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: company-acme-12345678" \
  -d '{
    "entity_type": "company",
    "legal_name": "Acme Corporation Ltd",
    "trading_name": "Acme Corp",
    "entity_subtype": "Private Limited Company",
    "jurisdiction": "GB",
    "incorporation_date": "2020-01-15",
    "registration_number": "12345678",
    "address_line_1": "123 Business Street",
    "address_city": "London",
    "address_postal_code": "SW1A 1AA",
    "address_country": "GB",
    "email": "contact@acme.com",
    "is_primary": true
  }'

import requests

response = requests.post(
    "https://api.kycgenie.com/api/v1/entities/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": "company-acme-12345678",
    },
    json={
        "entity_type": "company",
        "legal_name": "Acme Corporation Ltd",
        "trading_name": "Acme Corp",
        "entity_subtype": "Private Limited Company",
        "jurisdiction": "GB",
        "incorporation_date": "2020-01-15",
        "registration_number": "12345678",
        "address_line_1": "123 Business Street",
        "address_city": "London",
        "address_postal_code": "SW1A 1AA",
        "address_country": "GB",
        "email": "contact@acme.com",
        "is_primary": True,
    },
)

entity = response.json()
print(f"Created: {entity['name']}")  # "Acme Corp"

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

entity = client.entities.create(
    entity_type="company",
    legal_name="Acme Corporation Ltd",
    trading_name="Acme Corp",
    entity_subtype="Private Limited Company",
    jurisdiction="GB",
    incorporation_date="2020-01-15",
    registration_number="12345678",
    address_line_1="123 Business Street",
    address_city="London",
    address_postal_code="SW1A 1AA",
    address_country="GB",
    email="contact@acme.com",
    is_primary=True,
)

print(f"Created: {entity.name}")  # "Acme Corp"

const response = await fetch('https://api.kycgenie.com/api/v1/entities/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'company-acme-12345678',
  },
  body: JSON.stringify({
    entity_type: 'company',
    legal_name: 'Acme Corporation Ltd',
    trading_name: 'Acme Corp',
    entity_subtype: 'Private Limited Company',
    jurisdiction: 'GB',
    incorporation_date: '2020-01-15',
    registration_number: '12345678',
    address_line_1: '123 Business Street',
    address_city: 'London',
    address_postal_code: 'SW1A 1AA',
    address_country: 'GB',
    email: 'contact@acme.com',
    is_primary: true,
  }),
});
const entity = await response.json();
console.log(`Created: ${entity.name}`);  // "Acme Corp"

const response = await fetch('https://api.kycgenie.com/api/v2/entities/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'company-acme-12345678',
  },
  body: JSON.stringify({
    entity_type: 'company',
    legal_name: 'Acme Corporation Ltd',
    trading_name: 'Acme Corp',
    entity_subtype: 'Private Limited Company',
    jurisdiction: 'GB',
    incorporation_date: '2020-01-15',
    registration_number: '12345678',
    address_line_1: '123 Business Street',
    address_city: 'London',
    address_postal_code: 'SW1A 1AA',
    address_country: 'GB',
    email: 'contact@acme.com',
    is_primary: true,
  }),
});
const entity = await response.json();
console.log(`Created: ${entity.name}`);  // "Acme Corp"

Create Individual Entity

curl -X POST https://api.kycgenie.com/api/v1/entities/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: individual-john-smith-1985-06-15" \
  -d '{
    "entity_type": "individual",
    "first_name": "John",
    "last_name": "Smith",
    "date_of_birth": "1985-06-15",
    "nationality": "GB",
    "email": "john.smith@example.com",
    "address_country": "GB"
  }'

curl -X POST https://api.kycgenie.com/api/v2/entities/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: individual-john-smith-1985-06-15" \
  -d '{
    "entity_type": "individual",
    "first_name": "John",
    "last_name": "Smith",
    "date_of_birth": "1985-06-15",
    "nationality": "GB",
    "email": "john.smith@example.com",
    "address_country": "GB"
  }'

entity = requests.post(
    "https://api.kycgenie.com/api/v1/entities/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": "individual-john-smith-12345678",
    },
    json={
        "entity_type": "individual",
        "first_name": "John",
        "last_name": "Smith",
        "date_of_birth": "1985-06-15",
        "nationality": "GB",
        "email": "john.smith@example.com",
        "address_country": "GB",
    },
).json()
# name auto-calculated as "John Smith"
print(entity["name"])

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

entity = client.entities.create(
    entity_type="individual",
    first_name="John",
    last_name="Smith",
    date_of_birth="1985-06-15",
    nationality="GB",
    email="john.smith@example.com",
    address_country="GB",
)
print(entity.name)  # "John Smith"

const entity = await fetch('https://api.kycgenie.com/api/v1/entities/', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    entity_type: 'individual', first_name: 'John', last_name: 'Smith',
    date_of_birth: '1985-06-15', nationality: 'GB',
    email: 'john.smith@example.com', address_country: 'GB',
  }),
}).then(r => r.json());
console.log(entity.name); // "John Smith"

const entity = await fetch('https://api.kycgenie.com/api/v2/entities/', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    entity_type: 'individual', first_name: 'John', last_name: 'Smith',
    date_of_birth: '1985-06-15', nationality: 'GB',
    email: 'john.smith@example.com', address_country: 'GB',
  }),
}).then(r => r.json());
console.log(entity.name); // "John Smith"

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corp",
  "entity_type": "company",
  "legal_name": "Acme Corporation Ltd",
  "trading_name": "Acme Corp",
  "first_name": "",
  "middle_name": "",
  "last_name": "",
  "email": "contact@acme.com",
  "phone": "",
  "external_id": null,
  "is_primary": true,
  "address_line_1": "123 Business Street",
  "address_line_2": "",
  "address_city": "London",
  "address_state": "",
  "address_postal_code": "SW1A 1AA",
  "address_country": "GB",
  "nationality": "",
  "date_of_birth": null,
  "incorporation_date": "2020-01-15",
  "jurisdiction": "GB",
  "registration_number": "12345678",
  "created_at": "2026-01-14T12:41:56.456529Z"
}

List Entities

Returns a paginated list of entities for your tenant.

GET /api/v1/entities/

Query parameters

Parameter	Type	Description
`entity_type`	string	Filter by `company` or `individual`
`is_primary`	boolean	Filter by primary status
`search`	string	Name/email keyword search
`external_id`	string	Filter by your external reference ID
`created_after`	datetime	ISO 8601 - only entities created after this time
`created_before`	datetime	ISO 8601 - only entities created before this time
`page`	integer	Page number (default: 1)
`page_size`	integer	Results per page (default: 20, max: 100)
`after`	string	Cursor - return results after this cursor (from `next_cursor`)
`before`	string	Cursor - return results before this cursor (from `prev_cursor`)
`page_size`	integer	Results per page (default: 50, max: 100)

Response

Field	Type	Description
`count`	integer	Total number of matching entities
`page`	integer	Current page number
`page_size`	integer	Number of results in this page
`total_pages`	integer	Total number of pages
`results`	array	Array of entity summary objects

Field	Type	Description
`has_more`	boolean	Whether additional results exist
`next_cursor`	string \| null	Pass as `after` to fetch the next page
`prev_cursor`	string \| null	Pass as `before` to fetch the previous page
`results`	array	Array of entity summary objects

Each item in results contains: id, name, entity_type, external_id, is_primary, screening_status, response_count, risk_profiles_count, created_at.

List Entities

curl "https://api.kycgenie.com/api/v1/entities/?entity_type=company&page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# First page
curl "https://api.kycgenie.com/api/v2/entities/?entity_type=company&page_size=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page - pass next_cursor from the previous response as 'after'
curl "https://api.kycgenie.com/api/v2/entities/?entity_type=company&page_size=50&after=eyJpZCI6IjU1MWU4NTAwIn0" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

# First page
data = requests.get(
    "https://api.kycgenie.com/api/v1/entities/",
    headers=headers,
    params={"entity_type": "company", "page": 1, "page_size": 20},
).json()

print(f"Total: {data['count']} | Pages: {data['total_pages']}")
for entity in data["results"]:
    print(f"  {entity['name']} ({entity['entity_type']})")

# v1 - next page by page number
if data["page"] < data["total_pages"]:
    page2 = requests.get(
        "https://api.kycgenie.com/api/v1/entities/",
        headers=headers,
        params={"entity_type": "company", "page": data["page"] + 1, "page_size": 20},
    ).json()

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

# Returns cursor-paginated response
page = client.entities.list(entity_type="company", page_size=50)
print(f"Has more: {page.has_more}")
for entity in page.results:
    print(f"  {entity.name}")

# Paginate
if page.has_more:
    page2 = client.entities.list(
        entity_type="company",
        after=page.next_cursor,
        page_size=50,
    )

const params = new URLSearchParams({
  entity_type: 'company',
  page: '1',
  page_size: '20',
});
const data = await fetch(
  `https://api.kycgenie.com/api/v1/entities/?${params}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

console.log(`Total: ${data.count} | Pages: ${data.total_pages}`);
data.results.forEach(e => console.log(e.name));

// First page
let data = await fetch(
  `https://api.kycgenie.com/api/v2/entities/?entity_type=company&page_size=50`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

data.results.forEach(e => console.log(e.name));

// Next page - pass next_cursor as 'after'
if (data.has_more) {
  const next = await fetch(
    `https://api.kycgenie.com/api/v2/entities/?entity_type=company&page_size=50&after=${data.next_cursor}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  ).then(r => r.json());
  next.results.forEach(e => console.log(e.name));
}

Response

{
  "count": 142,
  "page": 1,
  "page_size": 20,
  "total_pages": 8,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corp",
      "entity_type": "company",
      "external_id": "EXT-001",
      "is_primary": true,
      "screening_status": "approved",
      "response_count": 3,
      "risk_profiles_count": 1,
      "created_at": "2026-01-10T09:30:00Z"
    }
  ]
}

Response

{
  "has_more": true,
  "next_cursor": "eyJpZCI6IjU1MWU4NTAwIn0",
  "prev_cursor": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corp",
      "entity_type": "company",
      "external_id": "EXT-001",
      "is_primary": true,
      "screening_status": "approved",
      "response_count": 3,
      "risk_profiles_count": 1,
      "created_at": "2026-01-10T09:30:00Z"
    }
  ]
}

Retrieve Entity

Returns the full Entity Object for a single entity by ID.

GET /api/v1/entities/{entity_id}/

GET /api/v2/entities/{entity_id}/

Query parameters

Parameter	Type	Description
`reveal_sensitive`	boolean	Pass `true` to receive unmasked values for `national_id_number`, `tax_id`, `ssn`, and `social_insurance_number`. Access is audit-logged. Default: `false`.

Retrieve Entity

curl "https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Reveal masked sensitive identity fields (audit-logged)
curl "https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/?reveal_sensitive=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.kycgenie.com/api/v2/entities/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

entity_id = "550e8400-e29b-41d4-a716-446655440000"

entity = requests.get(
    f"https://api.kycgenie.com/api/v1/entities/{entity_id}/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
).json()

print(entity["name"])

# To unmask sensitive fields (audit-logged)
entity_full = requests.get(
    f"https://api.kycgenie.com/api/v1/entities/{entity_id}/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"reveal_sensitive": "true"},
).json()

# national_id_number, tax_id, ssn, social_insurance_number now fully unmasked
print(entity_full.get("national_id_number"))

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

entity = client.entities.get(
    entity_id="550e8400-e29b-41d4-a716-446655440000",
)
print(entity.name)

# Unmask sensitive fields (audit-logged)
entity_full = client.entities.get(
    entity_id="550e8400-e29b-41d4-a716-446655440000",
    reveal_sensitive=True,
)
print(entity_full.national_id_number)  # fully unmasked

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const entity = await fetch(
  `https://api.kycgenie.com/api/v1/entities/${entityId}/`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

// Unmask sensitive fields
const entityFull = await fetch(
  `https://api.kycgenie.com/api/v1/entities/${entityId}/?reveal_sensitive=true`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const entity = await fetch(
  `https://api.kycgenie.com/api/v2/entities/${entityId}/`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corp",
  "entity_type": "company",
  "entity_subtype": null,
  "legal_name": "Acme Corporation Ltd",
  "trading_name": "Acme Corp",
  "registration_number": "12345678",
  "jurisdiction": "GB",
  "incorporation_date": "2020-01-15",
  "external_id": null,
  "address_line_1": "123 Business Street",
  "address_line_2": "",
  "address_city": "London",
  "address_state": "",
  "address_postal_code": "SW1A 1AA",
  "address_country": "GB",
  "is_primary": true,
  "screening_status": "not_screened",
  "response_count": 0,
  "risk_profiles_count": 0,
  "created_at": "2026-01-10T09:30:00Z",
  "updated_at": "2026-01-27T14:00:00Z"
}

{
  "id": "661f9511-f30c-52e5-b827-557766551111",
  "name": "Jane Smith",
  "entity_type": "individual",
  "entity_subtype": null,
  "title": "Ms",
  "first_name": "Jane",
  "middle_name": "",
  "last_name": "Smith",
  "gender": "",
  "date_of_birth": "1985-06-15",
  "nationality": "GB",
  "country_of_birth": "GB",
  "national_id_number": "****6789",
  "tax_id": "",
  "ssn": "",
  "social_insurance_number": "",
  "external_id": null,
  "address_line_1": "45 Elm Road",
  "address_line_2": "",
  "address_city": "Manchester",
  "address_state": "",
  "address_postal_code": "M1 2AB",
  "address_country": "GB",
  "is_primary": true,
  "screening_status": "not_screened",
  "response_count": 0,
  "risk_profiles_count": 0,
  "created_at": "2026-02-01T11:00:00Z",
  "updated_at": "2026-02-01T11:00:00Z"
}

Sensitive fields are masked to last 4 characters by default. Add ?reveal_sensitive=true for full values (access is audit-logged).

Update Entity

Partially update entity fields. Only the fields you include are modified.

PATCH /api/v1/entities/{entity_id}/

PATCH /api/v2/entities/{entity_id}/

Field update constraints

name and entity_type are immutable - cannot be updated after creation.
is_primary can only be promoted (false → true). Once primary, it cannot be demoted.
jurisdiction, nationality, and address_country must be ISO 3166-1 alpha-2 codes.

Response (200 OK)

Field	Type	Description
`id`	uuid	Entity ID
`name`	string	Computed display name
`entity_type`	string	Entity type
`updated_fields`	array	List of field names that were changed
`updated_at`	datetime	ISO 8601 timestamp of the update

Update Entity

curl -X PATCH https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: update-address-20260127" \
  -d '{
    "trading_name": "Acme Financial Corp",
    "address_line_1": "789 New Business Plaza",
    "address_city": "Birmingham",
    "address_postal_code": "B1 1AA"
  }'

curl -X PATCH https://api.kycgenie.com/api/v2/entities/550e8400-e29b-41d4-a716-446655440000/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trading_name": "Acme Financial Corp",
    "address_line_1": "789 New Business Plaza"
  }'

import requests

entity_id = "550e8400-e29b-41d4-a716-446655440000"
result = requests.patch(
    f"https://api.kycgenie.com/api/v1/entities/{entity_id}/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": "update-address-20260127",
    },
    json={
        "trading_name": "Acme Financial Corp",
        "address_line_1": "789 New Business Plaza",
        "address_city": "Birmingham",
        "address_postal_code": "B1 1AA",
    },
).json()

print(f"Updated: {result['name']}")
print(f"Changed: {result['updated_fields']}")

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

result = client.entities.update(
    entity_id="550e8400-e29b-41d4-a716-446655440000",
    trading_name="Acme Financial Corp",
    address_line_1="789 New Business Plaza",
    address_city="Birmingham",
    address_postal_code="B1 1AA",
)
print(result.updated_fields)

const result = await fetch(
  `https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/`,
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'update-address-20260127',
    },
    body: JSON.stringify({
      trading_name: 'Acme Financial Corp',
      address_line_1: '789 New Business Plaza',
      address_city: 'Birmingham',
      address_postal_code: 'B1 1AA',
    }),
  }
).then(r => r.json());

console.log(result.updated_fields);

const result = await fetch(
  `https://api.kycgenie.com/api/v2/entities/550e8400-e29b-41d4-a716-446655440000/`,
  {
    method: 'PATCH',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({ trading_name: 'Acme Financial Corp' }),
  }
).then(r => r.json());

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Financial Corp",
  "entity_type": "company",
  "updated_fields": ["trading_name", "address_line_1", "address_city", "address_postal_code"],
  "updated_at": "2026-01-27T14:22:00Z"
}

Delete Entity

Delete or archive an entity. The behaviour depends on whether the entity has associated KYC activity.

DELETE /api/v1/entities/{entity_id}/

DELETE /api/v2/entities/{entity_id}/

Compliance-safe deletion

If an entity has any KYC activity - screening results, identity verifications, multi-bureau checks, or DDQ responses - it cannot be hard-deleted. Instead, it is archived: all data is retained for the required regulatory retention period, then purged automatically. The response body includes a purge_after date when the data will be destroyed.

Response behaviour

Scenario	Status	Body
Entity has KYC activity (screening / verification / multi-bureau / responses)	`200 OK`	`{"status": "archived", "purge_after": "2033-01-27T00:00:00Z"}`
Entity has no KYC activity - clean delete	`204 No Content`	No body

Delete Entity

curl -X DELETE https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -w "\nHTTP Status: %{http_code}"

curl -X DELETE https://api.kycgenie.com/api/v2/entities/550e8400-e29b-41d4-a716-446655440000/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -w "\nHTTP Status: %{http_code}"

import requests

entity_id = "550e8400-e29b-41d4-a716-446655440000"
response = requests.delete(
    f"https://api.kycgenie.com/api/v1/entities/{entity_id}/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

if response.status_code == 200:
    data = response.json()
    if data["status"] == "deleted":
        # Clean delete - no KYC activity existed
        print("Entity permanently deleted.")
    else:
        # Archived for regulatory retention (FATF/AMLD)
        print(f"Archived. Data will be purged after: {data['purge_after']}")
else:
    print(f"Error: {response.json()}")

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

result = client.entities.delete(
    entity_id="550e8400-e29b-41d4-a716-446655440000",
)

if result.status == "deleted":
    print("Entity permanently deleted.")
elif result.status == "archived":
    print(f"Archived. Purge after: {result.purge_after}")

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
  `https://api.kycgenie.com/api/v1/entities/${entityId}/`,
  { method: 'DELETE', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

if (response.status === 200) {
  const data = await response.json();
  if (data.status === 'deleted') {
    console.log('Entity permanently deleted.');
  } else {
    console.log(`Archived. Purge after: ${data.purge_after}`);
  }
}

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
  `https://api.kycgenie.com/api/v2/entities/${entityId}/`,
  { method: 'DELETE', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

if (response.status === 200) {
  const data = await response.json();
  if (data.status === 'deleted') {
    console.log('Entity permanently deleted.');
  } else {
    console.log(`Archived. Purge after: ${data.purge_after}`);
  }
}

Response - Archived (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "archived",
  "purge_after": "2033-01-27T00:00:00Z"
}

Response - Clean Delete (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "deleted",
  "purge_after": null
}

Search Entities

Fuzzy search across entity names using similarity matching. Useful for deduplication checks before creating new entities.

GET /api/v1/entities/search/

Query parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query string
`entity_type`	string	No	Filter by `company` or `individual`
`threshold`	float	No	Similarity threshold 0.0–1.0 (default: 0.7). Higher = stricter matching.
`limit`	integer	No	Max results (default: 10, max: 50)

Response

Returns matching entities sorted by similarity score, descending.

Search Entities

curl "https://api.kycgenie.com/api/v1/entities/search/?q=Acme+Corp&threshold=0.7&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

results = requests.get(
    "https://api.kycgenie.com/api/v1/entities/search/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "q": "Acme Corp",
        "entity_type": "company",
        "threshold": 0.7,
        "limit": 10,
    },
).json()

print(f"Query: {results['query']} | Threshold: {results['threshold']}")
for match in results["results"]:
    print(f"  {match['name']} - similarity: {match['similarity']}")

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

results = client.entities.search(
    q="Acme Corp",
    entity_type="company",
    threshold=0.7,
    limit=10,
)

for match in results.results:
    print(f"{match.name} - similarity: {match.similarity}")

const params = new URLSearchParams({
  q: 'Acme Corp',
  entity_type: 'company',
  threshold: '0.7',
  limit: '10',
});
const results = await fetch(
  `https://api.kycgenie.com/api/v1/entities/search/?${params}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

results.results.forEach(m =>
  console.log(`${m.name} - similarity: ${m.similarity}`)
);

Response (200 OK)

{
  "query": "Acme Corp",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corp",
      "entity_type": "company",
      "entity_subtype": "Private Limited Company",
      "similarity": 1.0,
      "is_primary": true
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "Acme Finance Ltd",
      "entity_type": "company",
      "entity_subtype": "LLC",
      "similarity": 0.818,
      "is_primary": false
    }
  ]
}

Batch Create Entities

Create up to 200 entities in a single synchronous request. Ideal for onboarding workflows and bulk imports.

POST /api/v1/entities/batch/

POST /api/v2/entities/batch/

Limits

Max per request: 200 entities
Daily limit: 1,000 entities per tenant (resets at midnight UTC)
Duplicate detection: Automatic fuzzy matching on name + entity_type (enabled by default)

Request body

Field	Type	Required	Description
`entities`	array	Yes	1–200 entity objects. Each follows the same schema as Create Entity.
`skip_duplicates`	boolean	No	When `true` (default), entities matching an existing record by name/type are skipped rather than erroring.

Response fields

Field	Description
`summary`	Object with `requested`, `created`, `skipped`, `failed`, and `remaining_daily_quota` counts
`created_entities`	Array of successfully created entity objects
`skipped`	Array of entries that were skipped as duplicates, with `index`, `reason`, `existing_entity_id`, `matching_name`, and `similarity_score` (0.0–1.0)
`errors`	Array of validation errors, with `index` and `errors`

Batch Create Entities

curl -X POST https://api.kycgenie.com/api/v1/entities/batch/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-import-2026-01-27" \
  -d '{
    "entities": [
      {
        "entity_type": "company",
        "legal_name": "Acme Corp",
        "jurisdiction": "GB"
      },
      {
        "entity_type": "individual",
        "first_name": "Jane",
        "last_name": "Doe",
        "date_of_birth": "1990-03-22",
        "nationality": "US"
      }
    ],
    "skip_duplicates": true
  }'

curl -X POST https://api.kycgenie.com/api/v2/entities/batch/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entities": [
      {"entity_type": "company", "legal_name": "Acme Corp", "jurisdiction": "GB"},
      {"entity_type": "individual", "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1990-03-22"}
    ],
    "skip_duplicates": true
  }'

import requests

result = requests.post(
    "https://api.kycgenie.com/api/v1/entities/batch/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": "batch-import-2026-01-27",
    },
    json={
        "entities": [
            {"entity_type": "company", "legal_name": "Acme Corp", "jurisdiction": "GB"},
            {"entity_type": "individual", "first_name": "Jane", "last_name": "Doe",
             "date_of_birth": "1990-03-22", "nationality": "US"},
        ],
        "skip_duplicates": True,
    },
).json()

summary = result["summary"]
print(f"Created: {summary['created']}, Skipped: {summary['skipped']}, "
      f"Errors: {summary['failed']}, Remaining quota: {summary['remaining_daily_quota']}")

for entity in result["created_entities"]:
    print(f"  ✓ {entity['name']} ({entity['id']})")

for skipped in result["skipped"]:
    print(f"  ⊘ [{skipped['index']}] {skipped['matching_name']} (similarity: {skipped['similarity_score']})")

for error in result["errors"]:
    print(f"  ✗ [{error['index']}] {error['errors']}")

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

result = client.entities.batch_create(
    entities=[
        {"entity_type": "company", "legal_name": "Acme Corp", "jurisdiction": "GB"},
        {"entity_type": "individual", "first_name": "Jane", "last_name": "Doe",
         "date_of_birth": "1990-03-22", "nationality": "US"},
    ],
    skip_duplicates=True,
)

print(f"Created: {result.summary['created']}")
for entity in result.created_entities:
    print(f"  {entity.name}")

const result = await fetch('https://api.kycgenie.com/api/v1/entities/batch/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'batch-import-2026-01-27',
  },
  body: JSON.stringify({
    entities: [
      { entity_type: 'company', legal_name: 'Acme Corp', jurisdiction: 'GB' },
      { entity_type: 'individual', first_name: 'Jane', last_name: 'Doe',
        date_of_birth: '1990-03-22', nationality: 'US' },
    ],
    skip_duplicates: true,
  }),
}).then(r => r.json());

console.log(`Created: ${result.summary.created}, Remaining: ${result.summary.remaining_daily_quota}`);

const result = await fetch('https://api.kycgenie.com/api/v2/entities/batch/', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    entities: [
      { entity_type: 'company', legal_name: 'Acme Corp', jurisdiction: 'GB' },
    ],
    skip_duplicates: true,
  }),
}).then(r => r.json());

console.log(`Created: ${result.summary.created}`);

Response (200 OK)

{
  "summary": {
    "requested": 2,
    "created": 1,
    "skipped": 1,
    "failed": 0,
    "remaining_daily_quota": 998
  },
  "created_entities": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corp",
      "entity_type": "company",
      "created_at": "2026-01-27T12:00:00Z"
    }
  ],
  "skipped": [
    {
      "index": 1,
      "reason": "duplicate",
      "existing_entity_id": "0571139b-88bc-4fc0-92d4-3fffc1cb5feb",
      "matching_name": "Jane Doe",
      "similarity_score": 1.0
    }
  ],
  "errors": []
}

Entity Documents

Upload, list, download, and delete documents stored directly on an entity - such as certificates, passports, and financial statements.

Upload Entity Document

POST /api/v1/entities/{entity_id}/documents/upload/

POST /api/v2/entities/{entity_id}/documents/

Request body (multipart/form-data)

Field	Type	Required	Description
`file`	file	Yes	File to upload (max 10 MB)
`document_type`	string	Yes	Document type label (e.g. "Certificate of Incorporation")
`expiry_date`	date	No	YYYY-MM-DD expiry for the document

Upload Document

curl -X POST https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/documents/upload/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: upload-cert-inc-550e8400" \
  -F "file=@certificate_of_incorporation.pdf" \
  -F "document_type=Certificate of Incorporation"

curl -X POST https://api.kycgenie.com/api/v2/entities/550e8400-e29b-41d4-a716-446655440000/documents/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: upload-cert-inc-550e8400" \
  -F "file=@certificate_of_incorporation.pdf" \
  -F "document_type=Certificate of Incorporation"

import requests

entity_id = "550e8400-e29b-41d4-a716-446655440000"
with open("certificate_of_incorporation.pdf", "rb") as f:
    response = requests.post(
        f"https://api.kycgenie.com/api/v1/entities/{entity_id}/documents/upload/",
        headers={
            "Authorization": "Bearer YOUR_API_KEY",
            "Idempotency-Key": "upload-cert-inc-550e8400",
        },
        files={"file": ("certificate_of_incorporation.pdf", f, "application/pdf")},
        data={
            "document_type": "Certificate of Incorporation",
        },
    )
print(response.json())

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

with open("certificate_of_incorporation.pdf", "rb") as f:
    doc = client.entities.upload_document(
        entity_id="550e8400-e29b-41d4-a716-446655440000",
        file=f,
        document_type="Certificate of Incorporation",
    )
print(doc.id)

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('document_type', 'Certificate of Incorporation');

const doc = await fetch(
  'https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/documents/upload/',
  {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Idempotency-Key': 'upload-cert-inc-550e8400' },
    body: formData,
  }
).then(r => r.json());

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('document_type', 'Certificate of Incorporation');

const doc = await fetch(
  'https://api.kycgenie.com/api/v2/entities/550e8400-e29b-41d4-a716-446655440000/documents/',
  {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Idempotency-Key': 'upload-cert-inc-550e8400' },
    body: formData,
  }
).then(r => r.json());

List Entity Documents

GET /api/v1/entities/{entity_id}/documents/

GET /api/v2/entities/{entity_id}/documents/

Returns all documents attached to the entity, ordered by upload date descending. Both v1 and v2 return an envelope with count and documents - no cursor pagination is needed given the naturally bounded document count per entity.

List Documents

curl "https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/documents/" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.kycgenie.com/api/v2/entities/550e8400-e29b-41d4-a716-446655440000/documents/" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

entity_id = "550e8400-e29b-41d4-a716-446655440000"
data = requests.get(
    f"https://api.kycgenie.com/api/v1/entities/{entity_id}/documents/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
).json()

print(f"{data['entity_name']} - {data['count']} document(s)")
# v1: key is 'documents' | v2: key is 'results'
for doc in data["documents"]:
    print(f"{doc['document_type_name']}: {doc['name']} ({doc['size']} bytes)")

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

result = client.entities.list_documents(
    entity_id="550e8400-e29b-41d4-a716-446655440000",
)
print(f"{result.entity_name} - {result.count} document(s)")
# SDK wraps v2 - documents are under .results
for doc in result.results:
    print(f"{doc.document_type_name}: {doc.name}")

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const data = await fetch(
  `https://api.kycgenie.com/api/v1/entities/${entityId}/documents/`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

console.log(`${data.entity_name} - ${data.count} document(s)`);
data.documents.forEach(d => console.log(`${d.document_type_name}: ${d.name}`));

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const data = await fetch(
  `https://api.kycgenie.com/api/v2/entities/${entityId}/documents/`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

console.log(`${data.entity_name} - ${data.count} document(s)`);
// v2 uses 'results' (v1 uses 'documents')
data.results.forEach(d => console.log(`${d.document_type_name}: ${d.name}`));

Response (200 OK)

{
  "count": 1,
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_name": "Acme Corp",
  "documents": [
    {
      "id": "770f0622-g49d-63f6-c938-668877662222",
      "name": "certificate_of_incorporation.pdf",
      "size": 1048576,
      "content_type": "application/pdf",
      "document_type_name": "Certificate of Incorporation",
      "classification": "entity_private",
      "uploaded_by_email": "api.user@example.com",
      "created_at": "2026-01-15T10:30:00Z",
      "expiry_date": "2027-01-31"
    }
  ]
}

Response (200 OK)

{
  "count": 1,
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_name": "Acme Corp",
  "results": [
    {
      "id": "770f0622-g49d-63f6-c938-668877662222",
      "name": "certificate_of_incorporation.pdf",
      "size": 1048576,
      "content_type": "application/pdf",
      "document_type_name": "Certificate of Incorporation",
      "classification": "entity_private",
      "uploaded_by_email": "api.user@example.com",
      "created_at": "2026-01-15T10:30:00Z",
      "expiry_date": "2027-01-31"
    }
  ]
}

Get Document Download URL

Generate a short-lived pre-signed URL (valid 15 minutes) for downloading an entity document. The URL is safe to pass directly to a browser or file download client.

GET /api/v1/entities/{entity_id}/documents/{document_id}/download/

GET /api/v2/entities/{entity_id}/documents/{document_id}/download/

Get Download URL

curl "https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/documents/770f0622-g49d-63f6-c938-668877662222/download/" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.kycgenie.com/api/v2/entities/550e8400-e29b-41d4-a716-446655440000/documents/770f0622-g49d-63f6-c938-668877662222/download/" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

entity_id = "550e8400-e29b-41d4-a716-446655440000"
document_id = "770f0622-g49d-63f6-c938-668877662222"

result = requests.get(
    f"https://api.kycgenie.com/api/v1/entities/{entity_id}/documents/{document_id}/download/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
).json()

# Use the URL directly - valid for 15 minutes
print(result["download_url"])
print(f"Expires: {result['expires_at']}")

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

result = client.entities.get_document_download_url(
    entity_id="550e8400-e29b-41d4-a716-446655440000",
    document_id="770f0622-g49d-63f6-c938-668877662222",
)
print(result.download_url)  # valid for 15 minutes

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const documentId = '770f0622-g49d-63f6-c938-668877662222';

const result = await fetch(
  `https://api.kycgenie.com/api/v1/entities/${entityId}/documents/${documentId}/download/`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

// result.download_url is valid for 15 minutes
window.location.href = result.download_url;

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const documentId = '770f0622-g49d-63f6-c938-668877662222';

const result = await fetch(
  `https://api.kycgenie.com/api/v2/entities/${entityId}/documents/${documentId}/download/`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

window.location.href = result.download_url;

Response (200 OK)

{
  "download_url": "https://app.kycgenie.com/api/v1/files/dl_B7c9d2e3f4a5b6c7/",
  "expires_at": "2026-01-27T15:30:00+00:00",
  "filename": "certificate_of_incorporation.pdf",
  "content_type": "application/pdf",
  "size": 1048576
}

Delete Entity Document

DELETE /api/v1/entities/{entity_id}/documents/{document_id}/

DELETE /api/v2/entities/{entity_id}/documents/{document_id}/

Returns 204 No Content on success.

Delete Document

curl -X DELETE https://api.kycgenie.com/api/v1/entities/{entity_id}/documents/{document_id}/ \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X DELETE https://api.kycgenie.com/api/v2/entities/{entity_id}/documents/{document_id}/ \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.delete(
    f"https://api.kycgenie.com/api/v1/entities/{entity_id}/documents/{document_id}/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
# 204 No Content on success

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

client.entities.delete_document(
    entity_id="550e8400-e29b-41d4-a716-446655440000",
    document_id="770f0622-g49d-63f6-c938-668877662222",
)
# Returns None on success (204 No Content)

await fetch(
  `https://api.kycgenie.com/api/v1/entities/${entityId}/documents/${documentId}/`,
  { method: 'DELETE', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
// 204 No Content

await fetch(
  `https://api.kycgenie.com/api/v2/entities/${entityId}/documents/${documentId}/`,
  { method: 'DELETE', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

Entity Subtypes

The entity_subtype field is a free-text string used for business classification. The values below are commonly used conventions - use the Value column in your API requests.

Value	Description	Category
`LLC`	Limited Liability Company	Corporate
`Corporation`	Corporation	Corporate
`Private Limited Company`	Private Limited Company (Ltd.)	Corporate
`Public Limited Company`	Public Limited Company (PLC)	Corporate
`Sole Proprietorship`	Sole Proprietorship	Corporate
`Fund`	Investment Fund	Investment
`Hedge Fund`	Hedge Fund	Investment
`Private Equity Fund`	Private Equity Fund	Investment
`Mutual Fund`	Mutual Fund	Investment
`SPC`	Segregated Portfolio Company	Investment
`SICAV`	SICAV	Investment
`Unit Trust`	Unit Trust	Investment
`General Partnership`	General Partnership	Partnership
`Limited Partnership`	Limited Partnership (LP)	Partnership
`Limited Liability Partnership`	Limited Liability Partnership (LLP)	Partnership
`Trust`	Trust	Trust
`Investment Trust`	Investment Trust	Trust
`Family Trust`	Family Trust	Trust
`Holding Company`	Holding Company	Specialized
`Special Purpose Vehicle`	Special Purpose Vehicle (SPV)	Specialized
`Joint Venture`	Joint Venture	Specialized
`Fund Administrator`	Fund Administrator	Service Provider
`Service Provider`	Service Provider	Service Provider
`Financial Institution`	Financial Institution	Financial
`Bank`	Bank	Financial
`Regulator`	Regulatory Authority	Regulatory
`Non-Profit`	Non-Profit Organization	Non-Profit
`Charity`	Charity	Non-Profit
`Government Entity`	Government Entity	Government
`Government Agency`	Government Agency	Government
`Other`	Other	Other

Entity Relationships

Link two entities with a directional role to model your corporate ownership structure, board composition, UBO chains, and more. The typical pattern is from_entity holding a role at to_entity.

POST /api/v1/entities/{entity_id}/relationships/

GET /api/v1/entities/{entity_id}/relationships/

DELETE /api/v1/entities/{entity_id}/relationships/{relationship_id}/

POST /api/v2/entities/{entity_id}/relationships/

GET /api/v2/entities/{entity_id}/relationships/

DELETE /api/v2/entities/{entity_id}/relationships/{relationship_id}/

PATCH /api/v2/entities/{entity_id}/relationships/{relationship_id}/

Relationship Object

Field	Type	Description
`id`	uuid	Unique relationship ID
`from_entity`	object	The entity holding the role - contains `id`, `name`, `entity_type`
`to_entity`	object	The entity the role is held at - same shape as `from_entity`
`role`	string	Machine-readable role value. See Role Values.
`role_label`	string	Human-readable label
`role_title`	string \| null	Optional free-text job title override
`ownership_percentage`	string \| null	Percentage ownership (0–100), returned as a decimal string
`status`	string	`active`, `inactive`, `resigned`, or `deceased`
`created_at`	datetime	ISO 8601 creation timestamp

Role Values

Value	Label	Category
`ultimate_beneficial_owner`	Ultimate Beneficial Owner	Ownership
`beneficial_owner`	Beneficial Owner	Ownership
`shareholder`	Shareholder	Ownership
`partner`	Partner	Ownership
`limited_partner`	Limited Partner	Ownership
`general_partner`	General Partner	Ownership
`member`	Member	Ownership
`CEO`	Chief Executive Officer	C-Suite
`CFO`	Chief Financial Officer	C-Suite
`COO`	Chief Operating Officer	C-Suite
`CTO`	Chief Technology Officer	C-Suite
`CIO`	Chief Investment Officer	C-Suite
`CCO`	Chief Compliance Officer	C-Suite
`CRO`	Chief Risk Officer	C-Suite
`President`	President	C-Suite
`VP`	Vice President	C-Suite
`Chairman`	Chairman	Board
`Director`	Director	Board
`Managing Director`	Managing Director	Board
`Independent Director`	Independent Director	Board
`Non-Executive Director`	Non-Executive Director	Board
`Senior Manager`	Senior Manager	Management
`General Manager`	General Manager	Management
`Portfolio Manager`	Portfolio Manager	Management
`Investment Manager`	Investment Manager	Management
`Fund Manager`	Fund Manager	Management
`Operations Manager`	Operations Manager	Management
`Head of Client Services`	Head of Client Services	Management
`MLRO`	Money Laundering Reporting Officer	Compliance
`Compliance Officer`	Compliance Officer	Compliance
`Risk Manager`	Risk Manager	Compliance
`Legal Counsel`	Legal Counsel	Compliance
`Secretary`	Secretary	Operational
`Treasurer`	Treasurer	Operational
`Controller`	Controller	Operational
`signatory`	Signatory	Operational
`officer`	Officer	Operational
`pep`	Politically Exposed Person	Special
`key_personnel`	Key Personnel	Special
`fund_personnel`	Fund Personnel	Special
`gp_personnel`	General Partner Personnel	Special
`fund_admin_personnel`	Fund Administrator Personnel	Special
`other`	Other	Other

Add Relationship

curl -X POST https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/relationships/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rel-shareholder-660e8400-550e8400" \
  -d '{
    "from_entity": "660e8400-e29b-41d4-a716-446655440001",
    "to_entity": "550e8400-e29b-41d4-a716-446655440000",
    "role": "shareholder",
    "ownership_percentage": 25,
    "status": "active"
  }'

import requests

entity_id = "550e8400-e29b-41d4-a716-446655440000"
rel = requests.post(
    f"https://api.kycgenie.com/api/v1/entities/{entity_id}/relationships/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": "rel-shareholder-660e8400-550e8400",
    },
    json={
        "from_entity": "660e8400-e29b-41d4-a716-446655440001",
        "to_entity": entity_id,
        "role": "shareholder",
        "ownership_percentage": 25,
        "status": "active",
    },
).json()
print(rel["id"])

from kycgenie import KYCGenie

client = KYCGenie(api_key="YOUR_API_KEY")

# entity_id is auto-derived from from_entity - no need to pass it separately
rel = client.entities.create_relationship(
    from_entity="660e8400-e29b-41d4-a716-446655440001",  # the individual (UBO/director)
    to_entity="550e8400-e29b-41d4-a716-446655440000",    # the company
    role="shareholder",
    ownership_percentage=25,
    status="active",
)
print(rel.id)

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const rel = await fetch(
  `https://api.kycgenie.com/api/v1/entities/${entityId}/relationships/`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'rel-shareholder-660e8400-550e8400',
    },
    body: JSON.stringify({
      from_entity: '660e8400-e29b-41d4-a716-446655440001',
      to_entity: entityId,
      role: 'shareholder',
      ownership_percentage: 25,
      status: 'active',
    }),
  }
).then(r => r.json());

Response (201 Created)

{
  "id": "aa1b2c3d-e4f5-6789-abcd-ef0123456789",
  "from_entity": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Jane Smith",
    "entity_type": "individual"
  },
  "to_entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corp",
    "entity_type": "company"
  },
  "role": "shareholder",
  "role_label": "Shareholder",
  "role_title": null,
  "ownership_percentage": "25.00",
  "status": "active",
  "created_at": "2026-06-11T14:30:00Z"
}

Update Relationship

curl -X PATCH "https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/relationships/aa1b2c3d-e4f5-6789-abcd-ef0123456789/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: patch-rel-aa1b2c3d-20260611" \
  -d '{"ownership_percentage": 30, "status": "active"}'

import requests

entity_id = "550e8400-e29b-41d4-a716-446655440000"
rel_id = "aa1b2c3d-e4f5-6789-abcd-ef0123456789"

updated = requests.patch(
    f"https://api.kycgenie.com/api/v1/entities/{entity_id}/relationships/{rel_id}/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": "patch-rel-aa1b2c3d-20260611",
    },
    json={"ownership_percentage": 30, "status": "active"},
).json()
print(updated["ownership_percentage"])  # "30.00"

import kycgenie

client = kycgenie.KYCGenie(api_key="YOUR_API_KEY")

updated = client.entities.update_relationship(
    entity_id="550e8400-e29b-41d4-a716-446655440000",
    relationship_id="aa1b2c3d-e4f5-6789-abcd-ef0123456789",
    ownership_percentage=30,
    status="active",
)
print(updated.ownership_percentage)  # "30.00"

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const relId = 'aa1b2c3d-e4f5-6789-abcd-ef0123456789';

const updated = await fetch(
  `https://api.kycgenie.com/api/v1/entities/${entityId}/relationships/${relId}/`,
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'patch-rel-aa1b2c3d-20260611',
    },
    body: JSON.stringify({ ownership_percentage: 30, status: 'active' }),
  }
).then(r => r.json());
console.log(updated.ownership_percentage); // "30.00"

Update Response (200 OK)

{
  "id": "aa1b2c3d-e4f5-6789-abcd-ef0123456789",
  "from_entity": { "id": "660e8400-e29b-41d4-a716-446655440001", "name": "Jane Smith", "entity_type": "individual" },
  "to_entity": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Acme Corp", "entity_type": "company" },
  "role": "shareholder",
  "role_label": "Shareholder",
  "role_title": null,
  "ownership_percentage": "30.00",
  "status": "active",
  "created_at": "2026-06-11T14:30:00Z"
}

List Relationships

curl "https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/relationships/" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

entity_id = "550e8400-e29b-41d4-a716-446655440000"
data = requests.get(
    f"https://api.kycgenie.com/api/v1/entities/{entity_id}/relationships/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
).json()

print(f"{data['count']} relationship(s)")
for rel in data["results"]:
    print(f"  {rel['from_entity']['name']} → {rel['role_label']} → {rel['to_entity']['name']}")

import kycgenie

client = kycgenie.KYCGenie(api_key="YOUR_API_KEY")

data = client.entities.list_relationships(
    entity_id="550e8400-e29b-41d4-a716-446655440000",
)
print(f"{data.count} relationship(s)")
for rel in data.results:
    print(f"{rel.from_entity.name} → {rel.role_label} → {rel.to_entity.name}")

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const data = await fetch(
  `https://api.kycgenie.com/api/v1/entities/${entityId}/relationships/`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

console.log(`${data.count} relationship(s)`);
data.results.forEach(r =>
  console.log(`${r.from_entity.name} → ${r.role_label} → ${r.to_entity.name}`)
);

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const data = await fetch(
  `https://api.kycgenie.com/api/v1/entities/${entityId}/relationships/`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

console.log(`${data.count} relationship(s)`);
data.results.forEach(r =>
  console.log(`${r.from_entity.name} → ${r.role_label} → ${r.to_entity.name}`)
);

List Response (200 OK)

{
  "count": 1,
  "results": [
    {
      "id": "aa1b2c3d-e4f5-6789-abcd-ef0123456789",
      "from_entity": { "id": "660e8400-e29b-41d4-a716-446655440001", "name": "Jane Smith", "entity_type": "individual" },
      "to_entity": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Acme Corp", "entity_type": "company" },
      "role": "shareholder",
      "role_label": "Shareholder",
      "role_title": null,
      "ownership_percentage": "25.00",
      "status": "active",
      "created_at": "2026-06-11T14:30:00Z"
    }
  ]
}

Delete Relationship

curl -X DELETE "https://api.kycgenie.com/api/v1/entities/550e8400-e29b-41d4-a716-446655440000/relationships/aa1b2c3d-e4f5-6789-abcd-ef0123456789/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: delete-rel-aa1b2c3d-20260611"
# 204 No Content on success

import requests

entity_id = "550e8400-e29b-41d4-a716-446655440000"
relationship_id = "aa1b2c3d-e4f5-6789-abcd-ef0123456789"

response = requests.delete(
    f"https://api.kycgenie.com/api/v1/entities/{entity_id}/relationships/{relationship_id}/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": "delete-rel-aa1b2c3d-20260611",
    },
)
# 204 No Content on success

import kycgenie

client = kycgenie.KYCGenie(api_key="YOUR_API_KEY")

client.entities.delete_relationship(
    entity_id="550e8400-e29b-41d4-a716-446655440000",
    relationship_id="aa1b2c3d-e4f5-6789-abcd-ef0123456789",
)
# 204 No Content - no return value

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const relationshipId = 'aa1b2c3d-e4f5-6789-abcd-ef0123456789';

await fetch(
  `https://api.kycgenie.com/api/v1/entities/${entityId}/relationships/${relationshipId}/`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Idempotency-Key': 'delete-rel-aa1b2c3d-20260611',
    },
  }
);
// 204 No Content

Entities API

Entity Object

Common fields (all entities)

Company-only fields

Individual-only fields

Create Entity

Request body

Create Company Entity

Create Individual Entity

Response (201 Created)

List Entities

Query parameters

Response

Response

List Entities

Response

Response

Retrieve Entity

Query parameters

Retrieve Entity

Response (200 OK) Company Individual

Update Entity

Response (200 OK)

Update Entity

Response (200 OK)

Delete Entity

Response behaviour

Delete Entity

Response - Archived (200 OK)

Response - Clean Delete (200 OK)

Search Entities

Query parameters

Response

Search Entities

Response (200 OK)

Batch Create Entities

Request body

Response fields

Batch Create Entities

Response (200 OK)

Entity Documents

Upload Entity Document

Request body (multipart/form-data)

Upload Document

List Entity Documents

List Documents

Response (200 OK)

Response (200 OK)

Get Document Download URL

Get Download URL

Response (200 OK)

Delete Entity Document

Delete Document

Entity Subtypes

Entity Relationships

Relationship Object

Role Values

Add Relationship

Response (201 Created)

Update Relationship

Update Response (200 OK)

List Relationships

List Response (200 OK)

Delete Relationship

Response (200 OK)