Skip to main content

​
Get transfers

GET /api/v1/transfers
Retrieve all transfers between accounts for the authenticated user with support for date filtering and account filtering.

​
Query parameters

​
month
string
Filter transfers by month in YYYY-MM format. Cannot be used with start_date or end_date
​
start_date
string
Filter transfers on or after this date (YYYY-MM-DD). Cannot be used with month
​
end_date
string
Filter transfers on or before this date (YYYY-MM-DD). Cannot be used with month
​
account_id
string
Filter transfers where this account is either the source or destination
​
from_account_id
string
Filter transfers by source account UUID
​
to_account_id
string
Filter transfers by destination account UUID
​
description_contains
string
Filter transfers where description contains this text (case-insensitive)
​
min_amount
number
Filter transfers with amount greater than or equal to this value
​
max_amount
number
Filter transfers with amount less than or equal to this value
​
include_accounts
boolean
default:"true"
Include full account details for source and destination accounts. Accepts true, false, 1, or 0
​
fields
string
Comma-separated list of fields to return. Available fields: id, user_id, from_account_id, to_account_id, amount, date, description, created_at, from_account, to_account
​
sort
string
default:"date"
Field to sort by. Options: date, created_at, amount
​
order
string
default:"desc"
Sort order. Options: asc, desc
​
limit
integer
default:"100"
Maximum number of results to return (1-1000)
​
offset
integer
default:"0"
Number of results to skip for pagination
​
cursor
string
Cursor for pagination. Cannot be used with offset

​
Response fields

​
data
array
Array of transfer objects
​
id
string
Unique transfer identifier (UUID)
​
user_id
string
User UUID who owns this transfer
​
from_account_id
string
Source account UUID
​
to_account_id
string
Destination account UUID
​
amount
number
Transfer amount (always positive)
​
date
string
Transfer date (YYYY-MM-DD)
​
description
string | null
Transfer description
​
created_at
string
Transfer creation timestamp (ISO 8601)
​
from_account
object
Source account details (only included when include_accounts=true)
​
id
string
Account UUID
​
name
string
Account name
​
type
string
Account type
​
to_account
object
Destination account details (only included when include_accounts=true)
​
id
string
Account UUID
​
name
string
Account name
​
type
string
Account type
​
meta
object
Pagination and metadata
​
total
integer
Total number of matching transfers
​
returned
integer
Number of transfers returned in this response
​
limit
integer
Maximum results per page
​
offset
integer
Current offset
​
next_cursor
string | null
Cursor for the next page, or null if no more results
​
sort
string
Field used for sorting
​
order
string
Sort order applied
​
month
string | null
Month filter applied
​
start_date
string | null
Start date filter applied
​
end_date
string | null
End date filter applied
​
include_accounts
boolean
Whether account details were included

​
Example request

curl -X GET "https://api.cashcat.app/api/v1/transfers?month=2024-03&include_accounts=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example response

{
  "data": [
    {
      "id": "tr1s2t3u-v4w5-6789-trst-456789012345",
      "user_id": "u1v2w3x4-y5z6-7890-uvwx-456789012345",
      "from_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "to_account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "amount": 500.00,
      "date": "2024-03-15",
      "description": "Monthly savings transfer",
      "created_at": "2024-03-15T10:00:00Z",
      "from_account": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Main Checking",
        "type": "checking"
      },
      "to_account": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Savings Account",
        "type": "savings"
      }
    }
  ],
  "meta": {
    "total": 1,
    "returned": 1,
    "limit": 100,
    "offset": 0,
    "next_cursor": null,
    "sort": "date",
    "order": "desc",
    "month": "2024-03",
    "start_date": "2024-03-01",
    "end_date": "2024-03-31",
    "include_accounts": true
  }
}

​
Create transfer

POST /api/v1/transfers
Create a new transfer between two accounts. Both accounts must belong to the authenticated user.

​
Headers

​
Idempotency-Key
string
Optional idempotency key (max 200 characters) to prevent duplicate transfers

​
Query parameters

​
dry_run
boolean
default:"false"
If true, validates the transfer without creating it

​
Request body

​
from_account_id
string
required
Source account UUID
​
to_account_id
string
required
Destination account UUID (must be different from source)
​
amount
number
required
Transfer amount (must be positive)
​
date
string
required
Transfer date in YYYY-MM-DD format
​
description
string
Optional transfer description

​
Example request

curl -X POST "https://api.cashcat.app/api/v1/transfers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to_account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "amount": 500.00,
    "date": "2024-03-15",
    "description": "Monthly savings transfer"
  }'

​
Example response

{
  "data": {
    "id": "tr1s2t3u-v4w5-6789-trst-456789012345",
    "user_id": "u1v2w3x4-y5z6-7890-uvwx-456789012345",
    "from_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to_account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "amount": 500.00,
    "date": "2024-03-15",
    "description": "Monthly savings transfer",
    "created_at": "2024-03-15T10:00:00Z"
  },
  "meta": {
    "created": true
  }
}

​
Update transfer

PUT /api/v1/transfers
Update an existing transfer. All fields except id are optional.

​
Query parameters

​
dry_run
boolean
default:"false"
If true, validates the update without applying it

​
Request body

​
id
string
required
Transfer UUID to update
​
from_account_id
string
New source account UUID
​
to_account_id
string
New destination account UUID
​
amount
number
New transfer amount (must be positive)
​
date
string
New transfer date in YYYY-MM-DD format
​
description
string
New transfer description

​
Example request

curl -X PUT "https://api.cashcat.app/api/v1/transfers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "tr1s2t3u-v4w5-6789-trst-456789012345",
    "amount": 600.00,
    "description": "Updated savings transfer amount"
  }'

​
Example response

{
  "data": {
    "id": "tr1s2t3u-v4w5-6789-trst-456789012345",
    "user_id": "u1v2w3x4-y5z6-7890-uvwx-456789012345",
    "from_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to_account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "amount": 600.00,
    "date": "2024-03-15",
    "description": "Updated savings transfer amount",
    "created_at": "2024-03-15T10:00:00Z"
  },
  "meta": {
    "updated": true
  }
}

​
Delete transfer

DELETE /api/v1/transfers
Delete an existing transfer.

​
Query parameters

​
id
string
required
Transfer UUID to delete
​
dry_run
boolean
default:"false"
If true, validates the deletion without executing it

​
Example request

curl -X DELETE "https://api.cashcat.app/api/v1/transfers?id=tr1s2t3u-v4w5-6789-trst-456789012345" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example response

{
  "data": {
    "success": true,
    "id": "tr1s2t3u-v4w5-6789-trst-456789012345"
  }
}
Transfers move money between accounts without affecting budgets. They update account balances but don’t create budget entries.

Build docs developers (and LLMs) love

Get started for freeTalk to us