Get Bulk Transfer Details

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

string

required

The unique identifier of the bulk transfer to retrieve

Format: UUID v4
Example: 7d528558-1c20-4bb6-9a9a-a03c8292b297

Response Format

data

object

Show Response Fields

string

Unique identifier for the bulk transfer

description

string

User-provided description of the bulk transfer

status

string

Current status of the bulk transfer. One of:

created - Initial state
executing - Transfers in progress
completed - All transfers processed
cancelled - Manually cancelled
expired - Past expiration date

created_at

string

ISO 8601 timestamp of creation

updated_at

string

ISO 8601 timestamp of last update

expires_at

string

ISO 8601 timestamp when transfer expires

metadata

object

Optional additional data for the bulk transfer

owner

object

Details about the transfer owner

Show Owner Fields

string

Owner’s unique identifier

type

string

Owner type (e.g., “personal”, “business”)

items

array

Array of individual transfers in this batch

reference

string

Your unique reference for this bulk transfer

total_transfer_count

integer

Total number of transfers in the batch

successful_transfer_count

integer

Number of successfully completed transfers

failed_transfer_count

integer

Number of failed transfers

Example Request

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

const response = await fetch(
  'https://payout-staging.spendjuice.com/v1/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297',
  {
    headers: {
      'Authorization': ' YOUR_API_KEY'
    }
  }
);

import requests

response = requests.get(
    'https://payout-staging.spendjuice.com/v1/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297',
    headers={'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"
  }
}

{
  "error": {
    "code": "bulk_transfer_not_found",
    "message": "Bulk transfer not found",
    "type": "not_found_error"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key",
    "type": "authentication_error"
  }
}

Status Lifecycle

Bulk transfers progress through the following states:

Created

Initial state after creation

Transfers validated but not executed
Can be modified or cancelled

Executing

Transfers being processed

Individual transfers updating
Cannot be modified
Can be cancelled

Completed

All transfers processed

Final success/failure counts available
Cannot be modified or cancelled

Cancelled

Manually cancelled

Incomplete transfers stopped
Cannot be restarted

Expired

Past expiration date

Not executed
Cannot be modified or executed

Error Handling

401 - Unauthorized

Invalid API key provided
API key expired or revoked
Missing authorization header

403 - Forbidden

Insufficient permissions
API key doesn’t have access
Account restrictions

404 - Not Found

Invalid bulk transfer ID
Transfer deleted
Transfer not accessible

500 - Server Error

Temporary service disruption
Retry with exponential backoff
Contact support if persistent

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

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

Need Help?

For additional assistance:

​Overview

​Endpoint

​Path Parameters

​Response Format

​Example Request

​Response Examples

​Status Lifecycle

​Error Handling

​Rate Limits

​Best Practices

Need Help?

Overview

Endpoint

Path Parameters

Response Format

Example Request

Response Examples

Status Lifecycle

Error Handling

Rate Limits

Best Practices