​
Individual Account Opening

This guide walks you through the process of creating and verifying individual customer accounts using the FinHub API. The individual account opening process involves several steps including customer creation, identity verification, and account activation.

​
Overview

The individual account opening process follows these main steps:

  1. Create an individual customer profile
  2. Verify the customer’s identity (KYC)
  3. Activate the customer’s account
  4. Create financial accounts for the customer

​
Complete Flow Sequence

The following sequence diagram illustrates the complete individual account opening process, including both automated and manual verification paths:

Note: Approximately 90% of KYC verifications are approved automatically through the system’s verification algorithms. The remaining 10% require manual review by compliance officers through the Business Control Panel.

​
Prerequisites

Before starting the individual account opening process, ensure you have:

  • Valid API credentials for the FinHub platform
  • Completed the authentication process
  • Required customer information (personal details, contact information, etc.)
  • Appropriate permissions to create and manage customer accounts

​
Step 1: Create Individual Customer

The first step is to create an individual customer profile with basic information.

​
API Request

POST /api/v2/customer/individual
Content-Type: application/json
Authorization: Bearer {access_token}

​
Request Body

{
  "person": {
    "firstName": {
      "name": "John"
    },
    "lastName": {
      "name": "Doe"
    },
    "email": "john.doe@example.com",
    "password": "SecureP@ssw0rd",
    "nationality": "United States"
  },
  "address": {
    "country": "United States",
    "city": "New York",
    "street": "123 Main Street",
    "postalCode": "10001"
  },
  "contactDetails": {
    "phoneNumber": "+12125551234"
  }
}

​
Response

{
  "id": "cust_12345678",
  "status": "PENDING_VERIFICATION",
  "createdAt": "2025-05-31T09:15:00Z",
  "person": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  }
}

​
Step 2: Verify Customer Identity

After creating the customer profile, you need to verify their identity through the KYC process.

​
API Request

POST /api/v2/kyc/individual/verification
Content-Type: application/json
Authorization: Bearer {access_token}

​
Request Body

{
  "customerId": "cust_12345678",
  "documentType": "PASSPORT",
  "documentNumber": "AB1234567",
  "documentIssuingCountry": "United States",
  "documentExpiryDate": "2030-01-01",
  "dateOfBirth": "1985-05-15"
}

​
Response

{
  "verificationId": "ver_87654321",
  "status": "PENDING",
  "nextSteps": [
    {
      "type": "DOCUMENT_UPLOAD",
      "documentType": "PASSPORT",
      "uploadUrl": "https://api.finhub.cloud/upload/ver_87654321"
    }
  ]
}

​
Step 3: Upload Identity Documents

Upload the required identity documents for verification.

​
API Request

POST {uploadUrl from previous response}
Content-Type: multipart/form-data
Authorization: Bearer {access_token}

​
Request Body

--boundary
Content-Disposition: form-data; name="document"; filename="passport.jpg"
Content-Type: image/jpeg

[Binary data of the document image]
--boundary--

​
Response

{
  "documentId": "doc_12345678",
  "status": "RECEIVED",
  "message": "Document received and pending review"
}

​
Step 4: Check Verification Status

Periodically check the verification status until it’s completed. Note that verification can follow two paths:

  1. Automated Verification (90% of cases): The system automatically verifies the documents and approves the customer
  2. Manual Review (10% of cases): Documents are flagged for manual review by compliance officers in the Business Control Panel

​
API Request

GET /api/v2/kyc/individual/verification/{verificationId}
Authorization: Bearer {access_token}

​
Possible Responses

​
Automated Approval

{
  "verificationId": "ver_87654321",
  "customerId": "cust_12345678",
  "status": "COMPLETED",
  "verificationMethod": "AUTOMATED",
  "completedAt": "2025-05-31T10:30:00Z"
}

​
Manual Review in Progress

{
  "verificationId": "ver_87654321",
  "customerId": "cust_12345678",
  "status": "PENDING_REVIEW",
  "verificationMethod": "MANUAL",
  "message": "Documents under review by compliance team"
}

​
Manual Approval

{
  "verificationId": "ver_87654321",
  "customerId": "cust_12345678",
  "status": "COMPLETED",
  "verificationMethod": "MANUAL",
  "reviewerId": "rev_12345",
  "completedAt": "2025-05-31T11:45:00Z"
}

​
Step 5: Activate Customer Account

Once verification is complete, activate the customer account.

​
API Request

POST /api/v2/customer/individual/{customerId}/activate
Content-Type: application/json
Authorization: Bearer {access_token}

​
Response

{
  "id": "cust_12345678",
  "status": "ACTIVE",
  "activatedAt": "2025-05-31T10:35:00Z"
}

​
Step 6: Create Financial Account

Create a financial account for the customer.

​
API Request

POST /api/v2/accounts
Content-Type: application/json
Authorization: Bearer {access_token}

​
Request Body

{
  "customerId": "cust_12345678",
  "accountType": "CURRENT",
  "currency": "USD",
  "accountName": "Primary Account"
}

​
Response

{
  "accountId": "acc_87654321",
  "customerId": "cust_12345678",
  "accountNumber": "1234567890",
  "iban": "US12FINB1234567890",
  "currency": "USD",
  "status": "ACTIVE",
  "balance": {
    "available": 0,
    "current": 0,
    "currency": "USD"
  },
  "createdAt": "2025-05-31T10:40:00Z"
}

​
Error Handling

The API returns appropriate HTTP status codes and error messages when issues occur. Common error scenarios include:

HTTP StatusError CodeDescription
400INVALID_REQUESTThe request body is invalid or missing required fields
409DUPLICATE_EMAILA customer with the provided email already exists
422VERIFICATION_FAILEDThe customer verification failed
403INSUFFICIENT_PERMISSIONSThe API key doesn’t have permission to create customers

​
Example Error Response

{
  "error": {
    "code": "DUPLICATE_EMAIL",
    "message": "A customer with this email address already exists",
    "requestId": "req_abcdef123456"
  }
}

​
Best Practices

  1. Validation: Validate customer information before submission to avoid errors
  2. Error Handling: Implement robust error handling for all API calls
  3. Verification Status: Implement a polling mechanism to check verification status
  4. Security: Store customer IDs securely and never expose them to end users
  5. Compliance: Ensure all collected customer data complies with relevant regulations (GDPR, etc.)

​
Next Steps

After successfully opening an individual account, you can: