> ## Documentation Index
> Fetch the complete documentation index at: https://docs.juicyway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate Bulk Transfer

> Create a new bulk transfer session for processing multiple transfers efficiently

## Overview

Bulk transfers allow you to process multiple transfers in a single batch operation. This endpoint creates a new bulk transfer session that you can later populate with individual transfers and execute as a group.

> [!NOTE]
>
> Before initiating a bulk transfer:
>
> * Ensure sufficient balance for the expected total
>
> * Have your beneficiary details ready
>
> * Review the transfer limits and cut-off times

## Endpoint

```bash theme={null}
POST /bulk-transfers
```

## Request Parameters

**description** `string`

* Maximum length: 200 characters

* Used for reference and reporting

**expires\_at** `string`

Timestamp when the bulk transfer session expires

* Format: ISO 8601 (e.g., "2024-10-03T18:38:31Z")

* Maximum: 72 hours from creation

* Default: 24 hours from creation

**reference** `string` *required*

Your unique reference for this bulk transfer

* Must be unique across all bulk transfers

* Maximum length: 64 characters

* Alphanumeric characters, hyphens, and underscores only

**metadata** `object`

Additional data about the bulk transfer

* Maximum size: 20KB

* Key-value pairs of strings

## Request Examples

```json Basic Request theme={null}
{
  "description": "Monthly vendor payments",
  "expires_at": "2024-10-03T18:38:31Z",
  "reference": "juice-bulk-transfer-5d906f6d-933b-4de9-927f-c7522823f5ec"
}
```

```json With Metadata theme={null}
{
  "description": "Q4 contractor payments",
  "expires_at": "2024-10-03T18:38:31Z",
  "reference": "juice-bulk-q4-contractors-2024",
  "metadata": {
    "department": "engineering",
    "batch_type": "contractors",
    "period": "Q4-2024"
  }
}
```

## Response Format

**data** `object`

Created bulk transfer session details

**Response Fields**

**id** `string`

Unique identifier for the bulk transfer

**created\_at** `string`

Creation timestamp in ISO 8601 format

**expires\_at** `string`

Expiration timestamp in ISO 8601 format

**description** `string`

Provided description

**status** `string`

Current status of the bulk transfer:

* created - Initial state

* executing - Transfers in progress

* completed - All transfers processed

* cancelled - Manually cancelled

* expired - Session timeout

**failed\_transfer\_count** `integer`

Number of failed transfers in the batch

**successful\_transfer\_count** `integer`

Number of successful transfers in the batch

**total\_transfer\_count** `integer`

Total number of transfers in the batch

**items** `array`

List of individual transfers (empty on creation)

**metadata** `object`

Additional metadata provided

**owner** `object`

Details about the creating entity

## Response Examples

```json 201 Created theme={null}
{
  "data": {
    "created_at": "2024-10-02T17:39:26.049258Z",
    "description": "Monthly vendor payments",
    "expires_at": "2024-10-03T18:38:31Z",
    "failed_transfer_count": 0,
    "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "items": [],
    "metadata": {},
    "owner": {
      "id": "65fb1bf9-10e7-4556-8005-0c3249b8df36",
      "type": "personal"
    },
    "reference": "juice-bulk-transfer-5d906f6d-933b-4de9-927f-c7522823f5ec",
    "status": "created",
    "successful_transfer_count": 0,
    "total_transfer_count": 0,
    "updated_at": "2024-10-02T17:39:26Z"
  }
}
```

```json 400 Invalid Request theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "The request contains invalid parameters",
    "details": {
      "reference": ["Must be unique across all bulk transfers"]
    }
  }
}
```

```json 422 Validation Error theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Invalid expiration time",
    "details": {
      "expires_at": ["Must be between 1 and 72 hours from now"]
    }
  }
}
```

## Validation Rules

> **Reference Rules**
>
> * Must be unique across all bulk transfers
>
> * Length: 1-64 characters
>
> * Allowed characters: A-Z, a-z, 0-9, -, \_
>
> * Cannot start or end with hyphen/underscore

> **Expiration Rules**
>
> * Must be in future
>
> * Minimum: 1 hour from creation
>
> * Maximum: 72 hours from creation
>
> * Must be valid ISO 8601 format

> **Description Rules**
>
> * Maximum length: 200 characters
>
> * Cannot contain HTML or special characters
>
> * Optional but recommended for tracking

> **Metadata Rules**
>
> * Maximum size: 20KB
>
> * Keys must be strings
>
> * Values must be strings
>
> * No nested objects allowed

## Rate Limits

> [!NOTE]
>
> * 10 bulk transfer initiations per minute
>
> * Maximum of 100 transfers per batch
>
> * Burst limit: 2 requests per second

## Best Practices

1. **Reference Generation**

   * Use structured, meaningful references

   * Include date/time components

   * Add batch type identifiers

   * Store references for reconciliation

2. **Error Handling**

   * Implement proper retry logic

   * Monitor rate limits

   * Log all attempts

   * Handle timeouts gracefully

3. **Session Management**

   * Set reasonable expiration times

   * Plan for session timeouts

   * Monitor session status

   * Handle expired sessions

> **Next Steps**
>
> After creating a bulk transfer session:
>
> 1. [Add transfers](https://docs.juicyway.com/transfers/bulk-transfers/update-bulk-transfer.md) to the batch
>
> 2. [Execute the bulk transfer](https://docs.juicyway.com/transfers/bulk-transfers/execute-bulk-transfer.md)
>
> 3. [Monitor status](https://docs.juicyway.com/transfers/bulk-transfers/get-bulk-transfer-details.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.