Scenarios
On this page, you’ll find the endpoints that enable you to manage scenarios programmatically, allowing you to create, retrieve, update, and delete scenario data to suit various user needs. These scenarios are intended to capture detailed, real-life information about individual financial situations, including family setup, income, benefits eligibility, and more.
The Scenario Model
The scenario model serves as the foundation for each scenario, encompassing the data that defines a user’s financial and personal profile. It includes fields for family composition, income sources, and benefit eligibility, providing a well-rounded view of each scenario. Each scenario is assigned a unique token that acts as a secure identifier, allowing users to access and modify their data without exposing sensitive information directly. This flexibility enables developers to create simulations, analyze benefits distribution, and provide tailored experiences that reflect different financial profiles.
List All Scenarios
This endpoint retrieves a comprehensive list of all scenarios associated with your account. Each scenario object includes detailed information such as family structure, income, benefits eligibility, and other relevant financial data. This is useful for viewing and managing multiple scenarios in a single request.
Request
curl -X GET https://api.benefitscliffs.org/scenarios \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"data": [
{
"id": 825,
"user_id": 1,
"state": {
"id": 5,
"name": "Arkansas",
"slug": "arkansas"
},
"token": "1714384558434",
"expired": null,
"created_at": "2024-04-29T09:56:43.000000Z",
"scenario_data": {
# scenario data will be here
}
},
{
"id": 825,
"user_id": 1,
"state": {
"id": 5,
"name": "Arkansas",
"slug": "arkansas"
},
"token": "1714384558434",
"expired": null,
"created_at": "2024-04-29T09:56:43.000000Z",
"scenario_data": {
# scenario data will be here
}
}
]
}
View Scenario
This endpoint allows you to retrieve detailed information about a specific scenario by providing its unique token. The response includes the complete scenario object, covering aspects like income, benefits eligibility, family setup, and additional details to help analyze or verify specific scenarios.
Required Attributes
- Name
token- Type
- string
- Description
The unique token for the scenario.
Request
curl -X GET https://api.benefitscliffs.org/scenarios/YOUR_TOKEN \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"data": {
"status": "success",
"message": "Scenario found",
"scenario": {
"token": "1680519224478",
"scenario_data": {
"year": 2021,
"adult": [
{
"id": 1,
"age": 30,
"nickname": "Adult #1",
"wage_rate": "0",
"yes_or_no": 1,
"adult_type": 1,
"is_married": 0,
"is_veteran": 0,
"unemp_comp": "0",
"is_pregnant": 0,
"monthly_ssi": "0",
"child_support": "0",
"other_unearned": "0",
"monthly_disability": "0",
"soc_sec_retirement": "0",
"same_snap_household": 1,
"work_hours_per_week": "0",
"is_spouse_in_household": 1,
"same_legal_hh_fed_state": 1,
"training_hours_per_week": "0",
"aged_or_disability_income": 5
},
{
"id": 2,
"age": 32,
"wage_rate": "0",
"yes_or_no": 1,
"adult_type": 2,
"is_married": 1,
"is_veteran": 0,
"unemp_comp": "0",
"monthly_ssi": 0,
"child_support": "0",
"other_unearned": "0",
"monthly_disability": "0",
"soc_sec_retirement": "0",
"same_snap_household": 1,
"work_hours_per_week": "0",
"is_spouse_in_household": 1,
"same_legal_hh_fed_state": 1,
"training_hours_per_week": "0",
"aged_or_disability_income": 5
}
],
"child": [
{
"id": 1,
"age": 6,
"sex": 2,
"caretaker": 1,
"in_school": 2,
"yes_or_no": 1,
"is_disabled": 0,
"cc_rate_category": 30,
"ssi_income_amount": "0",
"child_care_setting": 1,
"relation_to_caretaker": 12,
"same_legal_hh_fed_state": 1,
"purchase_and_prepare_meals_together": 1
},
{
"id": 2,
"age": 0,
"sex": 1,
"caretaker": 1,
"in_school": 1,
"yes_or_no": 1,
"is_disabled": 0,
"cc_rate_category": 30,
"child_care_setting": 1,
"relation_to_caretaker": 11,
"same_legal_hh_fed_state": 1,
"purchase_and_prepare_meals_together": 1
}
],
"state": 50,
"token": 1680519224478,
"programs": [
"actc",
"ctc",
"eitc",
"state_tax",
"state_eitc",
"child_care",
"tanf",
"ssi",
"liheap",
"fica",
"snap",
"medic_aid",
"hix_ptc",
"chip",
"housing",
"wic",
"pandemic",
"fed_tax",
"nslp"
],
"sub_division": 1
},
"chart_img": "https://benefits...",
"created_at": "2023-04-03T10:53:54.000000Z",
"state": {
"id": 50,
"name": "Tennessee"
}
}
}
}
Save Scenario
This endpoint lets you save or update an existing scenario in your system. By providing the unique token along with updated scenarioData, you can modify details such as family structure, income, or benefit eligibility, ensuring the scenario reflects the most current information available.
Required Attributes
- Name
token- Type
- string
- Description
The token for the scenario.
- Name
scenarioData- Type
- json
- Description
The scenario data.
- Name
scenarioData.state_id- Type
- json
- Description
The scenario data.
Request
curl https://api.benefitscliffs.org/scenarios/save \
-H "Authorization: Bearer {token}" \
-d token="YOUR_TOKEN" \
Response
{
TBC
}
Delete Scenario
This endpoint allows you to permanently delete a specific scenario by its token. Note: Deleting a scenario is irreversible and will remove all associated data, including income details, benefits eligibility, and other scenario-specific information. Use this action with caution.
Required Attributes
- Name
token- Type
- string
- Description
The unique token for the scenario.
Request
curl -X DELETE https://api.benefits-cliffs.org/scenarios/YOUR_TOKEN/delete \
-H "Authorization: Bearer YOUR_API_KEY"
Create Scenario
This endpoint initiates a new scenario creation. Upon successful execution, it generates a unique token for the scenario, which can be used to access and manage the scenario’s data. This is essential for creating new scenarios with specific parameters, allowing users to explore unique financial and eligibility setups.
Request
curl -X POST https://api.benefits-cliffs.org/scenarios/YOUR_TOKEN/delete \
-H "Authorization: Bearer YOUR_API_KEY"