Getting started overview

This guide provides a structured approach to initiating interaction with YNAB, focusing on account creation, obtaining necessary credentials, and executing an initial API request to confirm connectivity. The process begins with establishing a user account, which includes a free trial period. Subsequently, developers can generate a Personal Access Token (PAT) required for authenticating API calls. The guide then outlines the steps for making a basic API request, demonstrating how to retrieve a list of budgets associated with the account.

YNAB offers a public API that uses OAuth2 for authentication and provides RESTful endpoints for programmatic access to financial data. This allows for building custom integrations, automating tasks, or extending YNAB's functionality. Understanding the foundational steps outlined here is essential for any further development or integration efforts.

Quick reference table

Step What to do Where
1. Create Account Sign up for a new YNAB account or log in to an existing one. YNAB Pricing Page
2. Generate Token Create a Personal Access Token (PAT) for API authentication. YNAB Account Settings > Developer Settings
3. Make Request Execute a GET request to a YNAB API endpoint using your PAT. Local development environment (e.g., cURL, Postman)
4. Verify Response Confirm the API returns expected data (e.g., list of budgets). Local development environment (console output)

Create an account and get keys

Before interacting with the YNAB API, a YNAB account is required. New users can begin with a 34-day free trial. After the trial, continued access requires a paid subscription, priced at $14.99 per month or $99 per year. Once an account is established, the next step involves generating a Personal Access Token (PAT), which serves as your API key.

Account creation

  1. Navigate to the YNAB website pricing page.
  2. Select 'Start Your Free Trial' or 'Sign Up'.
  3. Follow the prompts to enter your email address and create a password.
  4. Confirm your email address if required.
  5. Complete the initial setup steps within the YNAB application, such as creating your first budget.

Generating a Personal Access Token

A Personal Access Token (PAT) is a long-lived token that grants access to your YNAB data via the API. It is crucial to handle this token securely, as it provides programmatic control over your financial information.

  1. Log in to your YNAB account.
  2. Click on your account name in the top left corner, then select 'My Account'.
  3. In the account settings, navigate to the 'Developer Settings' or a similar section related to API access. The exact naming may vary slightly based on UI updates.
  4. Look for an option to 'Generate New Token' or 'Create Personal Access Token'.
  5. Provide a descriptive name for your token (e.g., 'My Integration App').
  6. Click 'Generate'. The token will be displayed once. Copy it immediately, as it will not be shown again for security reasons. If lost, you will need to generate a new one.
  7. Store your PAT securely. It should be treated like a password and not hardcoded directly into public repositories or shared insecurely.

Your first request

With your YNAB account active and a Personal Access Token generated, you can now make your first API call. This example demonstrates fetching a list of your budgets using the /budgets endpoint. This confirms that your PAT is correctly configured and that you can successfully authenticate with the YNAB API.

API Endpoint

The base URL for the YNAB API is https://api.youneedabudget.com/v1. All requests should be made to this base URL, followed by the specific endpoint path.

Authentication Header

All authenticated requests to the YNAB API require an Authorization header with the format Bearer YOUR_PERSONAL_ACCESS_TOKEN.

Example Request: Fetch Budgets

You can use a command-line tool like cURL or a programmatic approach in your preferred language to make this request. The following example uses cURL to retrieve a list of budgets.

Using cURL

curl -X GET \
  'https://api.youneedabudget.com/v1/budgets' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'

Replace YOUR_PERSONAL_ACCESS_TOKEN with the actual token you generated. A successful response will return a JSON object containing an array of your budgets. Each budget object will include details such as its ID, name, and last modified date.

Example Successful Response Structure

{
  "data": {
    "budgets": [
      {
        "id": "<budget_id_1>",
        "name": "My First Budget",
        "last_modified_on": "2026-05-29T10:00:00Z",
        "first_month": "2026-01-01",
        "last_month": "2026-12-01",
        "date_format": {
          "format": "MM/DD/YYYY"
        },
        "currency_format": {
          "iso_code": "USD",
          "decimal_digits": 2,
          "decimal_separator": ".",
          "symbol_first": true,
          "group_separator": ",",
          "currency_symbol": "$",
          "display_symbol": true
        }
      },
      {
        "id": "<budget_id_2>",
        "name": "Savings Goals Budget",
        "last_modified_on": "2026-05-28T15:30:00Z",
        "first_month": "2026-03-01",
        "last_month": "2026-10-01",
        "date_format": {
          "format": "MM/DD/YYYY"
        },
        "currency_format": {
          "iso_code": "USD",
          "decimal_digits": 2,
          "decimal_separator": ".",
          "symbol_first": true,
          "group_separator": ",",
          "currency_symbol": "$",
          "display_symbol": true
        }
      }
    ],
    "server_knowledge": 12345
  }
}

Common next steps

After successfully making your first API call, consider the following common next steps to further your integration with YNAB:

  • Explore other endpoints: Refer to the YNAB API documentation to discover endpoints for managing accounts, transactions, categories, and payees. This allows for a deeper interaction with your budget data.
  • Implement OAuth2 flow: For applications that will be used by multiple YNAB users, migrating from a Personal Access Token to a full OAuth2 authorization flow is recommended. This enables users to grant and revoke access to their YNAB data without sharing their PAT. The YNAB API supports standard OAuth2 client applications.
  • Build a client library: Depending on your programming language, consider developing a client library or wrapper around the YNAB API to simplify interactions and handle common tasks like authentication and error handling.
  • Webhooks for real-time updates: Investigate YNAB's webhook capabilities to receive real-time notifications about changes in your budget, such as new transactions or modifications to existing ones. This can be crucial for applications requiring up-to-date data.
  • Error handling and rate limiting: Implement robust error handling for API responses and familiarize yourself with YNAB's rate limiting policies to ensure your application behaves responsibly and handles unexpected situations gracefully.
  • Data synchronization strategies: For applications that maintain local copies of YNAB data, develop strategies for efficient data synchronization, using fields like server_knowledge to fetch only changed data.

Troubleshooting the first call

If your initial API request does not return the expected data or results in an error, consider the following troubleshooting steps:

  • Check Personal Access Token (PAT):
    • Correctness: Ensure the PAT copied into the Authorization header is exactly as generated, without any leading or trailing spaces or characters.
    • Expiration (unlikely for PATs, but possible for OAuth tokens): While PATs typically do not expire, if you are using a token obtained via OAuth, verify its validity period.
    • Revocation: Confirm the PAT has not been accidentally revoked in your YNAB account settings.
  • Verify Authorization Header Format: The header must be Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN. A common mistake is missing 'Bearer' or incorrect spacing.
  • Endpoint URL Accuracy: Double-check the API endpoint URL for typos. Ensure it starts with https://api.youneedabudget.com/v1/ and the specific resource path (e.g., budgets).
  • Network Connectivity: Confirm your development environment has stable internet access and is not blocked by a firewall or proxy from reaching api.youneedabudget.com.
  • HTTP Method: Ensure you are using the correct HTTP method (e.g., GET for retrieving data). Sending a POST or PUT to a GET-only endpoint will result in an error.
  • Review API Documentation: Consult the official YNAB API documentation for specific error codes and their meanings. Common HTTP status codes include:
    • 401 Unauthorized: Indicates an issue with the authentication token.
    • 404 Not Found: The requested resource does not exist or the URL is incorrect.
    • 429 Too Many Requests: You have exceeded the API's rate limits. Implement exponential backoff for retries.
  • Use a REST Client: Tools like Postman or Insomnia can help construct and test API requests more easily, providing clear visibility into headers, body, and responses.
  • Check YNAB Status Page: Occasionally, API issues may stem from YNAB's side. Check the YNAB status page for any ongoing service disruptions or maintenance.