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

# List bulk transfers

# List Bulk Transfers

Retrieve a paginated list of bulk transfers with support for filtering, sorting, and status tracking. This endpoint returns all bulk transfers associated with your account in chronological order.

## Endpoint

```bash theme={null}
GET /bulk-transfers
```

## Query Parameters

<ParamField query="status" type="string">
  Filter transfers by their current status:

  * `created` - Initialized but not executed
  * `executing` - Currently processing
  * `cancelled` - Manually cancelled
  * `expired` - Past execution window
  * `completed` - All transfers processed
</ParamField>

<ParamField query="after" type="string">
  Cursor for fetching next page of results

  * Use value from `pagination.after` in previous response
</ParamField>

<ParamField query="before" type="string">
  Cursor for fetching previous page of results

  * Use value from `pagination.before` in previous response
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Number of records to return per page

  * Minimum: 1
  * Maximum: 100
  * Default: 10
</ParamField>

## Response Format

<ResponseField name="data" type="array">
  Array of bulk transfer objects

  <Expandable title="Bulk Transfer Object">
    <ResponseField name="id" type="string">
      Unique identifier for the bulk transfer
    </ResponseField>

    <ResponseField name="description" type="string">
      Optional description of the bulk transfer
    </ResponseField>

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

    <ResponseField name="status" type="string">
      Current status of the 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>

    <ResponseField name="expires_at" type="string">
      ISO-8601 timestamp when the bulk transfer expires
    </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="metadata" type="object">
      Additional metadata about the transfer
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <ResponseField name="before" type="string">
    Cursor for the previous page
  </ResponseField>

  <ResponseField name="after" type="string">
    Cursor for the next page
  </ResponseField>

  <ResponseField name="limit" type="integer">
    Number of records per page
  </ResponseField>
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://payout-staging.spendjuice.com/v1/bulk-transfers?limit=10" \
  -H "Authorization:  YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://payout-staging.spendjuice.com/v1/bulk-transfers?limit=10',
    {
      headers: {
        'Authorization': ' YOUR_API_KEY'
      }
    }
  );
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://payout-staging.spendjuice.com/v1/bulk-transfers',
      params={'limit': 10},
      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": [],
        "metadata": {},
        "owner": {
          "id": "65fb1bf9-10e7-4556-8005-0c3249b8df36",
          "type": "personal"
        },
        "reference": "oct_2024_vendors",
        "status": "created",
        "successful_transfer_count": 0,
        "total_transfer_count": 0,
        "updated_at": "2024-10-02T17:39:26Z"
      }
    ],
    "pagination": {
      "after": "b101f718-d133-450c-a572-c281c7341803",
      "before": null,
      "limit": 10
    }
  }
  ```

  ```json 400 Invalid Parameters theme={null}
  {
    "error": {
      "code": "invalid_request",
      "message": "Invalid query parameters",
      "details": {
        "limit": ["Must be between 1 and 100"]
      }
    }
  }
  ```
</CodeGroup>

## Error Handling

<AccordionGroup>
  <Accordion title="400 - Invalid Request">
    Occurs when:

    * Invalid status value provided
    * Limit outside allowed range
    * Invalid cursor format
  </Accordion>

  <Accordion title="401 - Unauthorized">
    Occurs when:

    * Missing API key
    * Invalid API key
    * Expired API key
  </Accordion>

  <Accordion title="403 - Forbidden">
    Occurs when:

    * Insufficient permissions
    * Account restrictions
  </Accordion>
</AccordionGroup>

## Pagination

The API uses cursor-based pagination for reliable list operations:

1. Initial request: Specify desired `limit`
2. Subsequent requests: Use the `after` cursor from previous response
3. Previous page: Use the `before` cursor if available

<Note>
  For optimal performance:

  * Use reasonable page sizes (10-50 records)
  * Cache results when appropriate
  * Implement progressive loading in your UI
</Note>

## Rate Limits

<Info>
  This endpoint has the following rate limits:

  * 100 requests per minute per API key
  * Maximum of 1000 requests per hour
  * Burst limit: 20 requests per second
</Info>

## Best Practices

1. **Efficient Filtering**
   * Use status filters to reduce response size
   * Combine filters for precise results
   * Cache frequently accessed data

2. **Pagination Handling**
   * Store cursors temporarily for navigation
   * Implement infinite scroll for large lists
   * Show loading states during fetches

3. **Error Handling**
   * Implement proper retry logic
   * Handle rate limits gracefully
   * Log pagination errors

4. **Performance**
   * Use appropriate page sizes
   * Cache responses when possible
   * Monitor API response times

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

  * Check our [Error Handling Guide](/errors)
  * Review [Pagination Best Practices](/api-overview/pagination)
  * Contact [Support](mailto:support@juicyway.com)
</Card>