​
Overview

The Get Bulk Transfer Details endpoint allows you to retrieve comprehensive information about a specific bulk transfer including its current status, all included transfers, success/failure counts, and execution results.

​
Endpoint

GET /bulk-transfers/{id}

​
Path Parameters

​
id
string
required
The unique identifier of the bulk transfer to retrieve
  • Format: UUID v4
  • Example: 7d528558-1c20-4bb6-9a9a-a03c8292b297

​
Response Format

​
data
object

​
Example Request

curl -X GET "https://payout-staging.spendjuice.com/v1/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297" \
-H "Authorization:  YOUR_API_KEY"

​
Response Examples

{
  "data": {
    "created_at": "2024-10-02T17:39:26.049258",
    "description": "October Vendor Payments",
    "expires_at": "2024-10-03T17:39:25Z",
    "failed_transfer_count": 0,
    "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "items": [
      {
        "amount": 100000,
        "beneficiary": {
          "account_name": "ACME Corp",
          "account_number": "0123456789",
          "bank_name": "Example Bank"
        },
        "status": "pending",
        "created_at": "2024-10-02T17:39:26Z",
        "reference": "vendor_payment_123"
      }
    ],
    "metadata": {
      "department": "finance",
      "batch_id": "OCT2024_001"
    },
    "owner": {
      "id": "65fb1bf9-10e7-4556-8005-0c3249b8df36",
      "type": "business"
    },
    "reference": "46f3ef38-22de-4498-a6d3-13749aa2a0a7",
    "status": "created",
    "successful_transfer_count": 0,
    "total_transfer_count": 1,
    "updated_at": "2024-10-02T17:39:26Z"
  }
}

​
Status Lifecycle

Bulk transfers progress through the following states:
1

Created

Initial state after creation
  • Transfers validated but not executed
  • Can be modified or cancelled
2

Executing

Transfers being processed
  • Individual transfers updating
  • Cannot be modified
  • Can be cancelled
3

Completed

All transfers processed
  • Final success/failure counts available
  • Cannot be modified or cancelled
4

Cancelled

Manually cancelled
  • Incomplete transfers stopped
  • Cannot be restarted
5

Expired

Past expiration date
  • Not executed
  • Cannot be modified or executed

​
Error Handling

​
Rate Limits

This endpoint has the following rate limits:
  • 120 requests per minute per API key
  • Burst limit: 20 requests per second
  • Headers included:
    • X-RateLimit-Limit
    • X-RateLimit-Remaining
    • X-RateLimit-Reset

​
Best Practices

  1. Monitoring
    • Poll sparingly during execution
    • Use webhooks for status updates
    • Monitor failed transfers
    • Track execution progress
  2. Error Handling
    • Implement exponential backoff
    • Handle rate limits gracefully
    • Log all request failures
    • Set appropriate timeouts
  3. Response Processing
    • Cache stable responses
    • Track status changes
    • Monitor success rates
    • Alert on high failure rates

Need Help?

For additional assistance: