Get Transfers

Overview

The Get Transfers API allows you to retrieve a paginated list of transfers for a business. You can filter transfers by status, direction, and type, and control pagination with limit and offset parameters. Results are ordered by creation date (newest first).

Resource Access

• HTTP Method: GET
• Endpoint: /v1/businesses/{business_id}/transfers
• Authentication: Bearer token required

Path Parameters

Parameter	Type	Required	Description
business_id	string (UUID)	Yes	Unique identifier for the business

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of transfers to return (default: 50, max: 100)
offset	integer	No	Number of transfers to skip for pagination (default: 0)
status	string	No	Filter by transfer status: pending, processing, completed, failed, cancelled
direction	string	No	Filter by transfer direction: deposit, withdrawal
type	string	No	Filter by transfer type: wire, ach, check

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication

Response

Success Response (200 OK)

{
  "transfers": [
    {
      "id": "urn:uuid:transfer-123",
      "business_id": "urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc",
      "amount": {
        "currency": "USD",
        "amount": "100.00"
      },
      "bank_account_id": "urn:uuid:bank-account-123",
      "direction": "withdrawal",
      "type": "wire",
      "status": "completed",
      "idempotency_key": "urn:uuid:idempotency-123",
      "user_data": {
        "purpose": "Monthly withdrawal",
        "reference": "REF-001"
      },
      "created_at": "2022-01-01T00:00:00.000Z",
      "updated_at": "2022-01-01T12:00:00.000Z"
    },
    {
      "id": "urn:uuid:transfer-456",
      "business_id": "urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc",
      "amount": {
        "currency": "USD",
        "amount": "50.00"
      },
      "bank_account_id": "urn:uuid:bank-account-456",
      "direction": "deposit",
      "type": "ach",
      "status": "pending",
      "idempotency_key": "urn:uuid:idempotency-456",
      "user_data": {
        "purpose": "Customer payment",
        "reference": "REF-002"
      },
      "created_at": "2022-01-02T00:00:00.000Z",
      "updated_at": "2022-01-02T00:00:00.000Z"
    }
  ],
  "total_count": 25,
  "limit": 10,
  "offset": 0
}

Response Fields

Field	Type	Description
transfers	array	Array of transfer objects
transfers[].id	string (UUID)	Unique identifier for the transfer
transfers[].business_id	string (UUID)	Business ID this transfer belongs to
transfers[].amount	object	Transfer amount with currency
transfers[].bank_account_id	string (UUID)	Bank account ID used for this transfer
transfers[].direction	string	Transfer direction
transfers[].type	string	Transfer method type
transfers[].status	string	Current status of the transfer
transfers[].idempotency_key	string (UUID)	Idempotency key used
transfers[].user_data	object	Additional user-defined data
transfers[].created_at	string (date-time)	Creation timestamp
transfers[].updated_at	string (date-time)	Last update timestamp
total_count	integer	Total number of transfers matching the criteria
limit	integer	Number of transfers returned in this response
offset	integer	Number of transfers skipped

Transfer Status Values

• pending: Transfer initiated but not yet processed
• processing: Transfer is being processed
• completed: Transfer successfully completed
• failed: Transfer failed to process
• cancelled: Transfer was cancelled

Transfer Direction Values

• deposit: Money coming into the business account
• withdrawal: Money going out of the business account

Transfer Type Values

• wire: Wire transfer (fastest, highest fees)
• ach: ACH transfer (slower, lower fees)
• check: Physical check (slowest, variable fees)

Error Responses

• 400 Bad Request: Invalid query parameters (e.g., invalid limit or offset)
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: User does not have permission to view transfers for this business
• 404 Not Found: Business not found

Code Examples

cURL

curl -X GET \
  'https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/transfers?limit=10&status=completed' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Python

import requests

url = "https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/transfers"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
params = {
    "limit": 10,
    "status": "completed"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/transfers';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};
const params = {
  limit: 10,
  status: 'completed'
};

axios.get(url, { headers, params })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• Results are ordered by creation date (newest first)
• Use limit and offset for pagination through large result sets
• Combine filters to narrow down results (e.g., status + direction + type)
• The total_count field indicates the total number of transfers matching your filters
• Maximum limit is 100 transfers per request
• Default limit is 50 if not specified
• Use this API to monitor transfer status, generate reports, or build transfer history views

Interactive API Explorer