How to use the API (the docs!) - 18F/snap-js-api-prototype GitHub Wiki

API documentation

This prototype SNAP API calculates a household's estimated eligibility for the SNAP program. The API accepts inputs about a household and returns:

  • an estimate of that household's SNAP eligibility
  • an estimated benefit amount
  • an explanation of the logic behind the API's decision-making
  • a link to a state website where a household could apply for SNAP

Note that not all U.S. states are well-supported by the prototype API at this stage. States are being added one-by-one, based on partnership interest and other factors.

Example query

const inputs = {
    court_ordered_child_support_payments: 0
    dependent_care_costs: 0
    homeowners_insurance_and_taxes: 0
    household_includes_elderly_or_disabled: false
    household_size: 2
    medical_expenses_for_elderly_or_disabled: 0
    monthly_job_income: 1200
    monthly_non_job_income: 300
    rent_or_mortgage: 1900
    resources: 700
    state_or_territory: "VA"
    use_emergency_allotment: true
    utility_allowance: "NONE"
};

const response = new SnapAPI.SnapEstimateEntrypoint(inputs).calculate();

Table of Contents

Inputs (summary):

Inputs (detail):

household_size (integer, required)

The number of people in the household.

state_or_territory (string, required)

The U.S. Postal Abbreviation of the household's state or U.S. territory.

DEV NOTE: Handling of codes for territories is currently inconsistent and needs to be fixed.

household_includes_elderly_or_disabled (boolean, required)

Does the household include any household members who are 60 years of age or over, or who meet the SNAP criteria for disability?

Boolean values can be sent in as strings in the following format: "true", "false".

monthly_job_income (integer, required)

Monthly earned income in dollars from sources such as a job or self-employment.

monthly_non_job_income (integer, required)

Monthly income in dollars from sources non-job sources as Social Security, disability, Child Support, Worker's Comp, Unemployment, Pension Income, or other sources.

resources (integer, required)

Total household assets in dollars.

DEV NOTE: Some states have no asset limit. For other states, asset amounts are an important component of eligibility determination. This field may move from required to required-on-a-per-state-basis in the near future.

dependent_care_costs (integer, optional)

Monthly dependent care costs in dollars.

medical_expenses_for_elderly_or_disabled (integer, optional)

Monthly cost of medical expenses for elderly or disabled household members in dollars.

Send 0 or do not send any value for this field if household_includes_elderly_or_disabled == False.

court_ordered_child_support_payments (integer, optional)

Monthly cost of court-ordered child support payments in dollars.

rent_or_mortgage (integer, optional)

Monthly rent or mortgage payment costs in dollars.

homeowners_insurance_and_taxes (integer, optional)

Monthly costs of homeowners insurance and property taxes, in dollars.

utility_allowance (string, optional)

The utility allowance claimed by the household, if the household is in a state or territory that uses mandatory Standard Utility Allowances.

If a utility allowance value is provided, it must be one of the following

  • 'HEATING_AND_COOLING'
  • 'BASIC_LIMITED_ALLOWANCE'
  • 'SINGLE_UTILITY_ALLOWANCE'
  • 'ELECTRICITY'
  • 'GAS_AND_FUEL'
  • 'PHONE'
  • 'SEWAGE'
  • 'TRASH'
  • 'WATER'
  • 'NONE'

Sending an explicit value of 'NONE' is treated the same as sending no value for this field.

See "Standard Utility Allowances" from USDA for more information.

use_emergency_allotment (boolean, optional)

Is the household in a state or territory that is currently using SNAP Emergency Allotment amounts?

If no value is provided, the API will use its most recent available data on which states are using emergency allotments.

The API trusts the client about whether or not Emergency Allotments are in effect.

Boolean values can be sent in as strings in the following format: "true", "false".

Outputs (example output):

{
  'status': 'OK',
  'eligible': true,
  'estimated_monthly_benefit': 355,
  'state_website':'https://abe.illinois.gov/abe/access/',
  'use_emergency_allotment': true,
  'eligibility_factors': [
    {
      name: "Gross Income"
      result: 0
      sort_order: 0
      explanation: [
        "We find gross income by adding up monthly income from both job and non-job sources.",…
      ]
    }
    ...
    {
      name: "Net Income Test",
      result: true,
      sort_order: 3,
      explanation: [
        "To be eligible for SNAP, a household's net income needs to be below the net monthly income limit.",…
      ]
    }
    ...
  ]
}

Outputs (summary):

Outputs (details):

  • status (string)

    • "OK": Request handled successfully by API.
    • "ERROR": API encountered one or more errors in handling the request.

  • eligible (boolean)

    • true: Household likely eligible for SNAP benefits.
    • false: Household likely ineligible for SNAP benefits.

  • estimated_monthly_benefit (integer)

Estimated monthly SNAP benefit for household, in dollars.

  • state_website (string)

URL for the state or territorial website where a household can apply for SNAP benefits, or, if no such website exists, link to a page with more information about how to apply for SNAP benefits.

  • use_emergency_allotment (boolean)

Did the API use an emergency allotment amount in calculating its results?

  • eligibility_factors (array)

Experimental feature. This is an array of objects that explain the different factors involved in the final eligibility estimate and estimated benefit amount. See below for the shape of each object in the array.

  • eligibility_factor (object)

    • name: Name of the factor.
    • sort_order: Order in which to logically display the factor.
    • result: A boolean or integer result for this factor. (Boolean results for test such as "Gross Income Test" or "Net Income Test", integers for factors such as "Gross Income" or "Net Income".)
    • explanation: An array of sentences (strings) that explain the logic and math behind this factor. Each sentence in the array represents a line or paragraph.
    • type: One of "test", "income", or "amount".
      • "test": Net Income Test, Gross Income Test, Asset Test
      • "income": Net Income Calculation, Gross Income Calculation
      • "amount": Benefit Amount Calculation