294 lines
7.1 KiB
Markdown
294 lines
7.1 KiB
Markdown
# PocketSmith API Documentation (Offline Reference)
|
|
|
|
**API Version:** v2.0
|
|
**Base URL:** `https://api.pocketsmith.com/v2`
|
|
**Documentation Source:** https://developers.pocketsmith.com/
|
|
**Last Updated:** 2025-11-16
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Introduction](#introduction)
|
|
2. [Authentication](#authentication)
|
|
- [Developer Keys](#developer-keys-personal-tools)
|
|
- [OAuth 2.0](#oauth-20-multi-user-apps)
|
|
3. [API Reference](#api-reference)
|
|
- [Users](#users)
|
|
- [Institutions](#institutions)
|
|
- [Accounts](#accounts)
|
|
- [Transaction Accounts](#transaction-accounts)
|
|
- [Transactions](#transactions)
|
|
- [Categories](#categories)
|
|
- [Budgeting](#budgeting)
|
|
- [Supporting Resources](#supporting-resources)
|
|
4. [Common Topics](#common-topics)
|
|
- [Pagination](#pagination)
|
|
- [Error Handling](#error-handling)
|
|
5. [Changelog](#changelog)
|
|
6. [Support](#support)
|
|
|
|
---
|
|
|
|
## Introduction
|
|
|
|
The PocketSmith API is freely available to all developers without restrictions. The platform welcomes developers to build tools and integrations using their services.
|
|
|
|
**Developer Hub:** https://developers.pocketsmith.com/
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
PocketSmith provides two authentication methods depending on your use case.
|
|
|
|
### Developer Keys (Personal Tools)
|
|
|
|
For building personal tools like dashboard widgets or transaction importers, use developer keys.
|
|
|
|
**Configuration:**
|
|
- Manage keys in: Settings > Security within your PocketSmith account
|
|
- **Header:** `X-Developer-Key`
|
|
- **Access:** Persistent API access to your own account
|
|
|
|
**Example Request:**
|
|
```bash
|
|
curl --header "X-Developer-Key: YOUR_KEY_HERE" \
|
|
https://api.pocketsmith.com/v2/me
|
|
```
|
|
|
|
**Supported Languages:**
|
|
- Shell (curl)
|
|
- Node.js
|
|
- JavaScript
|
|
- PHP
|
|
- Python
|
|
|
|
### OAuth 2.0 (Multi-User Apps)
|
|
|
|
To create applications that other PocketSmith users can access, you'll need to use OAuth 2.0.
|
|
|
|
**Setup Process:**
|
|
|
|
1. **Register your application** by contacting the team at [email protected]
|
|
2. **Provide details** about yourself and your planned integration
|
|
3. **Receive credentials:** `client_id` and `client_secret` upon approval
|
|
4. **Implement authentication** using the OAuth integration guide
|
|
|
|
**OAuth Flow:**
|
|
- Standard OAuth 2.0 authorization code flow
|
|
- Detailed integration instructions available in the OAuth documentation section
|
|
|
|
---
|
|
|
|
## API Reference
|
|
|
|
The PocketSmith API v2.0 is organized around the following resource categories:
|
|
|
|
### Users
|
|
|
|
**Endpoints:**
|
|
- Get authorised user
|
|
- Get user by ID
|
|
- Update user information
|
|
|
|
**Example - Get the Authorised User:**
|
|
```
|
|
GET https://api.pocketsmith.com/v2/me
|
|
```
|
|
|
|
**Purpose:** Gets the user that corresponds to the access token used in the request.
|
|
|
|
**Authentication Required:** Yes (Header-based credentials)
|
|
|
|
---
|
|
|
|
### Institutions
|
|
|
|
Manage financial institutions connected to user accounts.
|
|
|
|
**Operations:**
|
|
- Create institution
|
|
- Read institution details
|
|
- Update institution information
|
|
- Delete institution
|
|
- List all institutions within a user account
|
|
|
|
---
|
|
|
|
### Accounts
|
|
|
|
Complete account management functionality.
|
|
|
|
**Operations:**
|
|
- Get account details
|
|
- Update account information
|
|
- Delete account
|
|
- Create new account
|
|
- Manage account ordering within users
|
|
- List accounts by institution
|
|
|
|
---
|
|
|
|
### Transaction Accounts
|
|
|
|
Transaction accounts are the specific accounts where transactions are recorded.
|
|
|
|
**Operations:**
|
|
- Get transaction account details
|
|
- Update transaction account
|
|
- List transaction accounts by user
|
|
|
|
---
|
|
|
|
### Transactions
|
|
|
|
Complete transaction lifecycle management with multi-context querying.
|
|
|
|
**Query Contexts:**
|
|
- By user
|
|
- By account
|
|
- By category
|
|
- By transaction account
|
|
|
|
**Operations:**
|
|
- Create transactions within transaction accounts
|
|
- Read transaction details
|
|
- Update transactions
|
|
- Delete transactions
|
|
- Query and filter transactions
|
|
|
|
---
|
|
|
|
### Categories
|
|
|
|
Manage and organize transaction categories.
|
|
|
|
**Operations:**
|
|
- Category management and organization
|
|
- List user-specific categories
|
|
- Create category rules
|
|
- Update categories
|
|
- Delete categories
|
|
|
|
---
|
|
|
|
### Budgeting
|
|
|
|
Budget management and analysis features.
|
|
|
|
**Features:**
|
|
- Budget retrieval and summaries
|
|
- Trend analysis
|
|
- Forecast cache management
|
|
|
|
---
|
|
|
|
### Supporting Resources
|
|
|
|
Additional resources for comprehensive financial data management:
|
|
|
|
- **Events** - Manage financial events
|
|
- **Attachments** - Attach files to transactions
|
|
- **Labels** - Label and tag transactions
|
|
- **Saved Searches** - Save frequently used search queries
|
|
- **Currencies** - Handle multi-currency support
|
|
- **Time Zones** - Manage timezone settings
|
|
|
|
---
|
|
|
|
## Common Topics
|
|
|
|
### Pagination
|
|
|
|
The API uses pagination for endpoints that return multiple records.
|
|
|
|
**Implementation Details:**
|
|
- Refer to the pagination documentation section for page size limits and navigation
|
|
- Response headers typically include pagination metadata
|
|
|
|
### Error Handling
|
|
|
|
The API returns standard HTTP status codes.
|
|
|
|
**Common Status Codes:**
|
|
- `200 OK` - Successful request
|
|
- `400 Bad Request` - Invalid request parameters
|
|
- `401 Unauthorized` - Authentication failure
|
|
- `403 Forbidden` - Insufficient permissions
|
|
- `404 Not Found` - Resource not found
|
|
- `500 Internal Server Error` - Server error
|
|
|
|
**Error Response Format:**
|
|
Detailed error handling documentation available at: https://developers.pocketsmith.com/docs
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
### v2.0 - Welcome to the new PocketSmith developer hub
|
|
**Posted:** Almost 7 years ago by Regan McEntyre
|
|
|
|
The development team announced an updated documentation portal: "We've given our developer documentation a bit of a spruce up. Come on in and check it out, and let us know what you think!"
|
|
|
|
**Current Status:**
|
|
- API Version 2.0 is the current stable version
|
|
- Interactive API documentation powered by OpenAPI 3 specification
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
**Contact the Development Team:**
|
|
- **Email:** [email protected]
|
|
|
|
**Resources:**
|
|
- **Interactive API Reference:** https://developers.pocketsmith.com/reference
|
|
- **Complete Guides:** https://developers.pocketsmith.com/docs
|
|
- **Changelog:** https://developers.pocketsmith.com/changelog
|
|
|
|
---
|
|
|
|
## Quick Start Guide
|
|
|
|
1. **For Personal Tools:**
|
|
```bash
|
|
# Get your developer key from Settings > Security
|
|
curl --header "X-Developer-Key: YOUR_KEY_HERE" \
|
|
https://api.pocketsmith.com/v2/me
|
|
```
|
|
|
|
2. **For Multi-User Applications:**
|
|
- Email [email protected] to register your app
|
|
- Implement OAuth 2.0 flow once approved
|
|
|
|
3. **Explore the API:**
|
|
- Start with the `/me` endpoint to verify authentication
|
|
- Review the resource categories that match your use case
|
|
- Test endpoints using the interactive reference
|
|
|
|
---
|
|
|
|
## Additional Notes
|
|
|
|
**OpenAPI Specification:**
|
|
The API documentation is built using OpenAPI 3, which means:
|
|
- Interactive testing tools available in the web interface
|
|
- Machine-readable API specifications
|
|
- Auto-generated client libraries possible
|
|
|
|
**Rate Limiting:**
|
|
Check the full documentation for any rate limiting policies.
|
|
|
|
**Best Practices:**
|
|
- Always handle errors gracefully
|
|
- Use pagination for large datasets
|
|
- Cache responses where appropriate
|
|
- Follow OAuth 2.0 best practices for multi-user apps
|
|
|
|
---
|
|
|
|
**End of Documentation**
|
|
|
|
For the most up-to-date information and interactive API testing, visit: https://developers.pocketsmith.com/
|