​
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.

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

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

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

​
Response Format

​
data
object

Created bulk transfer session details

​
Response Examples

{
  "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"
  }
}

​
Validation Rules

​
Rate Limits

  • 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 to the batch

  2. Execute the bulk transfer

  3. Monitor status