# Bulk Creation & Pre-provisioning

The virtual account system supports an `unallocated` flag during creation, allowing you to bulk pre-provision accounts before they are needed. This feature is designed for high-volume use cases where instant account assignment is critical for the user experience.

## Why Pre-provision Accounts?

### 1. Instant Customer Onboarding

Standard account creation may involve slight delays as systems process the request. By maintaining a pool of pre-created, unallocated accounts, you can instantly assign a virtual account number to a new customer the moment they sign up, without waiting for upstream provider responses.

### 2. Regulatory Compliance & Clean History

Reallocating used accounts to different customers can create audit and compliance complexities. The pre-provisioning model ensures that every customer receives a fresh account with no prior transaction history, maintaining strict segregation of data and funds.

### 3. Batch Processing Efficiency

Instead of making individual API calls for every new user in real-time, you can run batch jobs to replenish your pool of unallocated accounts during off-peak hours, ensuring you always have inventory ready for peak demand.

## Workflow

The following diagram illustrates how the pre-provisioning and allocation process works:


```mermaid
%%{init: {'theme': 'neutral', 'themeVariables': { 'fontSize': '16px', 'fontFamily': 'arial' }}}%%
sequenceDiagram
    participant User as End Customer
    participant Client as Client System
    participant API as BCB API
    
    note over Client, API: Phase 1: Pre-provisioning (Batch Job)
    Client->>API: POST /v1/virtual-accounts (items: [{unallocated: true}, ...])
    API-->>Client: Returns list of Unallocated Accounts
    Client->>Client: Store accounts in Inventory Pool
    
    note over User, Client: Phase 2: Instant Onboarding
    User->>Client: Sign Up / Request Account
    Client->>Client: Fetch available account from Pool
    Client->>API: PATCH /v1/virtual-accounts/{id} (Set customer details)
    API-->>Client: 200 OK (Account Allocated)
    Client-->>User: Display Account Number immediately
```

### Step 1: Create a Pool of Unallocated Accounts

When your inventory of available accounts runs low, you can create a new batch. For standard operations (1-2 accounts), the normal creation flow is sufficient. For larger volumes, use the `unallocated` flag.

**Endpoint:** `POST /v1/virtual-accounts`

**Request:**
You only need to specify the currency and the unallocated flag within the `items` array.


```json
{
  "items": [
    {
      "currency": "USD",
      "unallocated": true
    },
    {
      "currency": "USD",
      "unallocated": true
    }
  ]
}
```

### Step 2: Assign (Allocate) an Account

When a new customer needs an account, you select one from your unallocated pool and update its details. This "claims" the account for that specific customer.

**Endpoint:** `PATCH /v1/virtual-accounts/{virtualAccountNumber}`

**Key Behavior:**

- **While Unallocated:** You can update core identity fields (`accountName`, `accountHolderName`, `dob`, `nativeLanguageName`) and the `clientReference`.
- **To Allocate:** Update the account with the customer's real details (`accountName`, `accountHolderName`, etc.). This permanently assigns the account to that customer.
- **After Allocation:** Once an account is allocated to a customer, **only** the `clientReference` can be updated. This ensures the integrity of the account ownership.


**Example Allocation Request:**


```json
{
  "accountHolderName": "Jane Smith",
  "accountName": "Jane Smith",
  "clientReference": "USER_ID_98765",
  "dob": "1985-05-20",
  "nativeLanguageName": "Jane Smith"
}
```