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

<ParamField path="id" type="string" required>
  The unique identifier of the bulk transfer to retrieve

  * Format: UUID v4
  * Example: `7d528558-1c20-4bb6-9a9a-a03c8292b297`
</ParamField>

## Response Format

<ResponseField name="data" type="object">
  <Expandable title="Response Fields">
    <ResponseField name="id" type="string">
      Unique identifier for the bulk transfer
    </ResponseField>

    <ResponseField name="description" type="string">
      User-provided description of the bulk transfer
    </ResponseField>

    <ResponseField name="status" type="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
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      ISO 8601 timestamp when transfer expires
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Optional additional data for the bulk transfer
    </ResponseField>

    <ResponseField name="owner" type="object">
      Details about the transfer owner

      <Expandable title="Owner Fields">
        <ResponseField name="id" type="string">
          Owner's unique identifier
        </ResponseField>

        <ResponseField name="type" type="string">
          Owner type (e.g., "personal", "business")
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="items" type="array">
      Array of individual transfers in this batch
    </ResponseField>

    <ResponseField name="reference" type="string">
      Your unique reference for this bulk transfer
    </ResponseField>

    <ResponseField name="total_transfer_count" type="integer">
      Total number of transfers in the batch
    </ResponseField>

    <ResponseField name="successful_transfer_count" type="integer">
      Number of successfully completed transfers
    </ResponseField>

    <ResponseField name="failed_transfer_count" type="integer">
      Number of failed transfers
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

<CodeGroup>
  ```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'}
  )
  ```
</CodeGroup>

## Response Examples

<CodeGroup>
  ```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"
    }
  }
  ```
</CodeGroup>

## Status Lifecycle

Bulk transfers progress through the following states:

<Steps>
  <Step title="Created">
    Initial state after creation

    * Transfers validated but not executed
    * Can be modified or cancelled
  </Step>

  <Step title="Executing">
    Transfers being processed

    * Individual transfers updating
    * Cannot be modified
    * Can be cancelled
  </Step>

  <Step title="Completed">
    All transfers processed

    * Final success/failure counts available
    * Cannot be modified or cancelled
  </Step>

  <Step title="Cancelled">
    Manually cancelled

    * Incomplete transfers stopped
    * Cannot be restarted
  </Step>

  <Step title="Expired">
    Past expiration date

    * Not executed
    * Cannot be modified or executed
  </Step>
</Steps>

## Error Handling

<AccordionGroup>
  <Accordion title="401 - Unauthorized">
    * Invalid API key provided
    * API key expired or revoked
    * Missing authorization header
  </Accordion>

  <Accordion title="403 - Forbidden">
    * Insufficient permissions
    * API key doesn't have access
    * Account restrictions
  </Accordion>

  <Accordion title="404 - Not Found">
    * Invalid bulk transfer ID
    * Transfer deleted
    * Transfer not accessible
  </Accordion>

  <Accordion title="500 - Server Error">
    * Temporary service disruption
    * Retry with exponential backoff
    * Contact support if persistent
  </Accordion>
</AccordionGroup>

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

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

<Card title="Need Help?">
  For additional assistance:

  * Check our [Error Handling Guide](/errors)
  * Review [Webhook Implementation](/webhooks)
  * Contact [support@juicyway.com](mailto:support@juicyway.com)
</Card>