1. Overview & Architecture

Direct headless ingestion for scripts, mobile shortcuts, and bank webhooks.

SpendScout’s Developer API lets you record transactions programmatically from external software without navigating through web forms or managing session cookies. Every transaction ingested via the developer key immediately propagates through your personal dashboard, category spending budgets, and analytical models.

Immediate Ledger Sync

Transactions appear immediately in real-time feeds, graphs, and category velocity gauges.

Auto Account Reconciliation

Supplying an account_id automatically subtracts the amount from your live balance.

Isolated Key Scope

Your key is restricted to financial recording and cannot alter passwords or billing plans.

2. Key Generation & Lifecycle

Managing your secret key from the SpendScout Settings panel.

Open Settings (/account) in your SpendScout web app.
Navigate to the Developer API tab.
Click Generate Developer Key. Your secret key prefixed with sk_live_... will appear.
Save your key securely: The raw token is displayed only once. Subsequent visits show a masked format (sk_live_•••••••841f).
Revoke or Regenerate: If a key is accidentally committed to a public repository, click Regenerate to immediately invalidate it and issue a new token without downtime.

Security Best Practice: Never embed your developer secret key in client-side mobile apps or public GitHub repositories. Always inject it via environment variables (SPENDSCOUT_API_KEY).

3. Authentication Header

Required HTTP headers for automated requests.

All developer automation requests must supply the X-Api-Key header containing your active secret key:

HTTP Headers

bash

X-Api-Key: sk_live_your_secret_key_here

Content-Type: application/json

4. Automation Endpoint

Direct REST URL and execution behavior for headless expense records.

POST/api/v1/expenses/automation

Requires X-Api-Key

This endpoint processes your JSON payload, verifies that your developer key is active and associated with a valid account, updates linked financial account balances, recalculates category budgets, and immediately broadcasts changes to your dashboard.

5. Parameters & Payload Schema

Comprehensive field breakdown and interactive request/response models.

Request Parameters

Field	Type	Requirement	Description
title	string	Required	Merchant or transaction name (e.g. "Uber", "Starbucks").
amount	number	Required	Positive decimal amount (> 0).
category	string	Required	Must match one of the standard SpendScout categories below.
sub_category	string	Optional	Granular grouping (e.g. "Coffee", "Groceries", "Fuel").
payment_mode	string	Optional	"UPI", "Card", "Bank", or "Cash" (Defaults to "UPI").
account_id	integer	Optional	Account to automatically debit balance from.
date	ISO string	Optional	ISO 8601 date. Defaults to current timestamp.
description	string	Optional	Additional notes or memo.

Sample Request PayloadPOST

request.json

json

1	{
2	"title": "Starbucks Coffee",
3	"amount": 350.00,
4	"category": "Food & Dining",
5	"sub_category": "Coffee",
6	"payment_mode": "UPI",
7	"account_id": 1,
8	"description": "Latte with extra shot"
9	}

Sample Response Body201 Created

response.json

json

1	{
2	"id": 142,
3	"user_id": 7,
4	"title": "Starbucks Coffee",
5	"amount": 350.0,
6	"category": "Food & Dining",
7	"sub_category": "Coffee",
8	"payment_mode": "UPI",
9	"account_id": 1,
10	"date": "2026-10-19T09:15:00",
11	"description": "Latte with extra shot"
12	}

6. Supported Categories

Ensure the category parameter matches one of these labels.

Food & Dining

Transportation

Shopping

Entertainment

Bills & Utilities

Health & Fitness

Travel

Education

Personal Care

Gifts & Donations

Investments

Other

7. Ready-to-use Code Recipes

Copy-paste snippets with full syntax highlighting.

terminal_quickstart.sh

bash

1	curl -X POST "https://api.spendscout.tech/api/v1/expenses/automation" \
2	-H "X-Api-Key: sk_live_YOUR_KEY_HERE" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"title": "Supermarket Groceries",
6	"amount": 1450.50,
7	"category": "Food & Dining",
8	"sub_category": "Groceries",
9	"payment_mode": "Card",
10	"account_id": 1,
11	"description": "Weekly grocery restocking"
12	}'

8. Apple iOS Shortcuts & Bank SMS Automation

Automatically parse banking notifications to log transactions hands-free.

Create a Personal Automation in iOS Shortcuts

Open the Shortcuts app on iOS → tap the Automation tab → choose New Automation → select Message.

Set Trigger Conditions

Set Message Contains to "debited" or "spent", set sender to your Bank notification ID (e.g. HDFCBK, SBIBNK, ICICIB), and enable Run Immediately.

Extract Amount with Regex

Add the action Match Text using regex Rs\.?\s?([0-9,.]+) to isolate the transaction amount from the SMS body.

Dispatch HTTP Webhook

Add Get Contents of URL with:

URL: https://api.spendscout.tech/api/v1/expenses/automation
Method: POST
Header: X-Api-Key: sk_live_...
Request Body: JSON with parsed amount, merchant title, and default category.

9. Status & Error Codes

Standard HTTP status codes returned by the automation endpoints.

201 Created

Success

Transaction was ingested and account balances were deducted successfully.

401 Unauthorized

Invalid API Key

Missing or revoked X-Api-Key header.

422 Unprocessable

Validation Error

Missing required fields (e.g. title or amount) or amount is zero / negative.

SpendScout REST API Reference