{
  "openapi": "3.0.3",
  "info": {
    "title": "Bookkeeping Helper API",
    "version": "1.5.1",
    "description": "Bank statement PDF or text to transactions and CSV with a balance check, expense totals and monthly budgets. Turn a text-based bank or card statement PDF (or pasted statement text) into dated transactions, a CSV and a balance reconciliation (date order and number format are detected or set; card layouts and skipped lines are reported), optionally with rule-based categories and category totals, total expenses by category, month and share with a CSV, and total a monthly budget into spending, savings rate and money remaining. Limits: PDFs must contain real text, because scans and photos are refused with a 422 (OCR is not supported); bank layouts differ, so check the reconciliation; categories are generic keywords plus your own rules, not a merchant database. Nothing you send is stored. One X-API-Key header authenticates every call, and the same key works across every FreeDailyPro API. Every 4xx response is documented and none of them is billed.",
    "contact": {
      "name": "FreeDailyPro",
      "url": "https://www.freedailypro.com/developers",
      "email": "support@freedailypro.com"
    },
    "termsOfService": "https://www.freedailypro.com/terms",
    "x-logo": {
      "url": "https://www.freedailypro.com/favicon.ico"
    }
  },
  "servers": [
    {
      "url": "https://api.freedailypro.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer hub, plans and MCP setup",
    "url": "https://www.freedailypro.com/developers"
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "tags": [
    {
      "name": "Bookkeeping",
      "description": "Bank statement PDF or text to transactions and CSV with a balance check, expense totals and monthly budgets."
    }
  ],
  "paths": {
    "/v1/business/expenses": {
      "post": {
        "summary": "Total expenses and break them down by category, month and share",
        "operationId": "businessExpenses",
        "description": "Send items, each { category, amount } with an optional date (YYYY-MM-DD) and description. Returns total, byCategory (the original answer: the sum per category exactly as sent), count, categories (a list sorted by total with count and sharePct of the net total), a CSV of the category table, and, when any item has a date, byMonth totals (YYYY-MM) and undatedItems. A refund is a negative amount and reduces its category. mergeCategories:true treats categories that differ only in case or surrounding spaces as one (the first spelling is kept); by default categories are used exactly as sent. Limits: it totals what you send; it does not read receipts, convert currencies, keep a ledger or categorise by itself (use bank-statement-to-csv with categorize or categoryRules for that). Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Bookkeeping"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "category": {
                          "type": "string"
                        },
                        "amount": {
                          "type": "number"
                        },
                        "date": {
                          "description": "Optional date, YYYY-MM-DD. When any item has one, the response adds byMonth totals.",
                          "type": "string",
                          "pattern": "^\\d{4}-\\d{2}-\\d{2}"
                        },
                        "description": {
                          "description": "Optional note; not used in the totals.",
                          "type": "string",
                          "maxLength": 200
                        }
                      },
                      "required": [
                        "category",
                        "amount"
                      ],
                      "additionalProperties": false
                    },
                    "description": "The expenses to total. A refund is a negative amount."
                  },
                  "mergeCategories": {
                    "description": "true treats categories that differ only in case or surrounding spaces as one. Default false (exactly as sent).",
                    "type": "boolean"
                  }
                },
                "required": [
                  "items"
                ],
                "additionalProperties": false
              },
              "example": {
                "items": [
                  {
                    "category": "Software",
                    "amount": 129,
                    "date": "2026-09-02"
                  },
                  {
                    "category": "Travel",
                    "amount": 480.5,
                    "date": "2026-10-11"
                  },
                  {
                    "category": "Software",
                    "amount": 49,
                    "date": "2026-10-20"
                  }
                ]
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Expense tracker client and server side from freedailypro",
                  "result": {
                    "total": 658.5,
                    "byCategory": {
                      "Software": 178,
                      "Travel": 480.5
                    },
                    "count": 3,
                    "categories": [
                      {
                        "category": "Travel",
                        "total": 480.5,
                        "count": 1,
                        "sharePct": 72.97
                      },
                      {
                        "category": "Software",
                        "total": 178,
                        "count": 2,
                        "sharePct": 27.03
                      }
                    ],
                    "csv": "Category,Count,Total,Share %\nTravel,1,480.50,72.97\nSoftware,2,178.00,27.03"
                  }
                }
              }
            }
          },
          "400": {
            "description": "items is missing or an item has no category or a non-numeric amount; the body says which Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/planning/monthly-budget": {
      "post": {
        "summary": "Total a monthly budget and return spending, savings and remaining money",
        "operationId": "planningMonthlyBudget",
        "description": "Send 'income' (monthly) and 'expenses', each { name, amount }. As in the first version, 'spent' is the sum of the expenses, 'remaining' is income less spent and 'savingsRatePct' is remaining as a share of income. B-0136 adds two optional fields on each expense. 'kind' is need, want, savings or debt (a REQUIRED debt payment such as a card or loan minimum, which counts in the needs bucket of the 50/30/20 view; send only the minimum as debt and any extra as savings). 'period' is month (default) or year: a yearly amount counts as amount / 12 a month, which is how a sinking fund for an annual bill (insurance, gifts, car repairs) shows up in a monthly budget. When any expense uses kind or period, 'spent' is the sum of the monthly amounts and the response adds 'plan': needs (debt included), wants, saved, debt, yearlySetAside, spending (needs + wants), leftOver, 'lines' (each with its kind, the bucket it counts in, entered amount and monthly amount) and a 'steps' array that shows the working. Without kind or period the response is exactly the first version. Who calls it: budgeting and personal-finance apps, bank and fintech onboarding flows, financial-wellness programmes, and chatbots or MCP agents. Worked example: {\"income\":3500,\"expenses\":[{\"name\":\"Rent\",\"amount\":1200,\"kind\":\"need\"},{\"name\":\"Car insurance\",\"amount\":1200,\"kind\":\"need\",\"period\":\"year\"},{\"name\":\"Card minimum\",\"amount\":250,\"kind\":\"debt\"},{\"name\":\"Streaming\",\"amount\":50,\"kind\":\"want\"},{\"name\":\"Savings\",\"amount\":300,\"kind\":\"savings\"}]} returns plan.needs 1550 (1200 + 100 for the yearly insurance + 250 debt), wants 50, saved 300, debt 250, yearlySetAside 100 and leftOver 1600. Integration scenario: an app lists a user's bills, flags the annual ones as per year and shows how much to set aside each month and what is really left over. The 50/30/20 rule (about 50% needs, 30% wants, 20% savings) is a common rule of thumb, not advice; nothing is stored. A kind other than need, want, savings or debt, a period other than month or year, or a negative or non-numeric amount when kind or period is used is rejected with a 400. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Bookkeeping"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "income": {
                    "type": "number"
                  },
                  "expenses": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "amount": {
                          "type": "number"
                        },
                        "kind": {
                          "description": "50/30/20 bucket: need, want, savings, or debt (a required debt payment, counted in needs). When no expense has a kind the site's name-based guess is used for plan, and without kind or period on any expense the response is the first version.",
                          "type": "string",
                          "enum": [
                            "need",
                            "want",
                            "savings",
                            "debt"
                          ]
                        },
                        "period": {
                          "description": "month (default) or year: a yearly amount counts as amount / 12 a month (a sinking fund for an annual bill).",
                          "type": "string",
                          "enum": [
                            "month",
                            "year"
                          ]
                        }
                      },
                      "required": [
                        "name",
                        "amount"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "required": [
                  "income",
                  "expenses"
                ],
                "additionalProperties": false
              },
              "example": {
                "income": 5200,
                "expenses": [
                  {
                    "name": "Rent",
                    "amount": 1850
                  },
                  {
                    "name": "Groceries",
                    "amount": 520
                  },
                  {
                    "name": "Transport",
                    "amount": 210
                  },
                  {
                    "name": "Subscriptions",
                    "amount": 65
                  }
                ]
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Monthly budget planner client and server side from freedailypro",
                  "result": {
                    "income": 5200,
                    "spent": 2645,
                    "remaining": 2555,
                    "savingsRatePct": 49.13,
                    "expenses": [
                      {
                        "name": "Rent",
                        "amount": 1850
                      },
                      {
                        "name": "Groceries",
                        "amount": 520
                      },
                      {
                        "name": "Transport",
                        "amount": 210
                      },
                      "..."
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "A missing income, an unknown kind or period, or a negative or non-numeric expense amount (when kind or period is used); the body says which Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/business/bank-statement-to-csv": {
      "post": {
        "summary": "Turn a bank statement (text-based PDF or pasted text) into transactions, CSV and a balance check",
        "operationId": "businessBankStatementToCsv",
        "description": "Send the statement as a text-based PDF or as pasted text and get dated transactions, a CSV, the opening and closing balances found, and a reconciliation that checks the rows against the printed balances. Three ways to send it: JSON with text; JSON with fileBase64 (the PDF, base64 encoded); or multipart/form-data with the PDF under the field file (plus the other options as form fields). A PDF can be up to 20 MB and 100 pages. For a PDF the text and its positions are read from the file and rebuilt into lines, then the same parser reads them; the response adds source {type, pages, characters}, and includeText:true returns the lines that were read as extractedText. year fills in dates that print no year; dateOrder (auto, mdy, dmy) and numberFormat (auto, us for 1,234.56, eu for 1.234,56) are detected unless set; flipSigns reverses signs for card statements that print purchases as positive. categorize:true adds a category to each row from a short list of generic keywords, and categoryRules (your own {match, category} pairs, first match wins) apply before them; either one adds a category column to the CSV, a category on every transaction and categoryTotals (moneyOut, moneyIn, net and count per category). The categories are rule-based, not a merchant database: unmatched rows are Uncategorized, so check them. Limits: statements whose PDF has no text layer (scans and photos) are refused with a 422 because OCR is not supported; password-protected PDFs are refused; layouts differ a lot between banks, so check the reconciliation and skippedLines, and a PDF from which no transaction could be read returns a 422 with a hint instead of an empty result. No statement is stored. Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Bookkeeping"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "description": "The statement as pasted text. Send this, or a PDF in fileBase64 (or as the multipart field file).",
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 2000000
                  },
                  "fileBase64": {
                    "description": "A text-based PDF statement, base64 encoded, up to 20 MB and 100 pages. Scanned or photographed PDFs are refused with a 422: there is no OCR.",
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 28000000
                  },
                  "year": {
                    "type": "integer",
                    "minimum": 1990,
                    "maximum": 2100
                  },
                  "dateOrder": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "mdy",
                      "dmy"
                    ]
                  },
                  "numberFormat": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "us",
                      "eu"
                    ]
                  },
                  "flipSigns": {
                    "type": "boolean"
                  },
                  "categorize": {
                    "description": "true adds a category to every row from a short list of generic keywords (not a merchant database). Default false.",
                    "type": "boolean"
                  },
                  "categoryRules": {
                    "description": "Your own rules: a row whose description contains match (any case) gets that category; the first matching rule wins, before the built-in keywords.",
                    "maxItems": 200,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "match": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100
                        },
                        "category": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 60
                        }
                      },
                      "required": [
                        "match",
                        "category"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "includeText": {
                    "description": "true adds the lines read from the PDF to the response as extractedText, to see what the parser saw.",
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "text": "Date Description Amount Balance\n10/01 Opening balance 2,500.00\n10/03 GROCERY MART #14 -62.18 2,437.82\n10/05 PAYROLL ACME INC 1,950.00 4,387.82\n10/09 CITY POWER -118.40 4,269.42",
                "year": 2026,
                "dateOrder": "mdy",
                "numberFormat": "us"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Bank statement to CSV client and server side from freedailypro",
                  "result": {
                    "transactions": [
                      {
                        "date": "2026-10-03",
                        "description": "GROCERY MART #14",
                        "amount": -62.18,
                        "balance": 2437.82,
                        "signGuess": false
                      },
                      {
                        "date": "2026-10-05",
                        "description": "PAYROLL ACME INC",
                        "amount": 1950,
                        "balance": 4387.82,
                        "signGuess": false
                      },
                      {
                        "date": "2026-10-09",
                        "description": "CITY POWER",
                        "amount": -118.4,
                        "balance": 4269.42,
                        "signGuess": false
                      }
                    ],
                    "openingBalance": 2500,
                    "closingBalance": null,
                    "dateOrder": "mdy",
                    "numberFormat": "us",
                    "cardLayout": false,
                    "skippedLines": [],
                    "reconciliation": {
                      "basis": "balances",
                      "ok": true,
                      "total": 1769.42,
                      "mismatchedRows": [],
                      "difference": null,
                      "message": "All 3 running balances follow from the rows."
                    },
                    "csv": "Date,Description,Amount,Balance\n2026-10-03,GROCERY MART #14,-62.18,2437.82\n2026-10-05,PAYROLL ACME INC,1950,4387.82\n2026-10-09,CITY POWER,-118.4,4269.42"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Neither text nor a PDF was sent, both were sent, an option is invalid, or the PDF is over 20 MB or 100 pages; the body says which Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "422": {
            "description": "The PDF cannot be read: it is a scan or photo with no text layer (OCR is not supported), password-protected, damaged, not a PDF, or no transactions could be recognised in its text; the body says which Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    }
  }
}