Documentation
kompliant.com

Starting a Business Application

Suggest Edits

This integration pattern guides you through the process of creating a business application and adding all required components using the Kompliant API.

📘

Note:

Depending on the configuration, additional information may be required to complete a Business Application, including but not limited to:

  • Location information
  • Issued Identifiers information
  • Sales information

You can check what fields are missing from your application by using workflow.canComplete

Overview

A business application workflow in Kompliant involves the following steps:

  1. Create a workflow of type BUSINESS_APPLICATION
  2. Add business details
  3. Add control prong (business controller)
  4. Add ownership prongs (ultimate beneficial owners)
  5. Add bank account information
  6. Generate completion URL (optional)

This guide walks you through the sequence of API calls needed to complete these steps.

Step 1: Create the Business Application Workflow

The first step is to create a workflow of type BUSINESS_APPLICATION. This will automatically create a Subject Record for you. The Account ID is supplied to you when you receive your credentials.

POST https://api.kompliant.com/workflow.create

Request Body:

{
  "account_id": "your_account_id",
  "workflow": {
    "type": "BUSINESS_APPLICATION",
    "details": {
      "business_application_details": {
        "applying_user": {
          "email": "[email protected]",
          "first_name": "John",
          "last_name": "Doe"
        }
      }
    }
  }
}

📘

Note

You don't need to create a Subject Record separately. The workflow.create method will automatically create one of the appropriate type for you. The response includes both workflow_id and subject_record_id which you'll need for subsequent calls.

For more details on this API, see workflow.create.

Step 2: Add Business Information

Once you have the subject record ID, you can add business details:

POST https://api.kompliant.com/business.create

Request Body:

{
  "subject_record_id": "sr_from_previous_step",
  "business": {
    "legal_name": "Example Business LLC",
    "operating_name": "Example Business",
    "registration_type": "LLC_PRIVATE",
    "tax_id": "123456789",
    "phone_number": "(555) 123-4567",
    "industry_category_codes": [
      {
        "type": "MCC",
        "code": "5734",
        "details": {
          "mcc_details": {
            "card_brand": "MASTERCARD"
          }
        }
      }
    ],
    "addresses": [
      {
        "type": "LEGAL",
        "line1": "123 Business Street",
        "city": "Businessville",
        "state": "CA",
        "postal_code": "90210",
        "country": "US"
      }
    ]
  }
}

For more details on this API, see business.create.

Step 3: Add the Controlling Beneficial Owner

Next, you'll need to add the person under the control prong of ultimate beneficial ownership. This is a single individual with significant responsibility to control, manage or direct the business. For more information about the definitions of ultimate beneficial ownership, you can review the FFIEC BSA/AML Manual.

This is a two-step process:

3.1 Create the Person

POST https://api.kompliant.com/person.create

Request Body:

{
  "subject_record_id": "sr_from_previous_step",
  "person": {
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1980-01-15",
    "tax_id": "123456789",
    "citizenship": "US",
    "phone_number": "(555) 987-6543",
    "addresses": [
      {
        "type": "PRIMARY_RESIDENCE",
        "line1": "456 Controller Lane",
        "city": "Businessville",
        "state": "CA",
        "postal_code": "90210",
        "country": "US"
      }
    ]
  }
}

For more details on this API, see person.create.

3.2 Associate Person as Control Prong

POST https://api.kompliant.com/business.addOwner

Request Body:

{
  "business_id": "b_from_business_create",
  "business_owner": {
    "person_id": "p_from_person_create",
    "ownership_type": "CONTROL_PRONG",
    "business_person_position": "PRESIDENT"
  }
}

For more details on this API, see business.addOwner.

Step 4: Add Additional Beneficial Owners (Ownership Prong)

For each person who owns a significant percentage of the business (typically 25% or more share of ownership), repeat the following steps:

Note: If the controlling UBO (added in Step 3) is also owns a significant share of the business, you do not need to add them again under the ownership prong. Simply ensure their ownership percentage is properly recorded when adding them under the control prong.

4.1 Create the Person

POST https://api.kompliant.com/person.create

Request Body:

{
  "subject_record_id": "sr_from_workflow_create",
  "person": {
    "email": "[email protected]",
    "first_name": "Michael",
    "last_name": "Johnson",
    "date_of_birth": "1975-05-20",
    "tax_id": "987654321",
    "citizenship": "US",
    "phone_number": "(555) 456-7890",
    "addresses": [
      {
        "type": "PRIMARY_RESIDENCE",
        "line1": "789 Owner Avenue",
        "city": "Businessville",
        "state": "CA",
        "postal_code": "90210",
        "country": "US"
      }
    ]
  }
}

For more details on this API, see person.create.

4.2 Associate Person as Ownership Prong

POST https://api.kompliant.com/business.addOwner

Request Body:

{
  "business_id": "b_from_business_create",
  "business_owner": {
    "person_id": "p_from_person_create",
    "ownership_type": "OWNERSHIP_PRONG",
    "ownership_percentage": 51,
    "ownership_year_month": "2020-01",
    "business_person_position": "OWNER"
  }
}

⚠️

Important

The sum of ownership percentages for all beneficial owners cannot exceed 100%. Make sure to include all persons with significant ownership (usually 25% or more).

For more details on this API, see business.addOwner.

Step 5: Add Bank Accounts

For each bank account associated with the business:

5.1 Create the Bank Account

POST https://api.kompliant.com/bankAccount.create

Request Body:

{
  "subject_record_id": "sr_from_workflow_create",
  "bank_account": {
    "bank_account_ownership_type": "BUSINESS",
    "bank_account_type": "CHECKING",
    "bank_routing_number": "021000021",
    "bank_account_number": "1234567890123",
    "bank_name": "Example Bank"
  }
}

For more details on this API, see bankAccount.create.

5.2 Associate Bank Account with Business

POST https://api.kompliant.com/business.addBankAccount

Request Body:

{
  "business_id": "b_from_business_create",
  "business_bank_account": {
    "bank_account_id": "ba_from_bank_account_create",
    "bank_account_purposes": ["PRIMARY", "FEES", "SETTLEMENT"]
  }
}

For more details on this API, see business.addBankAccount.

Step 6: Generate Completion URL (Optional)

After populating the application with your available data, you can provide applicants with a URL to complete, review, or modify the application through Kompliant's web interface.

Use Cases

This feature is useful when you:

  • Have partial information and need the applicant to fill in missing details
  • Want the applicant to review and confirm all provided information
  • Need the applicant to complete additional steps like document signing

Generating the URL

Once you have created the workflow, you can direct applicants to:

https://apply.kompliant.com/login?application_id=<workflow_id>

Replace <workflow_id> with the ID returned from your workflow.create call.

Example:

https://apply.kompliant.com/login?application_id=wf_abc123def456

Applicant Authentication Process

  1. Access: The applicant visits the URL
  2. Email Verification: The system displays a masked version of the email address from the applying_user.email field in your workflow.create call
  3. Confirmation: The applicant confirms this is their email address
  4. Code Delivery: A verification code is sent to that email address
  5. Authentication: The applicant enters the code to access the application

What Applicants Can Do

Once authenticated, applicants can:

  • View all information you've provided via the API
  • Edit or modify any of the pre-populated data
  • Complete any missing required fields
  • Review the entire application before submission

⚠️

Important

The page at the URL uses the email address specified in the applying_user.email field from your workflow.create call for authentication. Ensure this email belongs to the person who should complete the application.

Complete Integration Flow

Below is a flowchart of the complete integration pattern:

workflow.create
    ↓
business.create
    ↓
person.create (Control Prong)
    ↓
business.addOwner (Control Prong)
    ↓
person.create (Ownership Prong 1)
    ↓
business.addOwner (Ownership Prong 1)
    ↓
[Repeat for additional owners if needed]
    ↓
bankAccount.create
    ↓
business.addBankAccount
    ↓
[Repeat for additional bank accounts if needed]
    ↓
Generate completion URL (optional)

Best Practices

  1. Error Handling: Implement proper error handling for each API call, particularly checking for the ENTITY_NOT_FOUND error which might indicate an issue with IDs from previous steps.

  2. ID Management: Maintain a mapping of all IDs created during the workflow (workflow_id, subject_record_id, business_id, person_ids, bank_account_ids) to facilitate updates or modifications.

  3. Verification: Before finalizing the application, use the list APIs (business.listOwners, business.listBankAccounts) to verify all components have been properly added.

  4. Sensitive Data: Be careful when handling sensitive data like tax IDs and bank account numbers. The API provides masking options through the show_sensitive_data parameter in get and list operations.

  5. Completion URL: When using the completion URL feature, ensure the applying_user.email in your workflow.create call belongs to the person who should complete the application, as this email is used for authentication.

Updated 3 months ago