​
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

GET /bulk-transfers

​
Query Parameters

​
status
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
​
after
string

Cursor for fetching next page of results

  • Use value from pagination.after in previous response
​
before
string

Cursor for fetching previous page of results

  • Use value from pagination.before in previous response
​
limit
integer
default:"10"

Number of records to return per page

  • Minimum: 1
  • Maximum: 100
  • Default: 10

​
Response Format

​
data
array

Array of bulk transfer objects

​
pagination
object
​
before
string

Cursor for the previous page

​
after
string

Cursor for the next page

​
limit
integer

Number of records per page

​
Example Request

curl -X GET "https://payout-staging.spendjuice.com/v1/bulk-transfers?limit=10" \
-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": [],
      "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
  }
}

​
Error Handling

​
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

For optimal performance:

  • Use reasonable page sizes (10-50 records)
  • Cache results when appropriate
  • Implement progressive loading in your UI

​
Rate Limits

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

​
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

Need Help?

For additional assistance: