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

# Get Bulk Transfer Details

> Retrieve detailed information about a specific bulk transfer including its status, items, and execution results

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

```bash theme={null}
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`

**Response Fields**

**id** `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

**Owner Fields**

**id** `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

```bash cURL theme={null}
curl -X GET "https://payout-staging.spendjuice.com/v1/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297" \
-H "Authorization:  YOUR_API_KEY"
```

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

```python Python theme={null}
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

```json 200 Success theme={null}
{
  "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"
  }
}
```

```json 404 Not Found theme={null}
{
  "error": {
    "code": "bulk_transfer_not_found",
    "message": "Bulk transfer not found",
    "type": "not_found_error"
  }
}
```

```json 401 Unauthorized theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key",
    "type": "authentication_error"
  }
}
```

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

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

> [!NOTE]
>
> 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:
>
> * Check our [Error Handling Guide](https://docs.juicyway.com/errors.md)
> * Review [Webhook Implementation](https://docs.juicyway.com/webhooks.md)
> * Contact [support@juicyway.com](mailto:support@juicyway.com)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.