Application Related Entities

Overview

The Application Related Entities API allows you to create and manage various entity types associated with an application, such as directors, shareholders, key employees, subsidiaries, and other related persons or companies. This endpoint supports both company and person entities with different relationship types as defined by the application configuration.

Authentication

This endpoint requires authentication. See API Authentication for detailed requirements and how to obtain credentials.

Create Related Entity

Endpoint

POST /api/applications/:id/related-entities

Request Body

Interface Definitions

interface CreateRelatedEntityDTO {
   _id?: string;
   selectedType: SupplierSelectedTypeOfStep;
   fields: RelatedEntityFieldDTO;
   relatedEntityType: ApplicationEntityType;
}

interface RelatedEntityFieldDTO {
   personRelatedEntitiesInformation?: PersonRelatedEntityDTO;
   companyRelatedEntitiesInformation?: CompanyRelatedEntityDTO;
}

// Person and Company DTOs reference the same structures as Submit Application API
// See Submit Application API documentation for complete field definitions
interface PersonRelatedEntityDTO extends UpsertPersonDTO {
   extra?: Record<string, any>;
}

interface CompanyRelatedEntityDTO extends UpsertCompanyDTO {
   extra?: Record<string, any>;
}

enum SupplierSelectedTypeOfStep {
   PERSON = 'person',
   COMPANY = 'company',
}

enum ApplicationEntityType {
   MAIN_PERSON = 'main_person',
   MAIN_COMPANY = 'main_company',
   LICENSE_ENTITY = 'license_entity',
   AUTHORIZED_REPRESENTATIVE = 'authorized_representative',
   PAYMENT_AGENT = 'payment_agent',
   UBO = 'ubo',
   CEO = 'ceo',
   AUTHORIZED_PERSON = 'authorizedPerson',
   SUBSIDIARY = 'subsidiary',
   CSP = 'csp',
   DIRECTOR = 'director',
   SHAREHOLDER = 'shareholder',
   KEY_EMPLOYEES = 'keyEmployees',
   SECRETARIES = 'secretaries',
   COUNTERPARTIES = 'counterparties',
}

Field Descriptions

• selectedType (required): Type of entity being created - either 'person' or 'company'
• relatedEntityType (required): Specific relationship type of the entity to the application
• fields (required): Container for entity information based on the selected type
• _id (optional): Unique identifier for updating existing entities

Entity Type Requirements

For Person Entities (selectedType: 'person')

• fields.personRelatedEntitiesInformation is required
• fields.companyRelatedEntitiesInformation should be omitted
• Person data follows the same structure as Submit Application API UpsertPersonDTO

For Company Entities (selectedType: 'company')

• fields.companyRelatedEntitiesInformation is required
• fields.personRelatedEntitiesInformation should be omitted
• Company data follows the same structure as Submit Application API UpsertCompanyDTO

Request Examples

Create Director (Person Entity)

{
   "selectedType": "person",
   "relatedEntityType": "director",
   "fields": {
      "personRelatedEntitiesInformation": {
         "firstName": "John",
         "lastName": "Smith",
         "email": "john.smith@example.com",
         "telephone": "+1234567890",
         "nationality": "US",
         "dob": "1980-05-15T00:00:00.000Z",
         "address": {
            "addressLine1": "123 Director Street",
            "city": "New York",
            "postCode": "10001",
            "country": "US"
         },
         "identificationType": "passport",
         "identificationNumber": "P987654321",
         "extra": {
            "appointmentDate": "2023-01-01",
            "boardCommittees": ["audit", "risk"]
         }
      }
   }
}

Create Subsidiary (Company Entity)

{
   "selectedType": "company",
   "relatedEntityType": "subsidiary",
   "fields": {
      "companyRelatedEntitiesInformation": {
         "name": "Subsidiary Corp Ltd",
         "tradingName": "SubCorp",
         "address": {
            "addressLine1": "456 Business Ave",
            "city": "London",
            "postCode": "SW1A 1AA",
            "country": "GB"
         },
         "companyType": "subsidiary",
         "dateOfIncorporation": "2022-03-15T00:00:00.000Z",
         "registrationNumber": "SUB123456",
         "countryOfIncorporation": "GB",
         "extra": {
            "ownershipPercentage": 75,
            "operationalStatus": "active"
         }
      }
   }
}

Create Shareholder (Person Entity)

{
   "selectedType": "person",
   "relatedEntityType": "shareholder",
   "fields": {
      "personRelatedEntitiesInformation": {
         "firstName": "Maria",
         "lastName": "Rodriguez",
         "email": "maria.rodriguez@example.com",
         "nationality": "ES",
         "dob": "1975-09-20T00:00:00.000Z",
         "address": {
            "addressLine1": "789 Shareholder Road",
            "city": "Madrid",
            "postCode": "28001",
            "country": "ES"
         },
         "identificationType": "nationalId",
         "identificationNumber": "12345678Z",
         "extra": {
            "shareholdingPercentage": 25.5,
            "shareClass": "ordinary",
            "votingRights": true
         }
      }
   }
}

Response Structure

Success Response

{
   "statusCode": 201,
   "message": "Related entity created successfully",
   "data": {
      "entityId": "60d5ecb54f3d2b001f8b4569",
      "relatedEntityType": "director",
      "selectedType": "person"
   }
}

Error Response

{
   "statusCode": 400,
   "message": "Validation failed",
   "errors": [
      {
         "field": "fields.personRelatedEntitiesInformation.firstName",
         "message": "First name is required"
      },
      {
         "field": "relatedEntityType",
         "message": "Invalid entity type for this application"
      }
   ]
}

Delete Related Entity

Endpoint

DELETE /api/applications/:id/related-entities

Request Body

Interface Definitions

interface DeleteApplicationRelatedEntityDTO {
   entityId: string;
   relatedEntityType: ApplicationEntityType;
}

Field Descriptions

• entityId (required): Unique identifier of the entity to be deleted
• relatedEntityType (required): Type of the related entity being deleted

Request Example

{
   "entityId": "60d5ecb54f3d2b001f8b4569",
   "relatedEntityType": "director"
}

Response Structure

Success Response

The API returns a 200 OK status code when the entity is successfully deleted. No response body is returned.

HTTP/1.1 200 OK

Error Response

{
   "statusCode": 400,
   "message": "Entity deletion validation failed",
   "errors": [
      {
         "field": "entityId",
         "message": "Invalid entity ID format"
      },
      {
         "field": "relatedEntityType",
         "message": "Entity type mismatch"
      }
   ]
}

Entity Types and Use Cases

Corporate Structure Entities

Directors (director)

• Type: Person
• Purpose: Board members with governance responsibilities
• Common Extra Fields: appointmentDate, boardCommittees, directorType

Shareholders (shareholder)

• Type: Person or Company
• Purpose: Equity holders in the company
• Common Extra Fields: shareholdingPercentage, shareClass, votingRights

Key Employees (keyEmployees)

• Type: Person
• Purpose: Senior management and key operational staff
• Common Extra Fields: position, startDate, reportingLine

Regulatory and Compliance Entities

Ultimate Beneficial Owners (ubo)

• Type: Person
• Purpose: Individuals with significant control or ownership
• Common Extra Fields: ownershipPercentage, controlType, sourceOfWealth

CEO (ceo)

• Type: Person
• Purpose: Chief Executive Officer
• Common Extra Fields: appointmentDate, previousRole, qualifications

Authorized Representatives (authorized_representative)

• Type: Person
• Purpose: Individuals authorized to act on behalf of the company
• Common Extra Fields: authorityScope, limitOfAuthority, designation

Business Structure Entities

Subsidiaries (subsidiary)

• Type: Company
• Purpose: Companies owned or controlled by the main entity
• Common Extra Fields: ownershipPercentage, operationalStatus, jurisdiction

Corporate Service Providers (csp)

• Type: Company
• Purpose: External service providers for corporate functions
• Common Extra Fields: serviceType, contractDate, licenseNumber

Operational Entities

Secretaries (secretaries)

• Type: Person
• Purpose: Company secretaries handling administrative functions
• Common Extra Fields: qualifications, appointmentDate, responsibilities

Counterparties (counterparties)

• Type: Person or Company
• Purpose: Business partners, clients, or transaction counterparts
• Common Extra Fields: relationshipType, contractValue, riskRating

Field Validation Requirements

Entity Creation Validation

• selectedType must match the entity data provided in fields
• relatedEntityType must be valid for the application type and configuration
• Person entities require firstName and lastName as mandatory fields
• Company entities require name as a mandatory field
• All field validations from Submit Application API apply to the respective entity types

Entity Deletion Validation

• entityId must be a valid MongoDB ObjectId
• Entity must exist and belong to the specified application
• relatedEntityType must match the entity being deleted
• Cannot delete entities that are required by the application configuration

Data Structure References

Person Entity Fields

For complete field definitions and validation rules for person entities, refer to the UpsertPersonDTO interface in the Submit Application API documentation.

Company Entity Fields

For complete field definitions and validation rules for company entities, refer to the UpsertCompanyDTO interface in the Submit Application API documentation.

Usage Guidelines

Entity Creation Workflow

1. Determine Entity Type: Based on your application requirements, identify which related entities need to be created
2. Prepare Entity Data: Structure the data according to the appropriate DTO (Person or Company)
3. Set Relationship Type: Choose the correct relatedEntityType based on the entity's role
4. Include Extra Information: Use the extra field for additional relationship-specific data
5. Submit Request: Send the POST request with the complete entity information

Entity Management Best Practices

• Consistent Data: Ensure entity data aligns with the main application information
• Required Entities: Check application configuration for mandatory related entities
• Validation: Validate all required fields before submission
• Documentation: Maintain clear records of entity relationships and roles

Error Handling

async function createRelatedEntity(applicationId, entityData) {
   try {
      const response = await fetch(
         `/api/applications/${applicationId}/related-entities`,
         {
            method: 'POST',
            headers: {
               'Content-Type': 'application/json',
               Authorization: 'Bearer ' + authToken,
            },
            body: JSON.stringify(entityData),
         }
      );

      if (response.ok) {
         const result = await response.json();
         console.log('Entity created:', result.data.entityId);
         return result;
      } else {
         const errorData = await response.json();
         throw new Error(errorData.message || 'Entity creation failed');
      }
   } catch (error) {
      console.error('Creation error:', error);
      throw error;
   }
}

async function deleteRelatedEntity(applicationId, deleteData) {
   try {
      const response = await fetch(
         `/api/applications/${applicationId}/related-entities`,
         {
            method: 'DELETE',
            headers: {
               'Content-Type': 'application/json',
               Authorization: 'Bearer ' + authToken,
            },
            body: JSON.stringify(deleteData),
         }
      );

      if (response.ok) {
         console.log('Entity deleted successfully');
         return { success: true };
      } else {
         const errorData = await response.json();
         throw new Error(errorData.message || 'Entity deletion failed');
      }
   } catch (error) {
      console.error('Deletion error:', error);
      throw error;
   }
}

Integration Examples

Complete Entity Management Flow

// Create multiple related entities for a company application
async function setupCompanyEntities(applicationId) {
   const entities = [
      // Create CEO
      {
         selectedType: 'person',
         relatedEntityType: 'ceo',
         fields: {
            personRelatedEntitiesInformation: {
               firstName: 'John',
               lastName: 'CEO',
               email: 'ceo@company.com',
               // ... other required fields
            },
         },
      },
      // Create Director
      {
         selectedType: 'person',
         relatedEntityType: 'director',
         fields: {
            personRelatedEntitiesInformation: {
               firstName: 'Jane',
               lastName: 'Director',
               email: 'director@company.com',
               // ... other required fields
            },
         },
      },
      // Create Subsidiary
      {
         selectedType: 'company',
         relatedEntityType: 'subsidiary',
         fields: {
            companyRelatedEntitiesInformation: {
               name: 'Subsidiary Company Ltd',
               registrationNumber: 'SUB123',
               // ... other required fields
            },
         },
      },
   ];

   const results = [];
   for (const entityData of entities) {
      try {
         const result = await createRelatedEntity(applicationId, entityData);
         results.push(result);
      } catch (error) {
         console.error(
            `Failed to create ${entityData.relatedEntityType}:`,
            error
         );
      }
   }

   return results;
}

Related APIs

• Use Submit Application API for field structure references and validation rules
• Use Get Application Configuration API to determine required entity types
• Use Application Files API to upload supporting documents for entities

Integration Tip

The extra field in entity data can be used to store relationship-specific information that doesn't fit standard person or company fields, such as ownership percentages, appointment dates, or authority limits.

Important

Entity types and requirements may vary based on your application configuration. Always verify required entity types through the Get Configuration API before creating entities.

Data Structure Reference

Person and Company entity fields follow the same structure as the Submit Application API. Refer to that documentation for complete field definitions and validation requirements.