Entities API

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

Two Entity Types

Companies: Legal entities such as corporations, LLCs and partnerships
Individuals: Natural persons such as directors, controllers and beneficiaries

Entity Object

The entity object represents a natural person (individual) or legal entity (company).

Core Attributes

Field Type Description
id uuid Unique identifier
name string Auto-calculated: For companies = trading_name or legal_name. For individuals = first_name + middle_name + last_name. Encrypted at rest.
entity_type string Must be company or individual
entity_subtype string Business classification: LLC, Trust, Fund, Service Provider, etc. See Entity Subtypes
is_primary boolean Determines whether this is the primary subject entity for compliance assessments, such as questionnaires.
created_at datetime Creation timestamp
updated_at datetime Last update timestamp

Note: Any entities created as non-primary(is_primary=false) are not visible in the Company and Individual tables in the UI dashboards by default. Non-primary entities are typically related entities of primary entities and should not be the subject of direct compliance assessments.

Company-Specific Fields

Field Type Description
legal_name string Official legal name of the company
trading_name string Trading name or DBA
registration_number string Company registration number
jurisdiction string Country of incorporation (ISO 3166-1 alpha-2 code, e.g., "GB", "US")
incorporation_date date Date of incorporation (YYYY-MM-DD)

Individual-Specific Fields

Field Type Description
title string Title (Mr, Mrs, Dr, etc.) - Encrypted
first_name string First/given name
middle_name string Middle name
last_name string Last/family name
gender string Gender: male or female
date_of_birth date Date of birth (YYYY-MM-DD)
country_of_birth string Country of birth (ISO 3166-1 alpha-2 code, e.g., "GB", "US")
nationality string Nationality (ISO 3166-1 alpha-2 code, e.g., "GB", "US")
national_id_number string National ID number
tax_id string Tax identification number
ssn string Social Security Number (US)
social_insurance_number string Social Insurance Number (Canada)

Contact & Address Fields (Both Types)

Field Type Description
email string Email address
phone string Phone number
address_line_1 string Street address
address_line_2 string Apartment, suite, unit
address_city string City
address_state string State/province
address_postal_code string Postal/ZIP code
address_country string Country (ISO 3166-1 alpha-2 code, e.g., "GB", "US")

Risk & Compliance Fields

Field Type Description
risk_score decimal Overall risk score (0.00 - 100.00)
last_kyc_check_date date Date of last KYC verification
next_kyc_check_date date Scheduled next KYC refresh

Computed Fields (API Response Only)

Field Type Description
screening_status string screened if entity has AML/sanctions screening, not_screened otherwise. Returned by both List and Get endpoints.
response_count integer Number of questionnaire responses where this entity is the subject. Returned by both List and Get endpoints.
risk_profiles_count integer Number of risk profiles associated with this entity as a result of screening. Returned by both List and Get endpoints.

Create Entity

Creates a new entity (company or individual) in your registry.

POST /api/v1/entities/
Idempotency

Entity creation supports idempotency via the Idempotency-Key header. If you retry the same request with the same key, you'll receive the existing entity instead of creating a duplicate. This is essential for handling network failures and retries safely. Keys are scoped to your tenant and expire after 24 hours.

Request Body (Company)

Parameter Type Required Description
entity_type string Yes Must be company
legal_name string Yes* Official legal name. *Either legal_name or trading_name is required
trading_name string Yes* Trading name/DBA. *Either legal_name or trading_name is required
entity_subtype string No Business classification (see Entity Subtypes)
jurisdiction string No ISO 3166-1 alpha-2 code (e.g., "GB", "US")
incorporation_date date No YYYY-MM-DD format
registration_number string No Company registration number
address_* string No Structured address fields (line1, line2, city, state, postal_code, country)
is_primary boolean No Default: true

Request Body (Individual)

Parameter Type Required Description
entity_type string Yes Must be individual
first_name string Yes First/given name (required for individuals)
middle_name string No Middle name
last_name string Yes Last/family name (required for individuals)
title string No Title (Mr, Mrs, Dr, etc.)
gender string No male or female
date_of_birth date No YYYY-MM-DD format
nationality string No Nationality/citizenship (ISO 3166-1 alpha-2 code, e.g., "GB", "US")
country_of_birth string No Country of birth (ISO 3166-1 alpha-2 code, e.g., "GB", "US")
address_* string No Structured address fields (line1, line2, city, state, postal_code, country)

API Response

Returns the created entity with 201 Created status.

Example Response - Company Entity

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Financial Services LLC",
  "entity_type": "company",
  "is_primary": true,
  "created_at": "2026-01-21T10:30:00Z"
}

Example Response - Individual Entity

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "John Michael Smith",
  "entity_type": "individual",
  "is_primary": true,
  "created_at": "2026-01-21T10:35:00Z"
}

Batch Create Entities

Create up to 200 entities in a single API request with automatic duplicate detection and validation.

POST /api/v1/entities/batch/
Performance & Limits
  • Max per request: 200 entities
  • Daily limit: 1,000 entities per tenant
  • Processing: Synchronous (immediate response)
  • Duplicate detection: 95% similarity threshold

Features

  • Automatic deduplication: Fuzzy matching prevents duplicate entities (95% similarity threshold)
  • Partial success: Valid entities are created even if some fail validation
  • Daily quota tracking: Remaining quota returned in each response
  • Mixed types: Create companies and individuals in the same batch
  • Validation: Same rules as single entity creation

Request Body

Parameter Type Required Description
entities array Yes Array of entity objects (max 200). Each object follows the same schema as single entity creation.
skip_duplicates boolean No Skip entities that match existing entities (≥95% similarity). Default: true

Request Example

{
  "entities": [
    {
      "entity_type": "individual",
      "first_name": "John",
      "last_name": "Smith",
      "date_of_birth": "1980-05-15",
      "nationality": "GB",
      "country_of_birth": "GB",
      "national_id_number": "784195625715172",
      "tax_id": "AB123456C",
      "address_line_1": "123 Main Street",
      "address_city": "London",
      "address_postal_code": "SW1A 1AA",
      "address_country": "GB"
    },
    {
      "entity_type": "company",
      "legal_name": "Acme Corporation Ltd",
      "trading_name": "Acme Corp",
      "entity_subtype": "Private Limited Company",
      "jurisdiction": "GB",
      "registration_number": "12345678",
      "address_line_1": "456 Business Park",
      "address_city": "Manchester",
      "address_postal_code": "M1 1AA",
      "address_country": "GB"
    }
  ],
  "skip_duplicates": true
}

API Response

Returns a detailed summary with 201 Created status.

{
  "summary": {
    "requested": 150,
    "created": 145,
    "skipped": 3,
    "failed": 2,
    "remaining_daily_quota": 855
  },
  "created_entities": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "John Smith",
      "entity_type": "individual"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Acme Corp",
      "entity_type": "company"
    }
  ],
  "skipped": [
    {
      "index": 5,
      "reason": "duplicate",
      "existing_entity_id": "770e8400-e29b-41d4-a716-446655440002",
      "matching_name": "John Smith",
      "similarity_score": 98.5
    }
  ],
  "errors": [
    {
      "index": 10,
      "entity": {
        "entity_type": "individual",
        "first_name": "Jane"
      },
      "errors": {
        "last_name": ["This field is required for individual entities"]
      }
    }
  ]
}

Response Fields

Field Type Description
summary.requested integer Total entities in request
summary.created integer Successfully created entities
summary.skipped integer Entities skipped due to duplicates (when skip_duplicates=true)
summary.failed integer Entities that failed validation
summary.remaining_daily_quota integer Remaining entities you can create today (resets daily at midnight UTC)
created_entities array List of successfully created entities with IDs
skipped array List of skipped entities with duplicate match details
errors array List of failed entities with validation errors

Error Responses

429 Too Many Requests - Daily Limit Exceeded

{
  "error": "Daily entity creation limit exceeded",
  "errors": {
    "limit": ["Maximum 1000 entities per day. Try again tomorrow."]
  }
}

429 Too Many Requests - Quota Insufficient

{
  "error": "Daily quota insufficient",
  "errors": {
    "limit": ["Requested 250 but only 150 remaining today"]
  }
}

400 Bad Request - Too Many Entities

{
  "error": "Batch size exceeds maximum",
  "errors": {
    "entities": ["Maximum 200 entities per batch request"]
  }
}
Deduplication Algorithm

The system uses fuzzy matching with a 95% similarity threshold. Entities are compared only within the same entity_type. The matching algorithm:

  • First checks for exact name matches (case-insensitive)
  • Compares against existing tenant entities, not just the current batch
  • If a match is found, the entity is skipped and the existing entity ID is returned

List Entities

Retrieves a paginated list of all entities in your tenant registry.

GET /api/v1/entities/

Query Parameters

Parameter Type Description
entity_type string Filter by type: company or individual
is_primary boolean Filter by primary status (true/false)
search string Search in name field
page integer Page number (default: 1)
page_size integer Results per page (default: 20, max: 100)

API Response

Returns a paginated list of entities with computed fields.

{
  "count": 42,
  "next": "https://api.kycgenie.com/api/v1/entities/?page=2",
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Financial Services LLC",
      "entity_type": "company",
      "is_primary": true,
      "screening_status": "screened",
      "response_count": 3,
      "risk_profiles_count": 1,
      "created_at": "2026-01-15T10:30:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "John Michael Smith",
      "entity_type": "individual",
      "is_primary": false,
      "screening_status": "approved",
      "response_count": 1,
      "risk_profiles_count": 0,
      "created_at": "2026-01-18T14:22:00Z"
    }
  ]
}

Get Entity

Retrieves detailed information about a specific entity.

GET /api/v1/entities/{id}/

Path Parameters

Parameter Type Description
id uuid The unique identifier of the entity

API Response

Returns the full entity object with all computed fields (screening_status, response_count, risk_profiles_count).

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Financial Services LLC",
  "entity_type": "company",
  "entity_subtype": "llc",
  "legal_name": "Acme Financial Services LLC",
  "trading_name": "Acme FinServ",
  "registration_number": "123456789",
  "jurisdiction": "US",
  "incorporation_date": "2020-03-15",
  "nationality": null,
  "date_of_birth": null,
  "address_line_1": "123 Wall Street",
  "address_line_2": "Suite 500",
  "address_city": "New York",
  "address_state": "NY",
  "address_postal_code": "10005",
  "address_country": "US",
  "is_primary": true,
  "screening_status": "screened",
  "response_count": 3,
  "risk_profiles_count": 1,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-20T16:45:00Z"
}

Example Response - Individual Entity

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "John William Smith",
  "entity_type": "individual",
  "entity_subtype": null,
  "title": "Mr",
  "first_name": "John",
  "middle_name": "William",
  "last_name": "Smith",
  "gender": "male",
  "date_of_birth": "1985-06-15",
  "nationality": "GB",
  "country_of_birth": "GB",
  "national_id_number": "784195625715172",
  "tax_id": "AB123456C",
  "ssn": null,
  "social_insurance_number": null,
  "address_line_1": "456 Residential Lane",
  "address_line_2": null,
  "address_city": "Manchester",
  "address_state": null,
  "address_postal_code": "M1 1AA",
  "address_country": "GB",
  "is_primary": true,
  "screening_status": "approved",
  "response_count": 1,
  "risk_profiles_count": 0,
  "created_at": "2026-01-18T14:22:00Z",
  "updated_at": "2026-01-18T14:22:00Z"
}

Update Entity

Updates an existing entity's information. All fields are optional.

PATCH /api/v1/entities/{id}/
Idempotency Required

Include an Idempotency-Key header (16-255 characters) to ensure updates are processed exactly once. Use a unique key per logical update operation.

Request Body

Include only the fields you want to update. Supports all entity fields except id, name and entity_type

Primary Entity Restriction

The is_primary field can be changed from false to true, but cannot be changed from true to false. Once an entity is marked as primary, it must remain primary. This ensures data integrity for assessment workflows.

API Response

Returns a minimal response with 200 OK status containing the updated entity ID, name, type, list of fields that were changed, and timestamp.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Financial Services LLC",
  "entity_type": "company",
  "updated_fields": [
    "trading_name",
    "address_line_1",
    "address_city"
  ],
  "updated_at": "2026-01-21T11:20:00Z"
}

Search Entities

Fuzzy search across entity names using similarity matching. Useful for deduplication and finding similar entities.

GET /api/v1/entities/search/

Query Parameters

Parameter Type Required Description
q string Yes Search query
entity_type string No Filter by company or individual
threshold float No Similarity threshold 0.0-1.0 (default: 0.7)
limit integer No Maximum results (default: 10, max: 50)

API Response

Returns matching entities with similarity scores sorted by relevance.

{
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Financial Services LLC",
      "entity_type": "company",
      "entity_subtype": "llc",
      "similarity_score": 0.95
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "Acme Finance LLC",
      "entity_type": "company",
      "entity_subtype": "llc",
      "similarity_score": 0.82
    },
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "name": "ACME Financial Group",
      "entity_type": "company",
      "entity_subtype": "corporation",
      "similarity_score": 0.78
    }
  ],
  "query": "Acme Financial",
  "count": 3
}

Delete Entity

Deletes an entity from your registry. Only allows deletion if the entity has no associated responses or documents.

DELETE /api/v1/entities/{id}/
Naturally Idempotent

DELETE operations are naturally idempotent and do not require an Idempotency-Key header. Deleting the same entity multiple times will result in the same state (entity not found).

Behavior

Returns a 204 No Content status if deletion succeeds. Returns a 400 Bad Request error if the entity has associated responses or documents.

Dependencies

Entities cannot be deleted if they have associated dependencies such as Responses or Documents. Delete or reassign dependencies before deletion.

API Response

Success Response (204 No Content)

No response body is returned. Check for HTTP status code 204.

Error Response - Entity Has Dependencies (400 Bad Request)

{
  "error": "Entity has dependencies",
  "detail": "Cannot delete entity with 3 response(s) and 5 document(s). Remove associated data first.",
  "response_count": 3,
  "document_count": 5
}

Entity Subtypes

The entity_subtype field provides granular business classification for entities. Use the Value column when making 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
Regulator Regulatory Authority Regulatory
Financial Institution Financial Institution Financial
Bank Bank Financial
Non-Profit Non-Profit Organization Non-Profit
Charity Charity Non-Profit
Government Entity Government Entity Government
Government Agency Government Agency Government
Other Other Other
Optional Field

The entity_subtype field is optional but recommended for better entity classification and reporting.

↑ ↓ to navigate • Enter to select • Esc to close