Import Transaction (Transfer between Accounts)

[krpradeep]

Hi,

I am trying to migrate my current data to Sure, I am able to create accounts/category etc. and now trying to import transactions.

I can import Transactions (using csv) which are against income/expense category but how do I import transfers between Accounts. Is there any sample csv template.

[jjmata]

Are you migrating from maybe? The schema is compatible/migrations will be run when you start sure automatically. Just make a backup in case things go wrong, but the export/import flow was not 100% complete from what I remember the maybe team saying.

[krpradeep]

Not from maybe but from moneydance.

or If there is currently no way to import transfer, may be I can use API end point to automate migrating transactions. Can you point me to place where I can find API for it. I tried dev tools but looks like it using authenticity_token for each request. Not sure how to generate one to pass in payload. may be that is something only rail specific. Not familiar with rail.

[minideezel]

Per the unofficial API docs floating around here and looking at the code, it doesn't support POSTING a transfer either. So there's no way to get a transfer in besides manually adding it. Definitely a needed feature.

[jjmata]

Can you point me to place where I can find API for it.

There is only some light documentation for the /chats endpoints here. I was trying to improve things here, would love help!

The best we have currently is what Amr collected here via Cursor work:

# Sure Finances API Specification

## Base URL

https://<url>/api/v1

## Authentication
Two methods supported:

### 1. OAuth2 (Bearer Token)

Authorization: Bearer <access_token>

### 2. API Key

X-Api-Key: <api_key>

## Rate Limits
- **Standard Tier**: 100 requests/hour
- **Premium Tier**: 1,000 requests/hour  
- **Enterprise Tier**: 10,000 requests/hour
- **Self-hosted**: No rate limiting

---

## Authentication Endpoints

### POST /auth/signup
Create new user account
```json
{
  "user": {
    "email": "[email protected]",
    "password": "SecurePass123!",
    "first_name": "John",
    "last_name": "Doe"
  },
  "device": {
    "device_id": "unique-device-id",
    "device_name": "iPhone 15",
    "device_type": "mobile",
    "os_version": "iOS 17.0",
    "app_version": "1.0.0"
  },
  "invite_code": "optional-invite-code"
}

Response:

{
  "access_token": "token",
  "refresh_token": "refresh_token", 
  "token_type": "Bearer",
  "expires_in": 2592000,
  "created_at": 1234567890,
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  }
}

POST /auth/login

Login with existing credentials

{
  "email": "[email protected]",
  "password": "SecurePass123!",
  "device": {
    "device_id": "unique-device-id",
    "device_name": "iPhone 15", 
    "device_type": "mobile",
    "os_version": "iOS 17.0",
    "app_version": "1.0.0"
  },
  "otp_code": "optional-2fa-code"
}

POST /auth/refresh

Refresh access token

{
  "refresh_token": "refresh_token",
  "device": {
    "device_id": "unique-device-id"
  }
}

---

Account Endpoints

GET /accounts

List all accounts (read-only)
Query Parameters:

• page (optional): Page number (default: 1)
• per_page (optional): Items per page (1-100, default: 25)

Response:

{
  "accounts": [
    {
      "id": "uuid",
      "name": "Chase Checking",
      "type": "Depository",
      "balance": 5000.00,
      "currency": "USD",
      "classification": "asset"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 10,
    "pages": 1
  }
}

PATCH /accounts/{id}/update_balance

Update account balance

{
  "balance": 5500.00
}

Response:

{
  "message": "Balance updated successfully",
  "account": {
    "id": "uuid",
    "name": "Chase Checking", 
    "balance": 5500.00,
    "currency": "USD"
  }
}

---

Transaction Endpoints

GET /transactions

List transactions with filtering
Query Parameters:

• page, per_page: Pagination
• account_id: Filter by account
• account_ids[]: Filter by multiple accounts
• category_id: Filter by category
• category_ids[]: Filter by multiple categories
• merchant_id: Filter by merchant
• merchant_ids[]: Filter by multiple merchants
• start_date: Filter from date (YYYY-MM-DD)
• end_date: Filter to date (YYYY-MM-DD)
• min_amount: Minimum amount
• max_amount: Maximum amount
• tag_ids[]: Filter by tags
• type: "income" or "expense"
• search: Search in name, notes, merchant

POST /transactions

Create new transaction

{
  "transaction": {
    "account_id": "uuid",
    "date": "2024-01-15",
    "amount": 50.00,
    "name": "Coffee Shop",
    "description": "Morning coffee",
    "notes": "Daily coffee",
    "currency": "USD",
    "category_id": "uuid",
    "merchant_id": "uuid",
    "nature": "expense",
    "tag_ids": ["uuid1", "uuid2"]
  }
}

GET /transactions/{id}

Get single transaction

PATCH /transactions/{id}

Update transaction

{
  "transaction": {
    "amount": 55.00,
    "name": "Updated Coffee Shop",
    "notes": "Updated notes"
  }
}

DELETE /transactions/{id}

Delete transaction

---

Chat AI Endpoints

GET /chats

List AI chats
Query Parameters:

• page, per_page: Pagination

POST /chats

Create new chat

{
  "title": "Budget Analysis",
  "message": "Analyze my spending patterns",
  "model": "gpt-4"
}

GET /chats/{id}

Get chat with messages

PATCH /chats/{id}

Update chat title

{
  "title": "Updated Chat Title"
}

DELETE /chats/{id}

Delete chat

POST /chats/{chat_id}/messages

Send message to AI

{
  "content": "What's my biggest expense category?",
  "model": "gpt-4"
}

POST /chats/{chat_id}/messages/retry

Retry last AI response

---

Usage Endpoints

GET /usage

Get API usage information
Response:

{
  "api_key": {
    "name": "My API Key",
    "scopes": ["read", "write"],
    "last_used_at": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "rate_limit": {
    "tier": "standard",
    "limit": 100,
    "current_count": 25,
    "remaining": 75,
    "reset_in_seconds": 1800,
    "reset_at": "2024-01-15T11:00:00Z"
  }
}

---

Error Responses

Standard Error Format

{
  "error": "error_type",
  "message": "Human readable error message",
  "errors": ["Detailed error 1", "Detailed error 2"]
}

Common Status Codes

• 200: Success
• 201: Created
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 422: Unprocessable Entity
• 429: Rate Limit Exceeded
• 500: Internal Server Error

Rate Limit Exceeded

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded",
  "reset_in_seconds": 1800
}

---

Scopes

• read: Read access to accounts, transactions, chats
• write: Full access including create, update, delete operations
• read_write: Full access (default for OAuth)

Notes

• All amounts are decimal numbers
• Dates are in ISO 8601 format (YYYY-MM-DD)
• UUIDs are used for all IDs
• Currency defaults to family's preferred currency
• Negative amounts represent income/inflow
• Positive amounts represent expenses/outflow

[jjmata]

My understanding (without looking at code) is that transfers are auto-identified (attempted!) by code that runs after your perform your import, maybe @dosu can confirm for us with some links to the code where that happen.

[dosubot[bot]]

Yes, transfers are auto-identified after import in Sure. The system expects you to import two transactions—one for each side of the transfer (outflow from one account, inflow to another). After import, Sure runs a matching process that attempts to reconcile these pairs into a single transfer entity. This is handled by matcher services and jobs that look for transactions with opposite amounts, different accounts, and dates within a close range.

You can see how transfers are represented and validated in the Transfer model, which requires the two transactions to have different accounts, opposite amounts, and dates within 4 days of each other. The Transaction model defines the types of transactions, including transfers.

There isn’t a dedicated CSV template for transfers; you just import the two transactions as you would any other, and the system attempts to match them. This process is automatic but may not be perfect—manual review is sometimes needed if the transactions don’t match up cleanly (for example, if the amounts or dates differ too much).

Let me know if you want more details on the matcher service or best practices for formatting your CSV!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}