Creating a Budget

The SPENDiD Budgets service was created to automate the tedious and time-consuming data gathering, math and validation tasks in the budgeting process.

Simply provide us with some basic demographic information and any known fixed expenses you have available and we'll fill in the rest to create a realistic budget.

curl --request POST \
  --url https://api.spendid.io/v1.0/budgets/generate \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-key: your_api_key'

Add demographic profile to request

Creating a Budget requires at least some basic demographic information. SPENDiD requires as little as zip code and net take-home income. The other options for demographic inputs only serve to make the Budget even more personalized and accurate -- let's add that now.

curl --request POST \
  --url https://api.spendid.io/v1.0/budgets/generate \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-key: your_api_key' \
  --data '{
  "demographics": {
    "age": 25,
    "gross_annual_income": 50000,
    "household_members": 1,
    "is_homeowner": false,
    "net_annual_income": 41004,
    "zip": "35210"
  }
}'

For more information on demographic models, check out the demographic model reference.

{
  "budget": {
    "food_home": 3625,
    "food_out": 2610,
    "alcoholic_beverages": 505,
    "mortgage_and_rent": 6553,
    "home_maintenance_and_repairs": 1044,
    "other_lodging": 520,
    "natural_gas": 350,
    "electricity": 1319,
    "heating_fuels_other": 91,
    "residential_phone_service": 182,
    "cellular_phone_service": 1061,
    "water_and_public_services": 504,
    "household_operations": 904,
    "housekeeping_supplies": 504,
    "furniture_and_appliances": 1634,
    "clothing_items_and_services": 1342,
    "vehicle_purchase_and_lease": 3865,
    "gasoline": 1843,
    "vehicle_maintenance_and_repairs": 748,
    "vehicle_insurance": 1002,
    "public_and_other_transportation": 533,
    "health_insurance": 2810,
    "medical_services": 755,
    "prescription_drugs": 443,
    "medical_supplies": 160,
    "fees_and_admissions": 393,
    "media_hardware_and_services": 920,
    "pets": 533,
    "toys_and_hobbies": 165,
    "personal_care": 606,
    "reading": 84,
    "education": 686,
    "tobacco_and_smoking": 333,
    "miscellaneous": 893,
    "cash_contributions": 1228,
    "life_and_personal_insurance": 257,
    "savings": 0,
    "other_debt_payments": 0
  }
}

SPENDiD Budgets returns an annual budget calculated for your net_annual_income and demographics.

Some notes on baseline responses:

  • Budget amounts are rounded to the nearest $1.
  • Budget amounts are annual.
  • SPENDiD budgets never lose money by default. We assume a fixed value of $0 annual savings if the request doesn't provide an explicit value.
  • SPENDiD assumes $0 "other_debt_payments" if none are explicitly provided.

📘

Why annual values?

Although many apps focus on monthly or biweekly income and billing cycles, there is significant variance between consumers and households.

SPENDiD inputs and outputs are always expressed annually to keep integrations simple while maximizing flexibility for downstream developers.

Convert values however you wish in your application.

  • val * (1/12) = monthly
  • val * (1/24) = semi-monthly
  • val * (1/26) = biweekly
  • val * (1/52) = weekly
  • val * (1/365) = daily

Add some expense constraints

To add fixed expenses to a request, just populate a budget object with what you know -- SPENDiD Budgets will fill out the rest.

For example, we'll use

  • $800 / month rent payment (800 * 12 = 9600)
  • $250 / month vehicle lease (250 * 12 = 3000)
  • $200 / month savings goal (200 * 12 = 2400)
  • No ongoing education expenses
  • No smoking
  • No prescription drug costs
  • Employer provided health insurance - already factored in net_annual_income
{
  "demographics": {
    "age": 25,
    "gross_annual_income": 50000,
    "household_members": 1,
    "is_homeowner": false,
    "net_annual_income": 41004,
    "zip": "35210"
  },
  "budget": {
    "mortgage_and_rent": 9600,
    "vehicle_purchase_and_lease": 3000,
    "savings": 2400,
    "tobacco_and_smoking": 0,
    "education": 0,
    "health_insurance": 0,
    "prescription_drugs": 0
  }
}

The Budgets service returns a complete budget for net_annual_income that respects the explicit expenses of the request based on the underlying demographics behavioral model.

{
  "budget": {
    "food_home": 3582,
    "food_out": 2579,
    "alcoholic_beverages": 499,
    "mortgage_and_rent": 9600,
    "home_maintenance_and_repairs": 1032,
    "other_lodging": 514,
    "natural_gas": 346,
    "electricity": 1304,
    "heating_fuels_other": 90,
    "residential_phone_service": 180,
    "cellular_phone_service": 1049,
    "water_and_public_services": 498,
    "household_operations": 894,
    "housekeeping_supplies": 498,
    "furniture_and_appliances": 1614,
    "clothing_items_and_services": 1326,
    "vehicle_purchase_and_lease": 3000,
    "gasoline": 1822,
    "vehicle_maintenance_and_repairs": 739,
    "vehicle_insurance": 991,
    "public_and_other_transportation": 526,
    "health_insurance": 0,
    "medical_services": 746,
    "prescription_drugs": 0,
    "medical_supplies": 158,
    "fees_and_admissions": 389,
    "media_hardware_and_services": 910,
    "pets": 526,
    "toys_and_hobbies": 163,
    "personal_care": 598,
    "reading": 83,
    "education": 0,
    "tobacco_and_smoking": 0,
    "miscellaneous": 883,
    "cash_contributions": 1213,
    "life_and_personal_insurance": 254,
    "savings": 2400,
    "other_debt_payments": 0
  }
}

SPENDiD Budget responses always return the core budget object. Developers are free to incorporate this object "as-is" or transform the output to fit your system.