Transactions

Overview

The Transactions API allows you to manage all financial transactions across your accounts. Transactions represent money movements including expenses, income, transfers, and payments.

List
Get
Create
Update
Delete

List transactions

curl -X GET "https://api.sure.app/v1/transactions?account_id=123&start_date=2024-01-01" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Retrieve a paginated list of transactions with optional filtering.

Query parameters

page

integer

default:"1"

Page number for pagination

per_page

integer

default:"25"

Number of transactions per page (max 100)

account_id

integer

Filter by single account ID

account_ids

array

Filter by multiple account IDs

category_id

integer

Filter by category ID

category_ids

array

Filter by multiple category IDs

merchant_id

integer

Filter by merchant ID

merchant_ids

array

Filter by multiple merchant IDs

tag_ids

array

Filter by tag IDs

start_date

string

Filter transactions on or after this date (YYYY-MM-DD)

end_date

string

Filter transactions on or before this date (YYYY-MM-DD)

min_amount

number

Filter transactions with amount greater than or equal to this value

max_amount

number

Filter transactions with amount less than or equal to this value

type

string

Filter by transaction type: income or expense

string

Search in transaction name, notes, and merchant name

Response

transactions

array

Array of transaction objects

Show Transaction object

integer

Unique identifier for the transaction

date

string

Transaction date (YYYY-MM-DD)

amount

string

Formatted amount string (e.g., “$50.00”)

amount_cents

integer

Absolute amount in minor units (cents)

signed_amount_cents

integer

Signed amount in minor units (negative for expenses, positive for income)

currency

string

Three-letter ISO currency code

name

string

Transaction description

notes

string

Additional notes

classification

string

Transaction classification: income or expense

account

object

Account information

Show Account

integer

Account ID

name

string

Account name

account_type

string

Account type

Get a transaction

curl -X GET https://api.sure.app/v1/transactions/1001 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Retrieve a specific transaction by ID.

Path parameters

integer

required

Transaction ID

Response

Returns a transaction object.

{
  "id": 1001,
  "date": "2024-01-15",
  "amount": "$42.50",
  "amount_cents": 4250,
  "signed_amount_cents": -4250,
  "currency": "USD",
  "name": "Starbucks",
  "notes": "Coffee meeting",
  "classification": "expense",
  "account": {
    "id": 1,
    "name": "Chase Checking",
    "account_type": "depository"
  },
  "category": {
    "id": 5,
    "name": "Food & Drink",
    "classification": "expense",
    "color": "#f97316",
    "icon": "utensils"
  },
  "merchant": null,
  "tags": [],
  "transfer": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Create a transaction

curl -X POST https://api.sure.app/v1/transactions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "account_id": 1,
      "date": "2024-01-15",
      "amount": 42.50,
      "nature": "expense",
      "name": "Lunch at cafe",
      "category_id": 5,
      "notes": "Team lunch"
    }
  }'

Create a new transaction.

Request body

transaction

object

required

Show Transaction parameters

account_id

integer

required

ID of the account for this transaction

date

string

required

Transaction date in YYYY-MM-DD format

amount

number

required

Transaction amount (positive number)

nature

string

required

Transaction nature: expense, outflow, income, or inflow

name

string

required

Transaction description

description

string

Alternative to name (will be used as name if name not provided)

category_id

integer

Category ID

merchant_id

integer

Merchant ID

tag_ids

array

Array of tag IDs

notes

string

Additional notes

currency

string

Three-letter ISO currency code (defaults to family currency)

Response

Returns the created transaction object.

{
  "id": 1002,
  "date": "2024-01-15",
  "amount": "$42.50",
  "amount_cents": 4250,
  "signed_amount_cents": -4250,
  "currency": "USD",
  "name": "Lunch at cafe",
  "notes": "Team lunch",
  "classification": "expense",
  "account": {
    "id": 1,
    "name": "Chase Checking",
    "account_type": "depository"
  },
  "category": {
    "id": 5,
    "name": "Food & Drink",
    "classification": "expense",
    "color": "#f97316",
    "icon": "utensils"
  },
  "merchant": null,
  "tags": [],
  "transfer": null,
  "created_at": "2024-01-15T14:30:00Z",
  "updated_at": "2024-01-15T14:30:00Z"
}

Update a transaction

curl -X PUT https://api.sure.app/v1/transactions/1001 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "name": "Updated description",
      "category_id": 6,
      "notes": "Updated notes"
    }
  }'

Update an existing transaction.

Path parameters

integer

required

Transaction ID

Request body

transaction

object

required

Show Transaction parameters

date

string

Transaction date in YYYY-MM-DD format

amount

number

Transaction amount

nature

string

Transaction nature: expense, outflow, income, or inflow

name

string

Transaction description

category_id

integer

Category ID (set to null to uncategorize)

merchant_id

integer

Merchant ID

tag_ids

array

Array of tag IDs (only updated when explicitly provided)

notes

string

Additional notes

Response

Returns the updated transaction object.

{
  "id": 1001,
  "date": "2024-01-15",
  "amount": "$42.50",
  "amount_cents": 4250,
  "signed_amount_cents": -4250,
  "currency": "USD",
  "name": "Updated description",
  "notes": "Updated notes",
  "classification": "expense",
  "account": {
    "id": 1,
    "name": "Chase Checking",
    "account_type": "depository"
  },
  "category": {
    "id": 6,
    "name": "Shopping",
    "classification": "expense",
    "color": "#3b82f6",
    "icon": "shopping-cart"
  },
  "merchant": null,
  "tags": [],
  "transfer": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T15:45:00Z"
}

Delete a transaction

curl -X DELETE https://api.sure.app/v1/transactions/1001 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Delete a transaction permanently.

Path parameters

integer

required

Transaction ID

Response

{
  "message": "Transaction deleted successfully"
}

Transaction nature

When creating or updating transactions, the nature field determines how the amount is signed:

expense or outflow: Amount is stored as positive (money leaving the account)
income or inflow: Amount is stored as negative (money entering the account)

The API expects positive amounts in the request and applies the correct sign based on the nature.

Getting Started

Resources

Transactions

Overview

List transactions

Query parameters

Response

Get a transaction

Path parameters

Response

Create a transaction

Request body

Response

Update a transaction

Path parameters

Request body

Response

Delete a transaction

Path parameters

Response

Transaction nature

Build docs developers (and LLMs) love

Getting Started

Resources

​Overview

​List transactions

​Query parameters

​Response

​Get a transaction

​Path parameters

​Response

​Create a transaction

​Request body

​Response

​Update a transaction

​Path parameters

​Request body

​Response

​Delete a transaction

​Path parameters

​Response

​Transaction nature

Build docs developers (and LLMs) love

Overview

List transactions

Query parameters

Response

Get a transaction

Path parameters

Response

Create a transaction

Request body

Response

Update a transaction

Path parameters

Request body

Response

Delete a transaction

Path parameters

Response

Transaction nature