pocketsmith
Module pocketsmith
API
Definitions
ballerinax/pocketsmith Ballerina library
Overview
PocketSmith is a personal finance and budgeting platform that brings bank accounts, transactions, categories, budgets and cash-flow forecasts together in one place. This connector supports version 2.0 of the PocketSmith API and lets Ballerina applications read and manage that financial data programmatically.
Key features
- Manage users, institutions and accounts, including their transaction accounts and balances
- Create, list, update and delete transactions, with filtering by date, type and review status
- Organise spending with categories and category rules
- Analyse budgets, trends and forecast events for a user or scenario
- Look up supported currencies and time zones
Setup guide
To use the connector you need a PocketSmith account and either a developer key or an OAuth 2.0 access token.
Option 1: Developer key
- Sign in to PocketSmith.
- Open Settings and go to Security & Integrations, then select Manage developer keys.
- Choose Create developer key, give the key a name and copy the generated value. It is shown only once.
Option 2: OAuth 2.0
- Register an application in the PocketSmith developer area to obtain a client ID and client secret.
- Complete the OAuth 2.0 authorization code flow against the PocketSmith authorization and token endpoints to obtain a refresh token.
- Keep the client ID, client secret and refresh token for the connector configuration.
Quickstart
To use the pocketsmith connector in your Ballerina application, update the .bal file as follows:
Step 1: Import the module
import ballerinax/pocketsmith;
Step 2: Instantiate a new connector
Create a Config.toml file with your developer key:
developerKey = "<your-developer-key>"
Then create a client in your .bal file:
configurable string developerKey = ?; final pocketsmith:Client pocketsmithClient = check new ({ auth: { xDeveloperKey: developerKey } });
Step 3: Invoke the connector operation
public function main() returns error? { pocketsmith:User _ = check pocketsmithClient->getAuthorisedUser(); }
Step 4: Run the Ballerina application
bal run
Examples
The PocketSmith connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:
- Monthly budget review - lists a user's accounts and compares forecast and actual spending per category for a date range.
- Uncategorised transaction cleanup - finds uncategorised transactions and optionally assigns them to a chosen category.
Clients
pocketsmith: Client
The PocketSmith API
Constructor
Gets invoked to initialize the connector.
init (ConnectionConfig config, string serviceUrl)- config ConnectionConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://api.pocketsmith.com/v2" - URL of the target service
getAuthorisedUser
Get the authorised user
getUser
Get user
Parameters
- id int - The unique identifier of the user
updateUser
function updateUser(int id, UpdateUserRequest payload, map<string|string[]> headers) returns User|errorUpdate user
Parameters
- id int - The unique identifier of the user
- payload UpdateUserRequest - User settings to update
getInstitution
Get institution
Parameters
- id int - The unique identifier of the institution
Return Type
- Institution|error - The retrieved institution
updateInstitution
function updateInstitution(int id, UpdateInstitutionRequest payload, map<string|string[]> headers) returns Institution|errorUpdate institution
Parameters
- id int - The unique identifier of the institution
- payload UpdateInstitutionRequest - Institution details to update
Return Type
- Institution|error - The updated institution
deleteInstitution
function deleteInstitution(int id, map<string|string[]> headers, *DeleteInstitutionQueries queries) returns error?Delete institution
Parameters
- id int - The unique identifier of the institution
- queries *DeleteInstitutionQueries - Queries to be sent with the request
Return Type
- error? - Success
listUserInstitutions
List institutions in user
Parameters
- id int - The unique identifier of the user
Return Type
- Institution[]|error - The retrieved user institutions
createUserInstitution
function createUserInstitution(int id, CreateInstitutionRequest payload, map<string|string[]> headers) returns Institution|errorCreate institution in user
Parameters
- id int - The unique identifier of the user
- payload CreateInstitutionRequest - Details of the institution to create
Return Type
- Institution|error - The created user institution
getAccount
Get account
Parameters
- id int - The unique identifier of the account
updateAccount
function updateAccount(int id, UpdateAccountRequest payload, map<string|string[]> headers) returns Account|errorUpdate account
Parameters
- id int - The unique identifier of the account
- payload UpdateAccountRequest - Account details to update
deleteAccount
Delete account
Parameters
- id int - The unique identifier of the account
Return Type
- error? - Success
listUserAccounts
List accounts in user
Parameters
- id int - The unique identifier of the user
updateUserAccountsOrder
function updateUserAccountsOrder(int id, UpdateAccountsOrderRequest payload, map<string|string[]> headers) returns Account[]|errorUpdate the display order of accounts in user
Parameters
- id int - The unique identifier of the user
- payload UpdateAccountsOrderRequest - Accounts listed in their new display order
createUserAccount
function createUserAccount(int id, CreateAccountRequest payload, map<string|string[]> headers) returns Account|errorCreate an account in user
Parameters
- id int - The unique identifier of the user
- payload CreateAccountRequest - Details of the account to create
listInstitutionAccounts
List accounts in institution
Parameters
- id int - The unique identifier of the institution
getTransactionAccount
function getTransactionAccount(int id, map<string|string[]> headers) returns TransactionAccount|errorGet transaction account
Parameters
- id int - The unique identifier of the transaction account
Return Type
- TransactionAccount|error - The retrieved transaction account
updateTransactionAccount
function updateTransactionAccount(int id, UpdateTransactionAccountRequest payload, map<string|string[]> headers) returns TransactionAccount|errorUpdate transaction account
Parameters
- id int - The unique identifier of the transaction account
- payload UpdateTransactionAccountRequest - Transaction account details to update
Return Type
- TransactionAccount|error - The updated transaction account
listUserTransactionAccounts
function listUserTransactionAccounts(int id, map<string|string[]> headers) returns TransactionAccount[]|errorList transaction accounts in user
Parameters
- id int - The unique identifier of the user
Return Type
- TransactionAccount[]|error - The retrieved user transaction accounts
getTransaction
Get a transaction
Parameters
- id int - The unique identifier of the transaction
Return Type
- Transaction|error - The retrieved transaction
updateTransaction
function updateTransaction(int id, UpdateTransactionRequest payload, map<string|string[]> headers) returns UpdateTransactionResponse|errorUpdate a transaction
Parameters
- id int - The unique identifier of the transaction
- payload UpdateTransactionRequest - Transaction details to update, optionally with splits
Return Type
- UpdateTransactionResponse|error - Success. When splits are provided, the response includes both the updated transaction and the newly created split transactions
deleteTransaction
Delete transaction
Parameters
- id int - The unique identifier of the transaction
Return Type
- error? - Success
listUserTransactions
function listUserTransactions(int id, map<string|string[]> headers, *ListUserTransactionsQueries queries) returns Transaction[]|errorList transactions in user
Parameters
- id int - The unique identifier of the user
- queries *ListUserTransactionsQueries - Queries to be sent with the request
Return Type
- Transaction[]|error - The retrieved user transactions
listAccountTransactions
function listAccountTransactions(int id, map<string|string[]> headers, *ListAccountTransactionsQueries queries) returns Transaction[]|errorList transactions in account
Parameters
- id int - The unique identifier of the account
- queries *ListAccountTransactionsQueries - Queries to be sent with the request
Return Type
- Transaction[]|error - The retrieved account transactions
listCategoryTransactions
function listCategoryTransactions(string id, map<string|string[]> headers, *ListCategoryTransactionsQueries queries) returns Transaction[]|errorList transactions in categories
Parameters
- id string - A comma-separated list of category IDs
- queries *ListCategoryTransactionsQueries - Queries to be sent with the request
Return Type
- Transaction[]|error - The retrieved category transactions
listTransactionAccountTransactions
function listTransactionAccountTransactions(int id, map<string|string[]> headers, *ListTransactionAccountTransactionsQueries queries) returns Transaction[]|errorList transactions in transaction account
Parameters
- id int - The unique identifier of the transaction account
- queries *ListTransactionAccountTransactionsQueries - Queries to be sent with the request
Return Type
- Transaction[]|error - The retrieved transaction account transactions
createTransactionAccountTransaction
function createTransactionAccountTransaction(int id, CreateTransactionRequest payload, map<string|string[]> headers) returns Transaction|errorCreate a transaction in transaction account
Parameters
- id int - The unique identifier of the transaction account
- payload CreateTransactionRequest - Details of the transaction to create
Return Type
- Transaction|error - The created transaction account transaction
getCategory
Get category
Parameters
- id int - The unique identifier of the category
updateCategory
function updateCategory(int id, UpdateCategoryRequest payload, map<string|string[]> headers) returns Category|errorUpdate category
Parameters
- id int - The unique identifier of the category
- payload UpdateCategoryRequest - Category details to update
deleteCategory
Delete category
Parameters
- id int - The unique identifier of the category
Return Type
- error? - Success
listUserCategories
List categories in user
Parameters
- id int - The unique identifier of the user
createUserCategory
function createUserCategory(int id, CreateCategoryRequest payload, map<string|string[]> headers) returns Category|errorCreate category in user
Parameters
- id int - The unique identifier of the user
- payload CreateCategoryRequest - Details of the category to create
listUserCategoryRules
List category rules in user
Parameters
- id int - The unique identifier of the user
Return Type
- CategoryRule[]|error - The retrieved user category rules
createCategoryRule
function createCategoryRule(int id, CreateCategoryRuleRequest payload, map<string|string[]> headers) returns CategoryRule|errorCreate category rule in category
Parameters
- id int - The unique identifier of the category
- payload CreateCategoryRuleRequest - Details of the category rule to create
Return Type
- CategoryRule|error - The created category rule
getUserBudget
function getUserBudget(int id, map<string|string[]> headers, *GetUserBudgetQueries queries) returns BudgetAnalysisPackage[]|errorList budget for user
Parameters
- id int - The unique identifier of the account
- queries *GetUserBudgetQueries - Queries to be sent with the request
Return Type
- BudgetAnalysisPackage[]|error - The retrieved user budget
getUserBudgetSummary
function getUserBudgetSummary(int id, map<string|string[]> headers, *GetUserBudgetSummaryQueries queries) returns BudgetAnalysisPackage[]|errorGet budget summary for user
Parameters
- id int - The unique identifier of the user
- queries *GetUserBudgetSummaryQueries - Queries to be sent with the request
Return Type
- BudgetAnalysisPackage[]|error - The retrieved user budget summary
getUserTrendAnalysis
function getUserTrendAnalysis(int id, map<string|string[]> headers, *GetUserTrendAnalysisQueries queries) returns BudgetAnalysisPackage[]|errorGet trend analysis for user
Parameters
- id int - The unique identifier of the user
- queries *GetUserTrendAnalysisQueries - Queries to be sent with the request
Return Type
- BudgetAnalysisPackage[]|error - The retrieved user trend analysis
deleteUserForecastCache
Delete forecast cache for user
Parameters
- id int - The unique identifier of the user
Return Type
- error? - Success
getEvent
Get event
Parameters
- id string - The unique identifier of the event
updateEvent
function updateEvent(string id, UpdateEventRequest payload, map<string|string[]> headers) returns Event|errorUpdate event
Parameters
- id string - The unique identifier of the event
- payload UpdateEventRequest - Event details to update
deleteEvent
function deleteEvent(string id, map<string|string[]> headers, *DeleteEventQueries queries) returns error?Delete event
Parameters
- id string - The unique identifier of the event
- queries *DeleteEventQueries - Queries to be sent with the request
Return Type
- error? - Success
listUserEvents
function listUserEvents(int id, map<string|string[]> headers, *ListUserEventsQueries queries) returns Event[]|errorList events in user.
Parameters
- id int - The unique identifier of the user
- queries *ListUserEventsQueries - Queries to be sent with the request
listScenarioEvents
function listScenarioEvents(int id, map<string|string[]> headers, *ListScenarioEventsQueries queries) returns Event[]|errorList events in scenario.
Parameters
- id int - The unique identifier of the scenario
- queries *ListScenarioEventsQueries - Queries to be sent with the request
createScenarioEvent
function createScenarioEvent(int id, CreateEventRequest payload, map<string|string[]> headers) returns Event|errorCreate event in scenario
Parameters
- id int - The unique identifier of the scenario
- payload CreateEventRequest - Details of the event to create
getAttachment
Get attachment
Parameters
- id int - The unique identifier of the attachment
Return Type
- Attachment|error - The retrieved attachment
updateAttachment
function updateAttachment(int id, UpdateAttachmentRequest payload, map<string|string[]> headers) returns Attachment|errorUpdate attachment
Parameters
- id int - The unique identifier of the attachment
- payload UpdateAttachmentRequest - Attachment details to update
Return Type
- Attachment|error - The updated attachment
deleteAttachment
Delete attachment
Parameters
- id int - The unique identifier of the attachment
Return Type
- error? - Success
listUserAttachments
function listUserAttachments(int id, map<string|string[]> headers, *ListUserAttachmentsQueries queries) returns Attachment[]|errorLists attachments in user
Parameters
- id int - The unique identifier of the user
- queries *ListUserAttachmentsQueries - Queries to be sent with the request
Return Type
- Attachment[]|error - The retrieved user attachments
createUserAttachment
function createUserAttachment(int id, CreateAttachmentRequest payload, map<string|string[]> headers) returns Attachment|errorCreate attachment in user
Parameters
- id int - The unique identifier of the user
- payload CreateAttachmentRequest - Attachment file and metadata to create
Return Type
- Attachment|error - The created user attachment
listTransactionAttachments
function listTransactionAttachments(int id, map<string|string[]> headers) returns Attachment[]|errorList attachments in transaction
Parameters
- id int - The unique identifier of the transaction
Return Type
- Attachment[]|error - The retrieved transaction attachments
assignTransactionAttachment
function assignTransactionAttachment(int id, AssignAttachmentRequest payload, map<string|string[]> headers) returns Attachment|errorAssigns attachment to transaction
Parameters
- id int - The unique identifier of the transaction
- payload AssignAttachmentRequest - Identifier of the attachment to assign to the transaction
Return Type
- Attachment|error - The attachment assigned to the transaction
unassignTransactionAttachment
function unassignTransactionAttachment(int transactionId, int attachmentId, map<string|string[]> headers) returns error?Unassigns attachment in transaction
Parameters
- transactionId int - The unique identifier of the transaction
- attachmentId int - The unique identifier of the attachment
Return Type
- error? - Success
listUserLabels
List labels in user
Parameters
- id int - The unique identifier of the user
listUserSavedSearches
List saved searches in user
Parameters
- id int - The unique identifier of the user
Return Type
- SavedSearch[]|error - The retrieved user saved searches
listCurrencies
List currencies
getCurrency
Get currency
Parameters
- id string - The unique identifier of the currency
listTimeZones
List time zones
Records
pocketsmith: Account
Fields
- safeBalance? decimal - The current safe balance, if safe balance is activated on the account. If safe balance is not activated, then null is returned
- currentBalanceInBaseCurrency? decimal - The current balance of the account in the user's base currency
- createdAt? string - When the account was created
- scenarios? Scenario[] - All scenarios that compose the account, including the primary
- title? string - The title of the account
- 'type? "bank"|"credits"|"cash"|"stocks"|"mortgage"|"loans"|"vehicle"|"property"|"insurance"|"other_asset"|"other_liability" - The type of the account
- currencyCode? string - The currency code for the account
- updatedAt? string - When the account was last updated
- currentBalanceDate? string - The date of the current balance
- currentBalanceExchangeRate? decimal - The exchange rate between the account's currency and the user's base currency, when different. If the currencies are the same, null is returned
- transactionAccounts? TransactionAccount[] - All transaction accounts that compose the account, including the primary
- currentBalance? decimal - The current balance of the account
- safeBalanceInBaseCurrency? decimal - The current safe balance in the user's base currency, if safe balance is activated on the account. If safe balance is not activated, then null is returned
- id? int - The unique identifier of the account
- primaryTransactionAccount? TransactionAccount -
- primaryScenario? Scenario -
- isNetWorth? boolean - Whether the account is a net worth asset
pocketsmith: ApiKeysConfig
Provides API key configurations needed when communicating with a remote HTTP endpoint.
Fields
- xDeveloperKey string - If you want to build a tool just for yourself, be it a desktop widget to display your balances or a tool to import transactions from a bank without a bank feed, you can use our developer keys feature. You can issue yourself a key which will give you persistent API access to just your account. You should rotate your keys regularly.
pocketsmith: AssignAttachmentRequest
Fields
- attachmentId? int - The unique identifier of the attachment
pocketsmith: Attachment
Fields
- contentType? string - The content type of the attachment
- updatedAt? string - When the attachment was last updated
- contentTypeMeta? AttachmentContentTypeMeta -
- originalUrl? string - The url of the attachment
- fileName? string - The file name of the attachment
- createdAt? string - When the attachment was created
- id? int - The unique identifier of the attachment
- variants? AttachmentVariants -
- title? string - The title of the attachment. If blank or not provided, the title will be derived from the file name
- 'type? string - The type of attachment
pocketsmith: AttachmentContentTypeMeta
Fields
- extension? string - The extension type of the attachment
- description? string - The content type description of the attachment
- title? string - The content type title of the attachment
pocketsmith: AttachmentVariants
Fields
- thumbUrl? string - The url of the thumb version of the attachment
- largeUrl? string - The url of the large version of the attachment
pocketsmith: BudgetAnalysis
Fields
- endDate? string - The end date of the budget analysis
- averageForecastAmount? decimal - The average budgeted amount across all periods
- periods? Period[] - The period analyses that this budget analysis comprises
- totalOverBy? decimal - The total amount the budget was exceeded across all periods
- totalActualAmount? decimal - The total actual (transactions) amount across all periods
- averageActualAmount? decimal - The average actual (transactions) amount across all periods
- totalForecastAmount? decimal - The total budgeted amount across all periods
- currencyCode? string - The currency of the budget analysis
- startDate? string - The start date of the budget analysis
- totalUnderBy? decimal - The total amount the budget was under by across all periods
pocketsmith: BudgetAnalysisPackage
Fields
- income? BudgetAnalysis -
- isTransfer? boolean - Whether the expense budget analysis looks like a transfer to the income budget analysis, based on a number of heuristics
- category? Category -
- expense? BudgetAnalysis -
pocketsmith: Category
Fields
- colour? string - The colour for the category
- updatedAt? string - When the category was last updated
- children? Category[] - The category's child categories
- parentId? int - The unique identifier of the parent category of this category, or null if this category has no parent (i.e. is a top-level category)
- isBill? boolean - Whether the category is a bill category. A bill category is when budgeted amounts are normally spent at once, instead of spread across a budgeting period. This category will be included in the bill reminder email when set to true
- isTransfer? boolean - Whether this category has been marked as a transfer category
- rollUp? boolean - Whether the category's budget is rolled up into its parent category, if a parent category is present
- createdAt? string - When the category was created
- id? int - The unique identifier of the category
- title? string - The title of the category
- refundBehaviour? "debits_are_deductions"|"credits_are_refunds"? - How the category's refunds or deductions should be reported on
pocketsmith: CategoryRule
Fields
- updatedAt? string - When the category rule was last updated
- createdAt? string - When the category rule was created
- id? int - The unique identifier of the category rule
- category? Category -
- payeeMatches? string - The keyword/s to match the transactions payees
pocketsmith: ConnectionConfig
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth BearerTokenConfig|OAuth2RefreshTokenGrantConfig|ApiKeysConfig - Provides Auth configurations needed when communicating with a remote HTTP endpoint.
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 30) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded/x-forwardedheader
- followRedirects? FollowRedirects - Configurations associated with Redirection
- poolConfig? PoolConfiguration - Configurations associated with request pooling
- cache CacheConfig(default {}) - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding) header
- circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig? RetryConfig - Configurations associated with retrying
- cookieConfig? CookieConfig - Configurations associated with cookies
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- secureSocket? ClientSecureSocket - SSL/TLS-related options
- proxy? ProxyConfig - Proxy server related options
- socketConfig ClientSocketConfig(default {}) - Provides settings related to client socket configuration
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
- laxDataBinding boolean(default true) - Enables relaxed data binding on the client side. When enabled,
nilvalues are treated as optional, and absent fields are handled asnilabletypes. Enabled by default.
pocketsmith: CreateAccountRequest
Fields
- title string - A title for the account
- 'type "bank"|"credits"|"cash"|"loans"|"mortgage"|"stocks"|"vehicle"|"property"|"insurance"|"other_asset"|"other_liability" - The type of the account
- currencyCode string - A currency code for the account
- institutionId int - The ID of the institution to create this account in
pocketsmith: CreateAttachmentRequest
Fields
- fileName? string - The file name of the attachment
- title? string - The title of the attachment. If the title is blank or not provided, the title will derived from the file name
- fileData? string - The base64-encoded contents of the source file. The supported file types are png, jpg, pdf, xls, xlsx, doc, docx
pocketsmith: CreateCategoryRequest
Fields
- colour? string - A CSS-style hex colour for the category
- parentId? int - The unique identifier of a category to be the parent of this category
- isBill? boolean - Set the category as a bill category
- isTransfer? boolean - Set the category as a transfer category
- rollUp? boolean - Set the category to be rolled up into its parent category
- title string - A title for the category
- refundBehaviour? "debits_are_deductions"|"credits_are_refunds"? - Set the refund behaviour of the category
pocketsmith: CreateCategoryRuleRequest
Fields
- applyToAll? boolean - Apply the created category rule to all transactions
- applyToUncategorised? boolean - Apply the created category rule to all uncategorised transactions
- payeeMatches string - The keyword/s to match the transaction payees
pocketsmith: CreateEventRequest
Fields
- date string - The starting date of the event
- note? string - A note for the event
- amount decimal - The amount of the event. A positive amount is a credit, and a negative amount is a debit
- categoryId int - The unique identifier of the category for the event
- repeatType "once"|"daily"|"weekly"|"fortnightly"|"monthly"|"yearly"|"each weekday" - The repeat type of the event
- repeatInterval int(default 1) - The repeat interval of the event
pocketsmith: CreateInstitutionRequest
Fields
- title string - A title for the institution
- currencyCode string - A currency code for the institution
pocketsmith: CreateTransactionRequest
Fields
- payee string - The payee/merchant of the transaction
- date string - The date when the transaction occurred
- needsReview? boolean - Whether the transaction needs to be reviewed or not
- note? string - A note for the transaction
- amount decimal - The amount of the transaction (signed). A positive amount is a credit, and a negative amount is a debit
- categoryId? int - The unique identifier of a category for the transaction
- chequeNumber? string - A cheque number for the transaction
- isTransfer? boolean - Whether the transaction should be indicated as a transfer
- memo? string - A memo for the transaction
- labels? string - A set of comma-separated labels for the transaction
pocketsmith: Currency
Fields
- symbol? string - The symbol of the currency
- name? string - The name of the currency
- id? string - The ISO 4217 or unofficial currency code
- minorUnit? int - The number of digits after the minor unit separator
- separators? CurrencySeparators -
pocketsmith: CurrencySeparators
Fields
- major? string - The separator used in the major unit
- minor? string - The seperator used for the minor unit
pocketsmith: DeleteEventQueries
Represents the Queries record for the operation: deleteEvent
Fields
- behaviour "one"|"forward"|"all" - Whether the delete applies only to this event, to all events within the series from this event or to all events within the series
pocketsmith: DeleteInstitutionQueries
Represents the Queries record for the operation: deleteInstitution
Fields
- mergeIntoInstitutionId? int - The unique identifier of the institution to merge into
pocketsmith: Event
Fields
- date? string - The date of the event
- note? string - The note of the event
- seriesStartId? string - The unique identifier of the series followed by the series's start date
- amount? decimal - The amount of the event
- repeatType? "once"|"daily"|"weekly"|"fortnightly"|"monthly"|"yearly"|"each weekday" - The repeat type of the event
- infiniteSeries? boolean - Whether the event repeats and does not have an end date
- amountInBaseCurrency? decimal - The amount of the event in the user's base currency
- currencyCode? string - The currency code of the event
- seriesId? int - The unique identifier of the series that the event belongs to
- colour? string - The CSS hex-style colour of the event
- scenario? Scenario -
- repeatInterval? int - The repeat interval of how often the event takes place
- id? string - The unique identifier of the event
- category? Category -
pocketsmith: GetUserBudgetQueries
Represents the Queries record for the operation: getUserBudget
Fields
- rollUp? boolean - Whether parent categories should have their children rolled up into them. When used, the children will still appear in the collection on their own, but their actual and forecast figures will be rolled up to the root parent
pocketsmith: GetUserBudgetSummaryQueries
Represents the Queries record for the operation: getUserBudgetSummary
Fields
- endDate string - The date to stop analysing the budget from. This will be bumped out to make full periods as necessary
- period "weeks"|"months"|"years"|"event" - The period to analyse in, one of
weeks,monthsoryears. Also supported isevent, although event period analysis is only possible when the budget events gathered align, so in this case where all categories are analysed together, it's highly unlikely that event period analysis will be possible
- interval int - The period interval, e.g. if the interval is 2 and the period is weeks, the budget will be analysed fortnightly
- startDate string - The date to start analysing the budget from. This will be bumped out to make full periods as necessary
pocketsmith: GetUserTrendAnalysisQueries
Represents the Queries record for the operation: getUserTrendAnalysis
Fields
- endDate string - The date to stop analysing the budget from. This will be bumped out to make full periods as necessary
- period "weeks"|"months"|"years"|"event" - The period to analyse in, one of
weeks,monthsoryears. Also supported isevent, although event period analysis is only possible when the budget events gathered align, so in this case where all categories are analysed together, it's highly unlikely that event period analysis will be possible
- interval int - The period interval, e.g. if the interval is 2 and the period is weeks, the budget will be analysed fortnightly
- categories string - A comma-separated list of category IDs to analyse
- scenarios string - A comma-separated list of scenario IDs to analyse. You're likely going to want to include all a user's scenarios here, unless you have reason to only analyse for a subset of scenarios. Regardless of what scenarios are analysed, all actuals (transactions) across all accounts will be included
- startDate string - The date to start analysing the budget from. This will be bumped out to make full periods as necessary
pocketsmith: Institution
Fields
- updatedAt? string - When the institution was last updated
- createdAt? string - When the institution was created
- id? int - The unique identifier of the institution
- title? string - The title of the institution
- currencyCode? string - The currency code of the institution
pocketsmith: ListAccountTransactionsQueries
Represents the Queries record for the operation: listAccountTransactions
Fields
- endDate? string - Limit to transactions on or before this date. Required if start_date is provided. If not provided, defaults to today's date
- needsReview? int - Limit to transactions that need to be reviewed
- search? string - Limit to transactions matching a keyword search string. The provided string is matched against the transaction amount, account name, payee, category title, note, labels, and the date in ISO 8601 format
- uncategorised? int - Limit to uncategorised transactions
- updatedSince? string - Limit to transactions updated since an ISO 8601 timestamp
- page? int - Choose a particular page of the results
- 'type? "debit"|"credit" - Limit to transactions of this type
- startDate? string - Limit to transactions on or after this date. Required if end_date is provided. If not provided, defaults to the furtherest date allowed by the user's subscription
pocketsmith: ListCategoryTransactionsQueries
Represents the Queries record for the operation: listCategoryTransactions
Fields
- endDate? string - Limit to transactions on or before this date. Required if start_date is provided. If not provided, defaults to today's date
- needsReview? int - Limit to transactions that need to be reviewed
- search? string - Limit to transactions matching a keyword search string. The provided string is matched against the transaction amount, account name, payee, category title, note, labels, and the date in ISO 8601 format
- uncategorised? int - Limit to uncategorised transactions
- updatedSince? string - Limit to transactions updated since an ISO 8601 timestamp
- page? int - Choose a particular page of the results
- 'type? "debit"|"credit" - Limit to transactions of this type
- startDate? string - Limit to transactions on or after this date. Required if end_date is provided. If not provided, defaults to the furtherest date allowed by the user's subscription
pocketsmith: ListScenarioEventsQueries
Represents the Queries record for the operation: listScenarioEvents
Fields
- endDate string - Return the events until and including this date
- startDate string - Return the events from and including this date
pocketsmith: ListTransactionAccountTransactionsQueries
Represents the Queries record for the operation: listTransactionAccountTransactions
Fields
- endDate? string - Limit to transactions on or before this date. Required if start_date is provided. If not provided, defaults to today's date
- needsReview? int - Limit to transactions that need to be reviewed
- search? string - Limit to transactions matching a keyword search string. The provided string is matched against the transaction amount, account name, payee, category title, note, labels, and the date in ISO 8601 format
- uncategorised? int - Limit to uncategorised transactions
- updatedSince? string - Limit to transactions updated since an ISO 8601 timestamp
- page? int - Choose a particular page of the results
- 'type? "debit"|"credit" - Limit to transactions of this type
- startDate? string - Limit to transactions on or after this date. Required if end_date is provided. If not provided, defaults to the furtherest date allowed by the user's subscription
pocketsmith: ListUserAttachmentsQueries
Represents the Queries record for the operation: listUserAttachments
Fields
- unassigned? int - If set, returns unassigned attachments, that are available for assigning to a transaction
pocketsmith: ListUserEventsQueries
Represents the Queries record for the operation: listUserEvents
Fields
- endDate string - Return the events until and including this date
- startDate string - Return the events from and including this date
pocketsmith: ListUserTransactionsQueries
Represents the Queries record for the operation: listUserTransactions
Fields
- endDate? string - Limit to transactions on or before this date. Required if start_date is provided. If not provided, defaults to today's date
- needsReview? int - Limit to transactions that need to be reviewed
- search? string - Limit to transactions matching a keyword search string. The provided string is matched against the transaction amount, account name, payee, category title, note, labels, and the date in ISO 8601 format
- uncategorised? int - Limit to uncategorised transactions
- updatedSince? string - Limit to transactions updated since an ISO 8601 timestamp
- page? int - Choose a particular page of the results
- 'type? "debit"|"credit" - Limit to transactions of this type
- startDate? string - Limit to transactions on or after this date. Required if end_date is provided. If not provided, defaults to the furtherest date allowed by the user's subscription
pocketsmith: OAuth2RefreshTokenGrantConfig
OAuth2 Refresh Token Grant Configs
Fields
- Fields Included from *OAuth2RefreshTokenGrantConfig
- refreshUrl string(default "https://api.pocketsmith.com/v2/oauth/access_token") - Refresh URL
pocketsmith: Period
Fields
- endDate? string - The end date of the period
- current? boolean - Whether this period is current, such that the current date (in the user's time zone) falls within the date range
- overBudget? boolean - Whether the budget has been exceeded in the period
- overBy? decimal - How much the budget has been exceeded by in the period
- forecastAmount? decimal - The sum of all forecast sources (budget events) in the period, for comparison against the actual amount
- percentageUsed? decimal - The percentage of the budget that has been used in the period
- actualAmount? decimal - The sum of all actuals (transactions) in the period
- refundAmount? decimal - This attribute tracks the amount that has been refunded or deducted to the actual amount. When a category is set to "always expense", any credit transactions are treated as refunds and when set to "always income", any debit transactions are treated as deductions
- underBudget? boolean - Whether the budget has not been exceeded in the period
- currencyCode? string - The currency of the period
- underBy? decimal - How much there is left in the budget for the period
- startDate? string - The start date of the period
pocketsmith: SavedSearch
Fields
- updatedAt? string - When the saved search was last updated
- createdAt? string - When the saved search was created
- id? int - The unique identifier of the saved search
- title? string - The title of the saved search
pocketsmith: Scenario
Fields
- closingBalanceDate? string - The date of the closing balance
- safeBalance? decimal - The current safe balance in the user's base currency, if safe balance is activated on the account associated with the scenario. If safe balance is not activated, then null is returned
- minimumValue? decimal -
- currentBalanceInBaseCurrency? decimal - The current balance of the scenario in the user's base currency
- description? string - A short description of what the scenario is modelling
- createdAt? string - When the scenario was created
- title? string - The title of the scenario
- 'type? "no-interest"|"savings"|"debt" - The type of the scenario
- startingBalance? decimal - The starting balance of the scenario
- startingBalanceDate? string - The date of the starting balance
- maximumValue? decimal -
- currentBalanceDate? string - The date of the current balance
- currentBalanceExchangeRate? decimal - The exchange rate between the scenario's currency and the user's base currency, when different. If the currencies are the same, null is returned
- updatedAt? string - When the scenario was last updated
- closingBalance? decimal - The closing balance of the scenario
- interestRate? decimal - The amount of interest to apply to the balance. Will apply periodically depending on what
interest_rate_repeat_idis set to
- interestRateRepeatId? int - A number representing how often the interest should be applied. 0 is used for no interest, 2 is weekly, 3 is fortnightly, 4 is monthly, 5 is yearly and 7 for quarterly
- currentBalance? decimal - The current balance of the scenario
- safeBalanceInBaseCurrency? decimal - The current safe balance in the user's base currency, if safe balance is activated on the account associated with the scenario. If safe balance is not available, then null is returned
- id? int - The unique identifier of the scenario
- achieveDate? string - For goals, the date that they should be achieved by
pocketsmith: TimeZone
Fields
- utcOffset? int - The time zone's UTC offset in seconds
- identifier? string - The tz database name of the time zone
- formattedOffset? string - The formatted offset of the time zone
- name? string - The name of the time zone
- abbreviation? string - The abbreviation of the time zone
- formattedName? string - The formatted name of the time zone
pocketsmith: Transaction
Fields
- date? string - The date the transaction took place
- note? string -
- amount? decimal -
- chequeNumber? string -
- transactionAccount? TransactionAccount -
- originalPayee? string - The payee the transaction was created with
- uploadSource? string - Where the transaction came from
- memo? string -
- isTransfer? boolean - Whether the transaction is a transfer
- createdAt? string - When the transaction was created
- amountInBaseCurrency? decimal - The amount of the transaction in the user's base currency
- 'type? "debit"|"credit" - Whether the transaction is a debit or a credit
- labels? string[] -
- payee? string - The payee/merchant of the transaction
- needsReview? boolean - Whether the transaction needs to be reviewed
- updatedAt? string - When the transaction was last updated
- closingBalance? decimal - The closing balance of the account at the transaction
- id? int - The unique identifier of the transaction
- category? Category -
- status? "pending"|"posted" - The status of the transaction. Pending transactions are temporary and may be superseded later by their posted counterparts, which are permanent
pocketsmith: TransactionAccount
Fields
- safeBalance? decimal - The current safe balance, if safe balance is activated and available for the transaction account. If safe balance is not available, then null is returned
- currentBalanceInBaseCurrency? decimal - The current balance of the transaction account in the user's base currency
- createdAt? string -
- 'type? "bank"|"credits"|"cash"|"stocks"|"mortgage"|"loans"|"vehicle"|"property"|"insurance"|"other_asset"|"other_liability" - The type of the transaction account
- startingBalance? decimal -
- currencyCode? string - The currency that the account is in. This is determined by the account that the transaction account belongs to
- number? string -
- startingBalanceDate? string -
- institution? Institution -
- currentBalanceDate? string -
- currentBalanceExchangeRate? decimal - The exchange rate between the transaction account's currency and the user's base currency, when different. If the currencies are the same, null is returned
- updatedAt? string -
- name? string -
- currentBalance? decimal -
- safeBalanceInBaseCurrency? decimal - The current safe balance in the user's base currency, if safe balance is activated and available for the transaction account. If safe balance is not available, then null is returned
- id? int -
pocketsmith: TransactionSplit
Fields
- payee? string - The payee for this split transaction. If not provided, inherits from the parent transaction
- date? string - The date for this split transaction. If not provided, defaults to the parent transaction's date
- amount decimal - The amount for this split transaction
- categoryId? int - The category ID for this split transaction. If not provided, inherits from the parent transaction
- isTransfer? boolean - Whether this split transaction should be indicated as a transfer
pocketsmith: TransactionSplitsResponse
Response when splits are provided
Fields
- splitTransactions Transaction[] -
- 'transaction Transaction -
pocketsmith: UpdateAccountRequest
Fields
- title? string - A new title for the account
- 'type? "bank"|"credits"|"cash"|"loans"|"mortgage"|"stocks"|"vehicle"|"property"|"insurance"|"other_asset"|"other_liability" - The type of the account
- currencyCode? string - A new currency code for the account
- isNetWorth? boolean - Whether the account is a net worth account
pocketsmith: UpdateAccountsOrderRequest
Fields
- accounts Account[] - List the account objects in their new display order
pocketsmith: UpdateAttachmentRequest
Fields
- title? string - The new title of the attachment. If the title is blank or not provided, the server will derive a title from the file name
pocketsmith: UpdateCategoryRequest
Fields
- colour? string - A new CSS-style hex colour for the category
- parentId? int - The unique identifier of a parent category for the category, making this category a child of that category
- isBill? boolean - Set the category as a bill category
- isTransfer? boolean - Set the category as a transfer category
- rollUp? boolean - Set the category to be rolled up into its parent category
- title? string - A new title for the category
- refundBehaviour? "debits_are_deductions"|"credits_are_refunds"? - Set the refund behaviour of the category
pocketsmith: UpdateEventRequest
Fields
- note? string - A note for the event
- amount? decimal - The amount of the event. A positive amount is a credit, and a negative amount is a debit
- repeatType? "once"|"daily"|"weekly"|"fortnightly"|"monthly"|"yearly"|"each weekday" - The repeat type of the event
- behaviour "one"|"forward"|"all" - Whether the update applies only to this event, to all events within the series from this event or to all events within the series
- repeatInterval? int - The repeat interval of the event
pocketsmith: UpdateInstitutionRequest
Fields
- title? string - A new title for the institution
- currencyCode? string - A new currency code for the institution
pocketsmith: UpdateTransactionAccountRequest
Fields
- startingBalanceDate? string - The starting balance date of the transaction account
- startingBalance? decimal - The starting balance amount of the transaction account
- institutionId? int - The unique identifier of a new institution for the transaction account
pocketsmith: UpdateTransactionRequest
Fields
- payee? string - A new payee for the transaction
- date? string - A new date for the transaction
- needsReview? boolean - Whether the transaction needs to be reviewed or not
- note? string - A new note for the transaction
- amount? decimal - The amount of the transaction (signed). A positive amount is a credit, and a negative amount is a debit
- splits? TransactionSplit[] - Split this transaction into multiple transactions. The correctly calculated remainder amount parameter must be provided, which is equal to the amount - sum(split_amounts). Splitting is atomic: all splits are validated before the original transaction and any splits are saved
- categoryId? int - The unique identifier of a new category for the transaction. Sending an empty string will uncategorize the transaction
- chequeNumber? string - A new cheque number for the transaction
- memo? string - A new memo for the transaction
- isTransfer? boolean - Whether the transaction is a transfer or not
- labels? string - A new comma-separated set of labels for the transaction
pocketsmith: UpdateUserRequest
Fields
- alwaysShowBaseCurrency? boolean - Whether the user wishes to have all monetary values converted to their base currency
- weekStartDay? int - The day of the week the user wishes their calendars to start on. A number between 0 and 6, where 0 is Sunday and 6 is Saturday
- name? string - A new name for the user
- betaUser? boolean - Whether the user is a beta user, and wishes to try out new features
- timeZone? string - A new time zone for the user
- baseCurrencyCode? string - A new base currency code for the user
pocketsmith: User
Fields
- forecastLastAccessedAt? string - When the user's forecast was last accessed
- availableBudgets? int - The user's total number of available budgets
- weekStartDay? int - The day of the week the user wishes their calendars to start on. A number between 0 and 6, where 0 is Sunday and 6 is Saturday
- betaUser? boolean - Whether the user has opted in to beta features
- forecastStartDate? string - The date that the user's forecast starts
- createdAt? string - When the user signed up
- forecastDeferRecalculate? boolean - Whether the user's forecast recalculation should be deferred
- login? string - The user's username
- timeZone? string - The user's time zone
- forecastEndDate? string - The date that the user's forecast ends
- lastLoggedInAt? string - When the user last logged into PocketSmith
- alwaysShowBaseCurrency? boolean - Whether the user wants to see all accounts in their base currency instead of the native account currency
- avatarUrl? string - The URL to the user's avatar
- updatedAt? string - When the user was last updated
- lastActivityAt? string - When the user last interacted with PocketSmith, via any application or the API
- name? string - The full name of the user, although not all users will have a name set
- forecastLastUpdatedAt? string - When the user's forecast was last updated
- usingMultipleCurrencies? boolean - Whether the user has multiple currencies in use across their account
- availableAccounts? int - The user's total number of available accounts
- id? int - The unique identifier of the user
- forecastNeedsRecalculate? boolean - Whether the user's forecast needs to be recalculated
- baseCurrencyCode? string - The user's base currency
- email? string - The user's email address
- isReviewingTransactions? boolean - Whether the user wants to review new transactions, transfer transactions or categorisation
Union types
pocketsmith: UpdateTransactionResponse
UpdateTransactionResponse
Import
import ballerinax/pocketsmith;Metadata
Released date: about 15 hours ago
Version: 2.0.0
License: Apache-2.0
Security
Direct vulnerabilities: No known direct vulnerabilities
Indirect vulnerabilities:
Checked on 2026-11-20 via OSV.dev
Compatibility
Platform: any
Ballerina version: 2201.12.0
GraalVM compatible: Yes
Pull count
Total: 43
Current verison: 1
Weekly downloads
Keywords
Vendor/PocketSmith
Area/Finance & Accounting
Type/Connector
PocketSmith
Contributors