Skip to main content

​
Overview

The Sync API triggers a comprehensive synchronization for your family’s financial data. This includes applying categorization rules, syncing all connected accounts, and automatically matching transfers between accounts.

​
Authentication

Requires read_write or write scope.

​
Endpoint

​
Trigger Sync

​
POST
/api/v1/sync
Initiate a family-wide sync operation.
What Gets Synced When you trigger a sync, Sure will:
  1. Apply all active categorization rules to transactions
  2. Sync all connected accounts (Plaid, SimpleFIN, etc.)
  3. Automatically detect and match transfer transactions between accounts
  4. Update account balances and holdings
Response Returns a sync job object with status 202 Accepted. The sync runs asynchronously in the background. 
{
  "id": "sync_123",
  "status": "pending",
  "syncable_type": "Family",
  "syncable_id": "456",
  "syncing_at": null,
  "completed_at": null,
  "window_start_date": "2024-01-01",
  "window_end_date": "2024-03-04",
  "message": "Sync has been queued and will apply all active rules"
}
Example Request 
curl -X POST https://your-domain.com/api/v1/sync \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json"

​
Response Fields

​
Sync Behavior

​
Rule Application

Active categorization rules are applied to all transactions during sync. Rules can:
  • Automatically categorize transactions based on merchant names
  • Apply tags based on transaction patterns
  • Set merchants for uncategorized transactions

​
Account Synchronization

Connected accounts are refreshed from their respective providers:
  • Plaid: Fetches latest transactions and balances
  • SimpleFIN: Updates transactions, balances, and investment holdings
  • SnapTrade: Syncs investment accounts and holdings
  • Coinbase: Updates cryptocurrency balances and transactions

​
Transfer Matching

The sync process automatically detects matching transactions between accounts and links them as transfers. Transfers are identified by:
  • Matching amounts (opposite signs)
  • Similar transaction dates
  • Same family accounts

​
Error Responses

{
  "error": "insufficient_scope",
  "message": "This action requires the 'write' scope"
}

{
  "error": "internal_server_error",
  "message": "Error: Sync service unavailable"
}

​
Important Notes

Asynchronous Processing: Sync operations run in the background. The API returns immediately with a sync job ID. You can check the status by monitoring your account data or using webhooks if configured.
Frequency: You can trigger syncs as needed, but be aware that some providers (like Plaid) may have rate limits on how frequently data can be refreshed.
Resource Intensive: Syncing all accounts and applying rules can be resource-intensive for families with many accounts and transactions. The operation may take several minutes to complete.
Automatic Syncs: Sure automatically syncs your data periodically. Manual syncs are useful when:
  • You’ve just added new categorization rules
  • You need the latest transactions immediately
  • You’ve connected a new account
  • You want to force transfer matching

​
Use Cases

​
After Adding Rules

# Create a new categorization rule via web interface
# Then trigger sync to apply it to existing transactions
curl -X POST https://your-domain.com/api/v1/sync \
  -H "X-Api-Key: your_api_key_here"

​
After Connecting Accounts

# Connect a new bank account via Plaid
# Then sync to fetch initial transactions
curl -X POST https://your-domain.com/api/v1/sync \
  -H "X-Api-Key: your_api_key_here"

​
Manual Refresh

# Get the latest data from all providers
curl -X POST https://your-domain.com/api/v1/sync \
  -H "X-Api-Key: your_api_key_here"

Build docs developers (and LLMs) love

Get started for freeTalk to us