PocketSmith API

Introduction

Welcome to the PocketSmith API. The API is available for anyone to use, and it's free. Everyone benefits from the vibrant developer community fostered around PocketSmith, and the excellent ecosystem of tools available to users as a result. Thanks for taking the interest in hacking on PocketSmith.

Go for a test drive

You can check out the API with your own PocketSmith account using the API Explorer. This will give you a good idea of how the endpoints work and what you can do with them.

Authorisation

How you authorise to the PocketSmith API depends on what your tool is and who will use it.

Tools just for me

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. When you make any authenticated request, you'll provide your key in the Authorization header with the Key prefix. For example:

curl --header "Authorization: Key b671bd60e7608fc655da352c4c32a247badb9815be266eab42328d6342287ed04780a8051b90d07108aec7afb0fabac1326c949428a2f18441452de428a6d3fd" https://api.pocketsmith.com/v2/me

To enable the developer keys feature for your PocketSmith account, send us an email on api@pocketsmith.com. You'll find a new menu under Security for managing your keys. You should rotate your keys regularly.

Creating apps

If you want to a create an app for PocketSmith that other PocketSmith users can use, you'll be using OAuth 2.

To register an app with PocketSmith, please email us on api@pocketsmith.com. Let us know a bit about yourself and what you plan on building. When approved, you will be provided with your client_id and client_secret to start using OAuth. Then, check out our guide for integrating OAuth to get started.

We're currently in beta testing

The PocketSmith API is in beta, because we need a little bit of scope to change things up as we find our feet.

  • API endpoints and verbs are subject to change.
  • The API may be unstable. Things might break, such is the nature of a beta. Please report any issues to us.

Our promise to you is that any breaking changes will be communicated well in advance, and we'll work with our developers to ensure a smooth transition if necessary. Once we're happy with it, we'll commit to no further breaking changes and stabilise the API.

Get in touch

We would love to hear from you about your app and how you're using the API, and if you have any suggestions or find any issues. Drop us a line on api@pocketsmith.com.

Errors

The PocketSmith API provides proper HTTP status codes when errors happen. This helps inform the client of the nature of the error without having to examine the response body, which will contain an English error message.

These are the types of errors that should be anticipated from the PocketSmith API:

Name HTTP status code Meaning What you should do
Bad Request 400 The request was invalid or malformed From the error message, find out what was wrong with your request
Unauthorized 401 The access token was missing or invalid Obtain a new access token with OAuth, potentially refreshing your token if it had expired
Not Allowed 403 Not allowed to perform the action, usually due to lack of permission to read or modify the requested resource
Not Found 404 The requested resource was not found Consider the resource to be non-existent, it either never existed or no longer exists
Method Not Allowed 405 The requested resource was valid, but not for the HTTP verb used
Unprocessable Entity 422 A validation error occurred See which field failed validation and remedy the issue. If the data was user-provided, show them the error and have them fix the data
Internal Server Error 500 Something broke on our side We've been alerted to the problem and will be looking into it
Service Unavailable 503 PocketSmith or a dependency are down temporarily for maintenance Try the request again at a later time

Every error listed above will have a JSON response body in the form:

{
  "error": "A nice English error message explaining the problem"
}

OAuth

Errors arising from OAuth will be spec-compliant, which means both an error and error_description field will be present in the response. In these cases, error will be some sort of identifier like invalid_grant, where error_description will be an English explanation of the issue. To know if you're getting an error in OAuth format or a regular PocketSmith error, check for the presence of the error_description field.

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}