Skip to main content

​
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

  • 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
  • Must be in future
  • Minimum: 1 hour from creation
  • Maximum: 72 hours from creation
  • Must be valid ISO 8601 format
  • Maximum length: 200 characters
  • Cannot contain HTML or special characters
  • Optional but recommended for tracking
  • Maximum size: 20KB
  • Keys must be strings
  • Values must be strings
  • No nested objects allowed

​
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
⌘I