> ## 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
</Note>

## Endpoint

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

## Request Parameters

<ParamField body="description" type="string">
  * Maximum length: 200 characters

  * Used for reference and reporting
</ParamField>

<ParamField body="expires_at" type="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
</ParamField>

<ParamField body="reference" type="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
</ParamField>

<ParamField body="metadata" type="object">
  Additional data about the bulk transfer

  * Maximum size: 20KB

  * Key-value pairs of strings
</ParamField>

## Request Examples

<CodeGroup>
  ```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"
    }
  }
  ```
</CodeGroup>

## Response Format

<ResponseField name="data" type="object">
  Created bulk transfer session details

  <Expandable title="Response Fields">
    <ResponseField name="id" type="string">
      Unique identifier for the bulk transfer
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Creation timestamp in ISO 8601 format
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      Expiration timestamp in ISO 8601 format
    </ResponseField>

    <ResponseField name="description" type="string">
      Provided description
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the bulk transfer:

      * created - Initial state

      * executing - Transfers in progress

      * completed - All transfers processed

      * cancelled - Manually cancelled

      * expired - Session timeout
    </ResponseField>

    <ResponseField name="failed_transfer_count" type="integer">
      Number of failed transfers in the batch
    </ResponseField>

    <ResponseField name="successful_transfer_count" type="integer">
      Number of successful transfers in the batch
    </ResponseField>

    <ResponseField name="total_transfer_count" type="integer">
      Total number of transfers in the batch
    </ResponseField>

    <ResponseField name="items" type="array">
      List of individual transfers (empty on creation)
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Additional metadata provided
    </ResponseField>

    <ResponseField name="owner" type="object">
      Details about the creating entity
    </ResponseField>
  </Expandable>
</ResponseField>

## Response Examples

<CodeGroup>
  ```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"]
      }
    }
  }
  ```
</CodeGroup>

## Validation Rules

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Expiration Rules">
    * Must be in future

    * Minimum: 1 hour from creation

    * Maximum: 72 hours from creation

    * Must be valid ISO 8601 format
  </Accordion>

  <Accordion title="Description Rules">
    * Maximum length: 200 characters

    * Cannot contain HTML or special characters

    * Optional but recommended for tracking
  </Accordion>

  <Accordion title="Metadata Rules">
    * Maximum size: 20KB

    * Keys must be strings

    * Values must be strings

    * No nested objects allowed
  </Accordion>
</AccordionGroup>

## Rate Limits

<Note>
  * 10 bulk transfer initiations per minute

  * Maximum of 100 transfers per batch

  * Burst limit: 2 requests per second
</Note>

## 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

<Card title="Next Steps">
  After creating a bulk transfer session:

  1. [Add transfers](/transfers/bulk-transfers/update-bulk-transfer) to the batch

  2. [Execute the bulk transfer](/transfers/bulk-transfers/execute-bulk-transfer)

  3. [Monitor status](/transfers/bulk-transfers/get-bulk-transfer-details)
</Card>