API docs

Every endpoint, its fields, errors and limits. The same description is at /openapi.json for Postman, SDK generators and AI agents.

Every check in the examples is the one paid in its payment_month, two months after the gift, at that year’s federal amount: $994 in 2026, $1,029 from January 2027 for one person.

Or start from the Giftwise Postman collection and its environment: 16 requests in five folders, each with tests, from checking a gift to calling the MCP server. The same collection runs in our test suite with Newman.

Contents

Keys and limits

Send your key as Authorization: Bearer gw_test_…. A key is optional. With one: 60 requests a minute and 1,000 a day, and every call shows on your usage page. Without one: 20 a minute.

Every response has the same shape: { data, meta, error }. meta carries request_id, version, rules_version and latency_ms. Rate-limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After on a 429.

Get a free key

Endpoints

12 endpoints. Each one opens to its fields, an example request and the response.

Check a gift

POST /api/v1/check-giftHow one gift changes her SSI check, the benefit-safe way to give it, and the rules and sources behind the answer.

Field	Type	About
`gift` required	`object`	The gift to check.
`gift.amount` required	`number`	Gift amount in US dollars.
`gift.delivery` required	`"cash" \| "vendor" \| "item" \| "able"`	How the gift reaches her: cash to her, paid to a vendor, the item itself, or her ABLE account. A home given outright is item, with category mortgage.
`gift.category`	`"medical" \| "equipment" \| "phone" \| "internet" \| "education" \| "utility" \| "rent" \| "mortgage" \| "property_tax" \| "food" \| "clothing" \| "transport" \| "personal" \| "event" \| "other"`	What the money is for. Rent, mortgage, property tax and utilities are housing (shelter). event means tickets to a game, show or other event; a birthday or holiday gift of money is other. Default "other".
`gift.date`	`string`	Date the gift arrives, YYYY-MM-DD. Defaults to today.
`gift.recurring`	`boolean`	True when the same giver pays this every month.
`gift.giver`	`string`	Who gives it, for example a first name. In a list of gifts, two gifts from the same giver in one quarter (or the months either side) are not one-off, so neither gets the $60 exclusion.
`gift.label`	`string`	A short name for the gift, such as Wheelchair repair. It comes back with the answer and does not change the math.
`gift.covers`	`object`	For a housing bill paid ahead or behind: the months it covers. A gift's share for months up to the payment counts when it is paid, and each later month's share in that month (POMS SI 00835.360 D.2).
`gift.covers.from` required	`string`	First month covered, YYYY-MM.
`gift.covers.to` required	`string`	Last month covered, YYYY-MM.
`gift.payerCoOwns`	`boolean`	True when the person paying a housing bill co-owns the home. The payment is not a gift, so with covers each month's share counts in that month, past months included (POMS SI 00835.360 D.3).
`gift.rentPaid`	`number`	For rent below market from a landlord who is her parent or child: the monthly rent she pays, with category rent and amount the market rent less that rent. The subsidy counted is the lesser of the market rent and the presumed maximum value, less this rent (POMS SI 00835.380).
`gift.every`	`"week" \| "two_weeks"`	For rent or another housing bill paid to the landlord or company weekly (week) or every two weeks (two_weeks): the amount is one payment, and the month counts the weekly amount times 13, divided by 3, a two-week amount halved first (POMS SI 00835.474 B.3).
`gift.loan`	`object`	Only for help that already exists and is a loan, to check how SSA counts it: a bona fide loan is not income (20 CFR 416.1103(f); cash, POMS SI 01120.220; food or shelter, SI 00835.482), and one that fails any test counts like the same help given. Giftwise moves gifts only; it does not arrange or record loans.
`gift.loan.mustRepay` required	`boolean`	She must repay it whether or not SSI or any other benefit is ever paid (POMS SI 00835.482 B.3).
`gift.loan.agreedWhenGiven` required	`boolean`	She and the lender both agreed she would repay at the time it was given, not afterwards (B.2, B.3).
`gift.loan.feasiblePlan` required	`boolean`	She has a plan to repay from her own income or property that she can meet; services do not count (B.4, B.5).
`gift.loan.enforceable`	`boolean`	Enforceable under the State's law (B.1). Leave it out to mean yes.
`gift.loan.repay`	`number`	What she agreed to repay, when less than the amount: her share of a bill paid for the household (B.4).
`gift.loan.fromHousehold`	`boolean`	True when the household she lives in lends her its own shelter: the amount borrowed counts as what she pays toward her share of its costs (SI 00835.482 E, F).
`profile`	`object`	The person who receives SSI. Every field is optional; leave it out for one adult who lives on her own with $1,240 in savings.
`profile.couple`	`boolean`	True for a couple who both receive SSI. A couple's full check is higher ($1,491 a month in 2026) and their savings limit is $3,000. Default false.
`profile.livesInAnothersHousehold`	`boolean`	True when she lives all month in someone else's home, with no ownership or rental liability. Unless she pays her pro rata share of the household's costs (householdCosts with householdSize, or proRataShare, and householdPays; within $20 counts), the household's shelter lowers her check every month, gift or not: by the one-third reduction ($331.33 in 2026) when it gives her all her meals. With no householdPays she is taken to pay nothing. Default false.
`profile.householdProvidesAllMeals`	`boolean`	Only used when livesInAnothersHousehold is true: whether that household gives her all her meals. The one-third reduction applies only then. Leave it out to mean true; false values housing help at up to $351.33 instead.
`profile.otherUnearnedMonthly`	`number`	Other unearned income each month, in US dollars, such as a pension. It is counted along with any cash gift. Default 0.
`profile.earnedMonthly`	`number`	Wages each month, in US dollars. After the first $65 and any of the $20 exclusion that is left, half of the rest is counted. Default 0.
`profile.ableEligible`	`boolean`	False when she cannot have an ABLE account. Then no gift is routed to ABLE. Default true.
`profile.ableBalance`	`number`	Her ABLE account balance, in US dollars. The first $100,000 does not count toward savings; the part over it does, and with her savings over the limit no SSI is paid that month, though Medicaid continues when the ABLE balance is the reason (POMS SI 01130.740 D.1). An ABLE gift that would take the account past $100,000 says so. Default 0.
`profile.ableContributedThisYear`	`number`	Dollars already put into her ABLE account this year. An ABLE gift that would pass the $20,000 yearly limit comes back with ambiguous set to true. Default 0.
`profile.savings`	`number`	Her countable savings at the start of the month the gift arrives, in US dollars. Cash she keeps adds to it, and the answer says when it would pass the limit on the 1st ($2,000, or $3,000 for a couple). Over the limit, no SSI is paid for the month. Default 1240.
`profile.householdSize`	`integer`	The people in her household, herself included (both members of a couple). Housing paid from outside the household is divided equally among them and she is charged her share (POMS SI 00835.350 B.4). Leave it out when no one else lives with her.
`profile.householdCosts`	`number`	In someone else's household: its monthly operating costs, rent or mortgage, property tax, heat, gas, electricity, water, sewer and garbage, not food (20 CFR 416.1133(c)). With householdSize it gives her pro rata share.
`profile.proRataShare`	`number`	Her pro rata share of those costs, when it is known directly (the couple's together). It takes the place of householdCosts.
`profile.householdPays`	`number`	What she pays toward those costs each month, in cash, not counting money for her food or any services (POMS SI 00835.480 C). Leave it out to mean nothing.

Response fields, in data
Field	Type	About
`check_before`	`number`	Her check for the payment month with no gift.
`check_after`	`number`	Her check for the payment month with the gift as given.
`counted_amount`	`number`	How much of the gift counts as income after exclusions.
`income_month`	`string`	The month the gift counts in, YYYY-MM: the month it arrives.
`payment_month`	`string`	The month whose check the income month decides, two months later, YYYY-MM.
`best_route`	`"cash" \| "vendor" \| "item" \| "able"`	The way to give it that keeps the most of her check.
`check_with_best_route`	`number`	Her check for the payment month on the best route.
`routes[]`	`array of objects`	Every way to give it, with the check each leaves.
`resources_after_gift`	`object`	The resource test on the 1st of the month after the gift arrives, with the gift as given: cash she keeps adds to savings, an ABLE deposit to the account.
`resources_after_gift.on`	`string`	The day the test is for, YYYY-MM-01.
`resources_after_gift.countable`	`number`	Countable resources that day: other resources plus the ABLE balance over $100,000.
`resources_after_gift.other`	`number`	Savings and other countable resources, before any ABLE balance.
`resources_after_gift.able_balance`	`number`	The ABLE balance that day.
`resources_after_gift.able_excess`	`number`	The part of the ABLE balance over $100,000, which counts as a resource.
`resources_after_gift.limit`	`number`	The resource limit: $2,000, or $3,000 for a couple.
`resources_after_gift.over`	`boolean`	True when countable resources are over the limit.
`resources_after_gift.status`	`"under" \| "able_suspension" \| "excess"`	under: at or below the limit. able_suspension: over only because of the ABLE balance, so SSI cash stops and Medicaid continues. excess: over on other resources alone.
`resources_for_check`	`object`	The resource test on the 1st of the payment month, which decides that check: over the limit, the check is $0. It counts the savings she states and the ABLE deposits; cash kept from the gift is in resources_after_gift.
`household`	`object \| null`	Only when profile.livesInAnothersHousehold is true: her place in that household for the payment month (POMS SI 00835.160, 20 CFR 416.1131 and 416.1133). Null otherwise.
`savings_on_next_first`	`number`	Deprecated, kept for version 1: resources_after_gift.countable.
`over_savings_limit`	`boolean`	Deprecated, kept for version 1: resources_after_gift.over, for the 1st of the month after the gift.
`able_balance_on_next_first`	`number`	Deprecated, kept for version 1: resources_after_gift.able_balance.
`resource_status`	`"under" \| "able_suspension" \| "excess"`	Deprecated, kept for version 1: resources_for_check.status, for the 1st of the payment month.
`ambiguous`	`boolean`	True when the rules leave room for doubt, for example whether a bill is a utility.
`ambiguity_reason`	`string \| null`	Why, when ambiguous.
`rule_ids`	`array of string`	The rules applied, from the rule table.
`citations[]`	`array of objects`	The regulation or POMS section behind each rule.
`explanation`	`object`	The answer in plain words, and with the numbers.
`trace`	`object`	The month's arithmetic, step by step.

Example request

{
  "gift": {
    "amount": 1000,
    "delivery": "cash",
    "category": "other",
    "date": "2026-04-10"
  },
  "profile": {
    "savings": 1240
  }
}

Example response Computed by the rules engine when this page was built.

{
  "data": {
    "check_before": 994,
    "check_after": 74,
    "counted_amount": 920,
    "income_month": "2026-04",
    "payment_month": "2026-06",
    "best_route": "item",
    "check_with_best_route": 994,
    "routes": [
      {
        "delivery": "vendor",
        "check": 0,
        "possible": false,
        "reason": "no_vendor_known"
      },
      {
        "delivery": "item",
        "check": 994,
        "possible": true
      },
      {
        "delivery": "able",
        "check": 994,
        "possible": true
      },
      {
        "delivery": "cash",
        "check": 74,
        "possible": true
      }
    ],
    "resources_after_gift": {
      "on": "2026-05-01",
      "countable": 2240,
      "other": 2240,
      "able_balance": 0,
      "able_excess": 0,
      "limit": 2000,
      "over": true,
      "status": "excess"
    },
    "resources_for_check": {
      "on": "2026-06-01",
      "countable": 1240,
      "other": 1240,
      "able_balance": 0,
      "able_excess": 0,
      "limit": 2000,
      "over": false,
      "status": "under"
    },
    "household": null,
    "savings_on_next_first": 2240,
    "over_savings_limit": true,
    "able_balance_on_next_first": 0,
    "resource_status": "under",
    "ambiguous": false,
    "ambiguity_reason": null,
    "rule_ids": [
      "R-CASH-01",
      "R-INFREQ-01",
      "R-GIE-01",
      "R-RMA-01",
      "R-RES-01"
    ],
    "citations": [
      {
        "id": "cfr-416-1121",
        "title": "20 CFR 416.1121: types of unearned income, including gifts",
        "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-K/section-416.1121"
      },
      {
        "id": "poms-si-00830-520",
        "title": "POMS SI 00830.520: Gifts",
        "url": "https://secure.ssa.gov/poms.nsf/lnx/0500830520"
      },
      {
        "id": "poms-si-00810-410",
        "title": "POMS SI 00810.410: Infrequent or Irregular Income Exclusion",
        "url": "https://secure.ssa.gov/poms.nsf/lnx/0500810410"
      },
      {
        "id": "poms-si-00810-420",
        "title": "POMS SI 00810.420: $20 General Income Exclusion",
        "url": "https://secure.ssa.gov/poms.nsf/lnx/0500810420"
      },
      {
        "id": "poms-si-02005-001",
        "title": "POMS SI 02005.001: Retrospective monthly accounting",
        "url": "https://secure.ssa.gov/poms.nsf/lnx/0502005001"
      },
      {
        "id": "poms-si-01110-003",
        "title": "POMS SI 01110.003: Resource limits",
        "url": "https://secure.ssa.gov/poms.nsf/lnx/0501110003"
      },
      {
        "id": "poms-si-01110-600",
        "title": "POMS SI 01110.600: When income becomes a resource",
        "url": "https://secure.ssa.gov/poms.nsf/lnx/0501110600"
      }
    ],
    "explanation": {
      "plain": "Cash counts as income. $1,000 minus $80 in exclusions leaves $920 counted in April, so her June 2026 check would be $74. Giving the item itself keeps her June 2026 check at $994. Kept as cash, her savings would be $2,240 on the 1st, over the limit.",
      "technical": "Rules R-CASH-01 (Cash gifts are unearned income); R-INFREQ-01 (Infrequent or irregular income exclusion); R-GIE-01 (General income exclusion); R-RMA-01 (Two-month delay). Income month 2026-04, payment month 2026-06 (retrospective monthly accounting, lag 2). Cash $1,000; in kind $0; shelter paid by others $0; ISM value $0; infrequent exclusion $60; general exclusion $20; countable $920; FBR for June 2026 $994 gives $74. Resources on 2026-06-01 $1,240 (other $1,240, ABLE over $100,000 $0) against $2,000: under, check $74. Best route: item ($994 in June 2026)."
    },
    "trace": {
      "month": "2026-04",
      "cashIncome": 1000,
      "inKindIncome": 0,
      "shelterPaidByOthers": 0,
      "ismValue": 0,
      "vtrApplied": false,
      "household": null,
      "infrequentExcluded": 60,
      "infrequentUsed": 60,
      "generalExcludedFromUnearned": 20,
      "generalExcludedFromEarned": 0,
      "earnedCountable": 0,
      "otherUnearned": 0,
      "countableIncome": 920,
      "incomeCheck": 74,
      "resources": {
        "on": "2026-06-01",
        "other": 1240,
        "ableBalance": 0,
        "ableExcess": 0,
        "countable": 1240,
        "limit": 2000,
        "over": false,
        "status": "under"
      },
      "check": 74,
      "paymentMonth": "2026-06"
    }
  },
  "meta": {
    "request_id": "req_a33aa53130cad5065f75",
    "version": "2026-11-08",
    "rules_version": "2026.1",
    "latency_ms": 2
  },
  "error": null
}

Try it in the playground

Plan several gifts

POST /api/v1/plan-monthMany gifts over several months, counted the way Social Security counts them: monthly, with the quarterly exclusion shared.

Field	Type	About
`gifts[]` required	`array of objects`	Between 1 and 500 gifts, in any order. Each one needs a date.
`gifts[].amount` required	`number`	Gift amount in US dollars.
`gifts[].delivery` required	`"cash" \| "vendor" \| "item" \| "able"`	How the gift reaches her: cash to her, paid to a vendor, the item itself, or her ABLE account. A home given outright is item, with category mortgage.
`gifts[].category`	`"medical" \| "equipment" \| "phone" \| "internet" \| "education" \| "utility" \| "rent" \| "mortgage" \| "property_tax" \| "food" \| "clothing" \| "transport" \| "personal" \| "event" \| "other"`	What the money is for. Rent, mortgage, property tax and utilities are housing (shelter). event means tickets to a game, show or other event; a birthday or holiday gift of money is other. Default "other".
`gifts[].date` required	`string`	Date the gift arrives, YYYY-MM-DD.
`gifts[].recurring`	`boolean`	True when the same giver pays this every month.
`gifts[].giver`	`string`	Who gives it, for example a first name. In a list of gifts, two gifts from the same giver in one quarter (or the months either side) are not one-off, so neither gets the $60 exclusion.
`gifts[].label`	`string`	A short name for the gift, such as Wheelchair repair. It comes back with the answer and does not change the math.
`gifts[].covers`	`object`	For a housing bill paid ahead or behind: the months it covers. A gift's share for months up to the payment counts when it is paid, and each later month's share in that month (POMS SI 00835.360 D.2).
`gifts[].covers.from` required	`string`	First month covered, YYYY-MM.
`gifts[].covers.to` required	`string`	Last month covered, YYYY-MM.
`gifts[].payerCoOwns`	`boolean`	True when the person paying a housing bill co-owns the home. The payment is not a gift, so with covers each month's share counts in that month, past months included (POMS SI 00835.360 D.3).
`gifts[].rentPaid`	`number`	For rent below market from a landlord who is her parent or child: the monthly rent she pays, with category rent and amount the market rent less that rent. The subsidy counted is the lesser of the market rent and the presumed maximum value, less this rent (POMS SI 00835.380).
`gifts[].every`	`"week" \| "two_weeks"`	For rent or another housing bill paid to the landlord or company weekly (week) or every two weeks (two_weeks): the amount is one payment, and the month counts the weekly amount times 13, divided by 3, a two-week amount halved first (POMS SI 00835.474 B.3).
`gifts[].loan`	`object`	Only for help that already exists and is a loan, to check how SSA counts it: a bona fide loan is not income (20 CFR 416.1103(f); cash, POMS SI 01120.220; food or shelter, SI 00835.482), and one that fails any test counts like the same help given. Giftwise moves gifts only; it does not arrange or record loans.
`gifts[].loan.mustRepay` required	`boolean`	She must repay it whether or not SSI or any other benefit is ever paid (POMS SI 00835.482 B.3).
`gifts[].loan.agreedWhenGiven` required	`boolean`	She and the lender both agreed she would repay at the time it was given, not afterwards (B.2, B.3).
`gifts[].loan.feasiblePlan` required	`boolean`	She has a plan to repay from her own income or property that she can meet; services do not count (B.4, B.5).
`gifts[].loan.enforceable`	`boolean`	Enforceable under the State's law (B.1). Leave it out to mean yes.
`gifts[].loan.repay`	`number`	What she agreed to repay, when less than the amount: her share of a bill paid for the household (B.4).
`gifts[].loan.fromHousehold`	`boolean`	True when the household she lives in lends her its own shelter: the amount borrowed counts as what she pays toward her share of its costs (SI 00835.482 E, F).
`profile`	`object`	The person who receives SSI. Every field is optional; leave it out for one adult who lives on her own with $1,240 in savings.
`profile.couple`	`boolean`	True for a couple who both receive SSI. A couple's full check is higher ($1,491 a month in 2026) and their savings limit is $3,000. Default false.
`profile.livesInAnothersHousehold`	`boolean`	True when she lives all month in someone else's home, with no ownership or rental liability. Unless she pays her pro rata share of the household's costs (householdCosts with householdSize, or proRataShare, and householdPays; within $20 counts), the household's shelter lowers her check every month, gift or not: by the one-third reduction ($331.33 in 2026) when it gives her all her meals. With no householdPays she is taken to pay nothing. Default false.
`profile.householdProvidesAllMeals`	`boolean`	Only used when livesInAnothersHousehold is true: whether that household gives her all her meals. The one-third reduction applies only then. Leave it out to mean true; false values housing help at up to $351.33 instead.
`profile.otherUnearnedMonthly`	`number`	Other unearned income each month, in US dollars, such as a pension. It is counted along with any cash gift. Default 0.
`profile.earnedMonthly`	`number`	Wages each month, in US dollars. After the first $65 and any of the $20 exclusion that is left, half of the rest is counted. Default 0.
`profile.ableEligible`	`boolean`	False when she cannot have an ABLE account. Then no gift is routed to ABLE. Default true.
`profile.ableBalance`	`number`	Her ABLE account balance, in US dollars. The first $100,000 does not count toward savings; the part over it does, and with her savings over the limit no SSI is paid that month, though Medicaid continues when the ABLE balance is the reason (POMS SI 01130.740 D.1). An ABLE gift that would take the account past $100,000 says so. Default 0.
`profile.ableContributedThisYear`	`number`	Dollars already put into her ABLE account this year. An ABLE gift that would pass the $20,000 yearly limit comes back with ambiguous set to true. Default 0.
`profile.savings`	`number`	Her countable savings at the start of the month the gift arrives, in US dollars. Cash she keeps adds to it, and the answer says when it would pass the limit on the 1st ($2,000, or $3,000 for a couple). Over the limit, no SSI is paid for the month. Default 1240.
`profile.householdSize`	`integer`	The people in her household, herself included (both members of a couple). Housing paid from outside the household is divided equally among them and she is charged her share (POMS SI 00835.350 B.4). Leave it out when no one else lives with her.
`profile.householdCosts`	`number`	In someone else's household: its monthly operating costs, rent or mortgage, property tax, heat, gas, electricity, water, sewer and garbage, not food (20 CFR 416.1133(c)). With householdSize it gives her pro rata share.
`profile.proRataShare`	`number`	Her pro rata share of those costs, when it is known directly (the couple's together). It takes the place of householdCosts.
`profile.householdPays`	`number`	What she pays toward those costs each month, in cash, not counting money for her food or any services (POMS SI 00835.480 C). Leave it out to mean nothing.

Example request

{
  "gifts": [
    {
      "date": "2026-04-05",
      "amount": 50,
      "delivery": "cash",
      "giver": "Ana"
    },
    {
      "date": "2026-06-25",
      "amount": 50,
      "delivery": "cash",
      "giver": "Ben"
    },
    {
      "date": "2026-06-26",
      "amount": 420,
      "delivery": "vendor",
      "category": "equipment",
      "giver": "Dan"
    }
  ]
}

Example response Computed by the rules engine when this page was built.

{
  "data": {
    "months": [
      {
        "month": "2026-04",
        "cashIncome": 50,
        "inKindIncome": 0,
        "shelterPaidByOthers": 0,
        "ismValue": 0,
        "vtrApplied": false,
        "household": null,
        "infrequentExcluded": 50,
        "infrequentUsed": 50,
        "generalExcludedFromUnearned": 0,
        "generalExcludedFromEarned": 0,
        "earnedCountable": 0,
        "otherUnearned": 0,
        "countableIncome": 0,
        "incomeCheck": 994,
        "resources": {
          "on": "2026-06-01",
          "other": 1240,
          "ableBalance": 0,
          "ableExcess": 0,
          "countable": 1240,
          "limit": 2000,
          "over": false,
          "status": "under"
        },
        "check": 994,
        "paymentMonth": "2026-06",
        "savingsOnNextFirst": 1290,
        "overResourceLimit": false
      },
      {
        "month": "2026-06",
        "cashIncome": 50,
        "inKindIncome": 0,
        "shelterPaidByOthers": 0,
        "ismValue": 0,
        "vtrApplied": false,
        "household": null,
        "infrequentExcluded": 10,
        "infrequentUsed": 10,
        "generalExcludedFromUnearned": 20,
        "generalExcludedFromEarned": 0,
        "earnedCountable": 0,
        "otherUnearned": 0,
        "countableIncome": 20,
        "incomeCheck": 974,
        "resources": {
          "on": "2026-08-01",
          "other": 1240,
          "ableBalance": 0,
          "ableExcess": 0,
          "countable": 1240,
          "limit": 2000,
          "over": false,
          "status": "under"
        },
        "check": 974,
        "paymentMonth": "2026-08",
        "savingsOnNextFirst": 1340,
        "overResourceLimit": false
      }
    ],
    "gifts": [
      {
        "label": null,
        "giver": "Ana",
        "amount": 50,
        "counted_amount": 0,
        "best_route": "item",
        "rule_ids": [
          "R-CASH-01",
          "R-INFREQ-01",
          "R-GIE-01",
          "R-RMA-01"
        ],
        "explanation": {
          "plain": "Cash counts as income. $50 minus $50 in exclusions leaves $0 counted in April, so her June 2026 check would be $994.",
          "technical": "Rules R-CASH-01 (Cash gifts are unearned income); R-INFREQ-01 (Infrequent or irregular income exclusion); R-GIE-01 (General income exclusion); R-RMA-01 (Two-month delay). Income month 2026-04, payment month 2026-06 (retrospective monthly accounting, lag 2). Cash $50; in kind $0; shelter paid by others $0; ISM value $0; infrequent exclusion $50; general exclusion $0; countable $0; FBR for June 2026 $994 gives $994. Resources on 2026-06-01 $1,240 (other $1,240, ABLE over $100,000 $0) against $2,000: under, check $994. Best route: item ($994 in June 2026)."
        }
      },
      {
        "label": null,
        "giver": "Ben",
        "amount": 50,
        "counted_amount": 0,
        "best_route": "item",
        "rule_ids": [
          "R-CASH-01",
          "R-INFREQ-01",
          "R-GIE-01",
          "R-RMA-01"
        ],
        "explanation": {
          "plain": "Cash counts as income. $50 minus $50 in exclusions leaves $0 counted in June, so her August 2026 check would be $994.",
          "technical": "Rules R-CASH-01 (Cash gifts are unearned income); R-INFREQ-01 (Infrequent or irregular income exclusion); R-GIE-01 (General income exclusion); R-RMA-01 (Two-month delay). Income month 2026-06, payment month 2026-08 (retrospective monthly accounting, lag 2). Cash $50; in kind $0; shelter paid by others $0; ISM value $0; infrequent exclusion $50; general exclusion $0; countable $0; FBR for August 2026 $994 gives $994. Resources on 2026-08-01 $1,240 (other $1,240, ABLE over $100,000 $0) against $2,000: under, check $994. Best route: item ($994 in August 2026)."
        }
      },
      {
        "label": null,
        "giver": "Dan",
        "amount": 420,
        "counted_amount": 0,
        "best_route": "vendor",
        "rule_ids": [
          "R-VEND-01"
        ],
        "explanation": {
          "plain": "Paid straight to the shop, so it is not counted. Her August 2026 check stays $994.",
          "technical": "Rules R-VEND-01 (Bills paid directly to a supplier). Income month 2026-06, payment month 2026-08 (retrospective monthly accounting, lag 2). Cash $0; in kind $0; shelter paid by others $0; ISM value $0; infrequent exclusion $0; general exclusion $0; countable $0; FBR for August 2026 $994 gives $994. Resources on 2026-08-01 $1,240 (other $1,240, ABLE over $100,000 $0) against $2,000: under, check $994. Best route: vendor ($994 in August 2026)."
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_d9ec0461846f4ea01155",
    "version": "2026-11-08",
    "rules_version": "2026.1",
    "latency_ms": 3
  },
  "error": null
}

Try it in the playground

Read a bill

POST /api/v1/read-billClaudeUpload a photo or PDF of a bill (multipart field file). Claude reads it. A bill at or near housing, or one Claude is less than 90% sure of, also goes to the two reviewers, and the referee decides; then the rules engine picks the benefit-safe way to pay it.

Field	Type	About
`file` required	`string`	JPEG, PNG, WebP or PDF, up to 10 MB.

Example request, with the sample electric bill

POST /api/v1/read-bill
Content-Type: multipart/form-data

file: northside-electric-bill.png

Example response Recorded from the live API on November 5, 2026.

{
  "data": {
    "bill": {
      "vendor_name": "Northside Electric Co-op",
      "vendor_category": "utility",
      "amount_due": 138,
      "currency": "USD",
      "due_date": "2026-11-20",
      "customer_name": "Maya Ortiz",
      "line_items": [
        {
          "description": "Electric usage, 612 kWh",
          "amount": 112.3
        },
        {
          "description": "Delivery charge",
          "amount": 19.2
        },
        {
          "description": "Taxes and fees",
          "amount": 6.5
        }
      ],
      "is_shelter_cost": true,
      "confidence": 0.97,
      "explanation": {
        "plain": "This is Maya's home electric bill from Northside Electric Co-op. The total is $138.00, due November 20, 2026.",
        "technical": "Read vendor header 'Northside Electric Co-op', 'Bill to: Maya Ortiz', 'Due: 2026-11-20', three line items, and 'Total due $138.00' (line items sum to $138.00). Category 'utility' chosen because the statement is for residential electric service (power), which also marks it as a shelter cost. Currency assumed USD from '$' symbol. Document is labeled as a sample/fictional."
      }
    },
    "check": {
      "check_after": 971,
      "best_route": "able",
      "check_with_best_route": 1029,
      "rule_ids": [
        "R-SHEL-01",
        "R-GIE-01"
      ],
      "ambiguous": true,
      "explanation": {
        "plain": "Help with utilities counts as housing support, up to $363 a month. $58 would be counted, so her January check would be $971. Sending it to her ABLE account keeps $1,029.",
        "technical": "Rules R-SHEL-01 (Housing costs paid by others); R-GIE-01 (General income exclusion). Income month 2026-11, payment month 2027-01 (retrospective monthly accounting, lag 2). Cash $0; in kind $0; shelter paid by others $138; ISM value $138; infrequent exclusion $60; general exclusion $20; countable $58; FBR $1,029 gives $971. Best route: able ($1,029)."
      }
    }
  },
  "meta": {
    "request_id": "req_17d49e76c4db49279ec6",
    "version": "2026-11-01",
    "rules_version": "2026.1",
    "latency_ms": 6572,
    "model": "claude-opus-5-5"
  },
  "error": null
}

Try it in the playground

Read a letter from Social Security

POST /api/v1/read-letterClaudeUpload a photo or PDF of the person's letter about their SSI payment (multipart field file, optional field pronoun). Claude reads the facts a gift page asks for, each with a short quote, and never returns an SSN, claim number, address or date of birth. The rules engine computes the check from those facts and compares it with the payment the letter states; for a PDF with a text layer, each quote is checked against the letter's text. Nothing is stored: send the confirmed answers as profile to /api/v1/gift-pages or PATCH /api/manage/{token}.

Field	Type	About
`file` required	`string`	JPEG, PNG, WebP or PDF, up to 10 MB.
`pronoun`	`"she" \| "he" \| "they"`	How the answer refers to the person. Optional; she/her when left out.

Example request, with the sample letter (made up for this demo)

POST /api/v1/read-letter
Content-Type: multipart/form-data

file: sam-ssa-letter-sample.pdf

Example response Recorded from the live API on November 10, 2026.

{
  "data": {
    "letter": {
      "is_ssa_letter": true,
      "ssi_payment": {
        "amount": 106,
        "month": "2027-01",
        "quote": "Beginning January 2027, the amount you will receive each month is $106.00.",
        "quote_found": true
      },
      "other_income": [
        {
          "kind": "social_security",
          "monthly_amount": 600,
          "quote": "We counted Social Security benefits of $600.00 a month.",
          "quote_found": true
        }
      ],
      "wages": {
        "monthly_amount": 0,
        "quote": "You told us you have no wages.",
        "quote_found": true
      },
      "living_arrangement": {
        "in_anothers_household": true,
        "gets_all_meals": true,
        "quote": "One-third reduction, because you live in another person's household and receive food and shelter from them",
        "quote_found": true
      },
      "couple": {
        "is_couple": false,
        "quote": "We pay you as an individual.",
        "quote_found": true
      },
      "explanation": {
        "plain": "This is a notice about Sam's SSI payments. It says that starting January 2027, Sam will receive $106.00 each month.",
        "technical": ""
      }
    },
    "answers": {
      "home": "other",
      "meals": true,
      "benefits": 600,
      "wages": 0,
      "couple": false
    },
    "profile": {
      "livesInAnothersHousehold": true,
      "householdProvidesAllMeals": true,
      "otherUnearnedMonthly": 600,
      "earnedMonthly": 0,
      "couple": false
    },
    "check": {
      "month": "2027-01",
      "monthLabel": "January 2027",
      "letterSays": 106,
      "answersGive": 106,
      "matches": true,
      "plain": "Matches his letter: $106 for January 2027."
    },
    "quotes": {
      "checked": 5,
      "found": 5,
      "set_aside": 0,
      "text_layer": true
    },
    "stored": false
  },
  "meta": {
    "request_id": "req_e76824d816aa4a6e833d",
    "version": "2026-11-08",
    "rules_version": "2026.1",
    "latency_ms": 34,
    "model": "claude-opus-5-5",
    "replayed": true,
    "recorded_at": "2026-11-10T18:14:29.665Z"
  },
  "error": null
}

Try it in the playground

Read a fundraiser

POST /api/v1/analyze-fundraiserClaudeRead a public fundraiser page and plan how each use of the money can reach her without lowering her check.

Field	Type	About
`url` required	`string`	A public fundraiser page, http or https. A path on this site, such as /samples/fundraiser.html, also works.

Example request

{
  "url": "/samples/fundraiser.html"
}

Example response Recorded from the live API on November 5, 2026.

{
  "data": {
    "page": {
      "title": "Help Maya get an accessible van (sample fundraiser)",
      "read_via": "bundled",
      "live_view_url": null
    },
    "fundraiser": {
      "title": "Help Maya get an accessible van (sample fundraiser)",
      "goal_amount": 6000,
      "raised_amount": 6000,
      "beneficiary_description": "Maya, 29, lives on her own and uses a power wheelchair. She is starting community college this spring, and the bus route does not reach campus. Organized by her mom, Rosa.",
      "uses": [
        {
          "description": "Wheelchair ramp and lock-down conversion of a used minivan, done by Lakeside Mobility Conversions",
          "amount": 5200,
          "category": "equipment",
          "likely_vendor": "Van conversion shop (Lakeside Mobility Conversions)"
        },
        {
          "description": "First months of insurance on the van",
          "amount": 500,
          "category": "transport",
          "likely_vendor": "Auto insurance company"
        },
        {
          "description": "Gas for her first semester of classes",
          "amount": 300,
          "category": "transport",
          "likely_vendor": "Gas station"
        }
      ],
      "mentions_benefits": true,
      "explanation": {
        "plain": "Maya's fundraiser is fully funded at $6,000! The money covers a wheelchair-accessible van conversion, insurance and gas so she can get to community college. Giftwise can help deliver it in a benefit-safe way.",
        "technical": "Goal $6,000; raised $6,000 from 48 donors. Stated uses: $5,200 ramp and lock-down conversion of a used minivan by Lakeside Mobility Conversions (equipment); $500 initial van insurance (transport); $300 gas for first semester (transport). Uses sum to $6,000. The page states Maya receives SSI, so mentions_benefits is true. Paying vendors directly (conversion shop, insurer) may help, since SSI generally counts cash and some in-kind support as income; benefit rules should be confirmed for her specific situation."
      }
    },
    "plan": [
      {
        "use": "Wheelchair ramp and lock-down conversion of a used minivan, done by Lakeside Mobility Conversions",
        "amount": 5200,
        "category": "equipment",
        "route": "vendor",
        "likely_vendor": "Van conversion shop (Lakeside Mobility Conversions)",
        "check_if_cash": 0,
        "check_with_route": 1029
      },
      {
        "use": "First months of insurance on the van",
        "amount": 500,
        "category": "transport",
        "route": "vendor",
        "likely_vendor": "Auto insurance company",
        "check_if_cash": 609,
        "check_with_route": 1029
      },
      {
        "use": "Gas for her first semester of classes",
        "amount": 300,
        "category": "transport",
        "route": "vendor",
        "likely_vendor": "Gas station",
        "check_if_cash": 809,
        "check_with_route": 1029
      }
    ],
    "summary": "Here is how $6,000 can reach her and keep her full benefits."
  },
  "meta": {
    "request_id": "req_2e6f642159df4d108653",
    "version": "2026-11-01",
    "rules_version": "2026.1",
    "latency_ms": 7121,
    "model": "claude-opus-5-5"
  },
  "error": null
}

Try it in the playground

Ask the two reviewers

POST /api/v1/review-billClaudeTwo Claude reviewers decide whether a bill paid by someone else is a housing cost. One reads the regulations and the Federal Register, the other SSA's operating manual, and each must quote its rulebook word for word. A program checks every quote, and the rules engine picks the route.

Field	Type	About
`description` required	`string`	What the bill is for, in its own words: the business, the service and any line items.
`amount` required	`number`	Amount someone else would pay, in US dollars.
`category` required	`"medical" \| "equipment" \| "phone" \| "internet" \| "education" \| "utility" \| "rent" \| "mortgage" \| "property_tax" \| "food" \| "clothing" \| "transport" \| "personal" \| "event" \| "other"`	The category the bill was read as. Housing categories (rent, mortgage, property tax, utility) are the ones the reviewers settle.
`date`	`string`	Date it is paid, YYYY-MM-DD. Defaults to today.
`recurring`	`boolean`	True when the same person pays it every month.
`profile`	`object`	The person who receives SSI. Every field is optional; leave it out for one adult who lives on her own with $1,240 in savings.
`profile.couple`	`boolean`	True for a couple who both receive SSI. A couple's full check is higher ($1,491 a month in 2026) and their savings limit is $3,000. Default false.
`profile.livesInAnothersHousehold`	`boolean`	True when she lives all month in someone else's home, with no ownership or rental liability. Unless she pays her pro rata share of the household's costs (householdCosts with householdSize, or proRataShare, and householdPays; within $20 counts), the household's shelter lowers her check every month, gift or not: by the one-third reduction ($331.33 in 2026) when it gives her all her meals. With no householdPays she is taken to pay nothing. Default false.
`profile.householdProvidesAllMeals`	`boolean`	Only used when livesInAnothersHousehold is true: whether that household gives her all her meals. The one-third reduction applies only then. Leave it out to mean true; false values housing help at up to $351.33 instead.
`profile.otherUnearnedMonthly`	`number`	Other unearned income each month, in US dollars, such as a pension. It is counted along with any cash gift. Default 0.
`profile.earnedMonthly`	`number`	Wages each month, in US dollars. After the first $65 and any of the $20 exclusion that is left, half of the rest is counted. Default 0.
`profile.ableEligible`	`boolean`	False when she cannot have an ABLE account. Then no gift is routed to ABLE. Default true.
`profile.ableBalance`	`number`	Her ABLE account balance, in US dollars. The first $100,000 does not count toward savings; the part over it does, and with her savings over the limit no SSI is paid that month, though Medicaid continues when the ABLE balance is the reason (POMS SI 01130.740 D.1). An ABLE gift that would take the account past $100,000 says so. Default 0.
`profile.ableContributedThisYear`	`number`	Dollars already put into her ABLE account this year. An ABLE gift that would pass the $20,000 yearly limit comes back with ambiguous set to true. Default 0.
`profile.savings`	`number`	Her countable savings at the start of the month the gift arrives, in US dollars. Cash she keeps adds to it, and the answer says when it would pass the limit on the 1st ($2,000, or $3,000 for a couple). Over the limit, no SSI is paid for the month. Default 1240.
`profile.householdSize`	`integer`	The people in her household, herself included (both members of a couple). Housing paid from outside the household is divided equally among them and she is charged her share (POMS SI 00835.350 B.4). Leave it out when no one else lives with her.
`profile.householdCosts`	`number`	In someone else's household: its monthly operating costs, rent or mortgage, property tax, heat, gas, electricity, water, sewer and garbage, not food (20 CFR 416.1133(c)). With householdSize it gives her pro rata share.
`profile.proRataShare`	`number`	Her pro rata share of those costs, when it is known directly (the couple's together). It takes the place of householdCosts.
`profile.householdPays`	`number`	What she pays toward those costs each month, in cash, not counting money for her food or any services (POMS SI 00835.480 C). Leave it out to mean nothing.

Example request

{
  "description": "Northside Electric Co-op, residential electric service, monthly bill",
  "amount": 138,
  "category": "utility",
  "recurring": true
}

Example response Recorded from the live API on November 5, 2026.

{
  "data": {
    "reviews": [
      {
        "authority": "regs",
        "answer": "shelter",
        "passage_id": "cfr-416-1130-shelter",
        "cite": "20 CFR 416.1130(b)(1)",
        "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-K/section-416.1130",
        "quote": "Shelter includes room, rent, mortgage payments, real property taxes, heating fuel, gas, electricity, water, sewerage, and garbage collection services.",
        "quote_checked": true,
        "set_aside_reason": null,
        "reason": {
          "plain": "Yes, this is a shelter cost. Electricity is listed by name as shelter, so someone else paying it counts as in-kind support.",
          "technical": "20 CFR 416.1130(b)(1) lists \"electricity\" in its definition of shelter. It also counts as in-kind support and maintenance any shelter \"that you receive because someone else pays for it.\" A residential electric bill paid directly to the co-op is not income itself under 416.1103(g). However, the shelter received because of that payment is in-kind income for shelter."
        },
        "confidence": 0.95
      },
      {
        "authority": "poms",
        "answer": "shelter",
        "passage_id": "poms-si-00835-020-shelter",
        "cite": "POMS SI 00835.020B.36",
        "url": "https://secure.ssa.gov/poms.nsf/lnx/0500835020",
        "quote": "In household LA's, shelter costs (also known as “items of shelter” ) are mortgage payments, property insurance (if required by a mortgageholder), rent, gas, electricity, heating fuel, water, sewer, garbage collection service, and real property taxes.",
        "quote_checked": true,
        "set_aside_reason": null,
        "reason": {
          "plain": "Yes, this is a shelter cost. Electricity is on the manual's list of shelter costs, so someone else paying the bill directly counts as in-kind support.",
          "technical": "SI 00835.020B.36 explicitly lists \"electricity\" among shelter costs. SI 00835.465C and SI 00835.020B.17 add that a non-household member paying a vendor directly for a household shelter item creates outside ISM. The bill is for residential electric service, not a business, so SI 00835.471 does not apply."
        },
        "confidence": 0.95
      }
    ],
    "referee": {
      "decision": "shelter",
      "agreed": true,
      "summary": "Both reviewers found it in their own rulebook: this bill is a housing cost."
    },
    "outcome": {
      "route": "able",
      "check_after": 1029,
      "readings": [
        "utility"
      ],
      "routes": [
        {
          "delivery": "vendor",
          "possible": true,
          "check": 911,
          "ruleIds": [
            "R-SHEL-01",
            "R-GIE-01"
          ]
        },
        {
          "delivery": "able",
          "possible": true,
          "check": 1029,
          "ruleIds": [
            "R-ABLE-01",
            "R-ABLE-02"
          ]
        }
      ],
      "rule_ids": [
        "R-ABLE-01",
        "R-ABLE-02"
      ]
    }
  },
  "meta": {
    "request_id": "req_289520a1b3ae44339a30",
    "version": "2026-11-01",
    "rules_version": "2026.1",
    "latency_ms": 4220,
    "model": "claude-opus-5-5"
  },
  "error": null
}

Try it in the playground

Ask the rulebook

POST /api/v1/ask-rulesClaudeAsk a question about SSI and gifts in plain words. Elasticsearch finds the passages (hybrid keyword and semantic search with jina-embeddings-v3, reranked by jina-reranker-v3) across the regulations, SSA's operating manual and its worked examples; Claude answers from only those passages, and a program checks every quote word for word.

Field	Type	About
`question` required	`string`	A question about SSI and gifts, in plain words, for example "Does it count if my sister pays my phone bill?"

Example request

{
  "question": "Does it count as income if my sister pays my phone bill?"
}

Example response Recorded from the live API on November 5, 2026.

{
  "data": {
    "question": "Does it count as income if my sister pays my phone bill?",
    "answer": "No. Under the SSI rules, when someone else pays your bill directly to the company, the payment is not your income. Phone service is also not counted because it is not food or shelter. The rules give this exact example of a sister paying an SSI recipient's phone bill and say neither the payment nor the phone service is income.",
    "quotes": [
      {
        "cite": "20 CFR 416.1103(g)",
        "passage_id": "cfr-416-1103-g",
        "quote": "Payment of your bills by someone else directly to the supplier is not income.",
        "found_word_for_word": true,
        "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-K/section-416.1103"
      },
      {
        "cite": "POMS SI 00815.400 B.2",
        "passage_id": "example-phone-bill",
        "quote": "Neither the payment to the phone company nor the telephone service received as a result of the payment is income because it is not food or shelter.",
        "found_word_for_word": true,
        "url": null
      },
      {
        "cite": "POMS SI 00815.400A",
        "passage_id": "poms-si-00815-400-policy",
        "quote": "However, anything received in kind as a result of the payment is income if it is food or shelter.",
        "found_word_for_word": true,
        "url": "https://secure.ssa.gov/poms.nsf/lnx/0500815400"
      }
    ],
    "passages": [
      {
        "id": "example-phone-bill",
        "kind": "example",
        "cite": "POMS SI 00815.400 B.2",
        "title": "A sister pays the phone bill",
        "text": "Joshua Hall, an SSI recipient, is unable to pay his phone bill so his sister pays the phone company with her own money. Neither the payment to the phone company nor the telephone service received as a result of the payment is income because it is not food or shelter.",
        "url": null,
        "score": 1.453
      },
      {
        "id": "poms-si-00815-400-example-phone",
        "kind": "manual",
        "cite": "POMS SI 00815.400B.2",
        "title": "SI 00815.400 Bills Paid By a Third Party — B. Examples, 2. Third party payment does not result in income",
        "text": "2. Third party payment does not result in income\nJoshua Hall, an SSI recipient, is unable to pay his phone bill so his sister pays the phone company with her own money. Neither the payment to the phone company nor the telephone service received as a result of the payment is income because it is not food or shelter.",
        "url": "https://secure.ssa.gov/poms.nsf/lnx/0500815400",
        "score": 1.444
      },
      {
        "id": "cfr-416-1103-g",
        "kind": "regulation",
        "cite": "20 CFR 416.1103(g)",
        "title": "§ 416.1103 What is not income? — (g) Bills paid for you",
        "text": "(g) Bills paid for you. Payment of your bills by someone else directly to the supplier is not income. However, we count the value of anything you receive because of the payment if it is in-kind income as defined in § 416.1102.",
        "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-K/section-416.1103",
        "score": 1.223
      },
      {
        "id": "cfr-416-1103-g-examples",
        "kind": "regulation",
        "cite": "20 CFR 416.1103(g) (Examples)",
        "title": "§ 416.1103 What is not income? — (g) Bills paid for you",
        "text": "Examples: If your daughter uses her own money to pay your mortgage payment directly to the mortgage lender, the payment itself is not your income because you do not receive it. However, because of your daughter's payment, the transaction provides you with shelter; the mortgage payment is in-kind income for shelter to you. Similarly, if you book a hotel room on credit and your son later pays the bill, the payment to the hotel is not income to you, but the payment of the bill is in-kind income for shelter to you. In this example, if your son pays for the hotel bill in a month after the month of the hotel stay, we will count the in-kind income to you in the month in which he pays the bill. On the other hand, if your brother pays a lawn service to mow your grass, the payment is not income to you because the mowing cannot be used to meet your needs for food or shelter. Therefore, the payment for the lawn service is not in-kind income as defined in § 416.1102.",
        "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-K/section-416.1103",
        "score": 1.206
      },
      {
        "id": "cfr-416-1102",
        "kind": "regulation",
        "cite": "20 CFR 416.1102",
        "title": "§ 416.1102 What is income?",
        "text": "Income is anything that you receive in cash or in-kind that you can use to meet your needs for food or shelter. For purposes of this definition, income may be received actually or constructively. Income is received constructively, unless there are significant restrictions on your ability to receive it, if it is under your control or you can use it despite not actually receiving it. Sometimes income also includes more or less than you actually receive (see §§ 416.1110 and 416.1123(b)). In-kind income is not cash but is something else that you can use to meet your needs for food or shelter. Exception: Food is not included in the calculations of in-kind support and maintenance, which is a type of unearned income that we have special rules for valuing (see §§ 416.1130 through 416.1148).",
        "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-K/section-416.1102",
        "score": 1.09
      },
      {
        "id": "poms-si-00815-400-policy",
        "kind": "manual",
        "cite": "POMS SI 00815.400A",
        "title": "SI 00815.400 Bills Paid By a Third Party — A. Policy",
        "text": "A. Policy\nPayment of an individual's bills (including supplementary medical insurance under title XVIII or other medical insurance premiums) by a third party directly to the supplier is not income. However, anything received in kind as a result of the payment is income if it is food or shelter.",
        "url": "https://secure.ssa.gov/poms.nsf/lnx/0500815400",
        "score": 1.079
      }
    ],
    "retrieval": {
      "engine": "elasticsearch",
      "model": ".jina-embeddings-v3",
      "reranker": ".jina-reranker-v3"
    },
    "ai": true
  },
  "meta": {
    "request_id": "req_17d7bf49052d4ee394b1",
    "version": "2026-11-01",
    "rules_version": "2026.1",
    "latency_ms": 5015
  },
  "error": null
}

Try it in the playground

Create a gift page

POST /api/v1/gift-pagesTurn a list of needs, for example from a fundraiser, into a live gift page where every dollar is paid straight to the shop or the ABLE account through PayPal. The rules engine picks each route. Send the person's situation as profile and every check on the page uses it; without it the page names the sample situation it uses. Sandbox pages, five a day per visitor.

Field	Type	About
`name` required	`string`	First name of the person who receives SSI, as it should appear on the page.
`pronoun` required	`"she" \| "he" \| "they"`	How the page refers to them: she/her, he/him or they/them.
`organizer`	`string`	Who is organizing, for the thank-you line. Optional.
`note`	`string`	A short note to givers. Optional; a plain default is written if empty.
`source_url`	`string`	The fundraiser page the needs came from. Optional.
`needs[]` required	`array of objects`	What the page asks for. Giftwise decides each route: housing goes to the ABLE account, everything else straight to the shop.
`needs[].title` required	`string`	What the money is for, in a few words.
`needs[].amount` required	`number`	Dollars still needed.
`needs[].category` required	`"medical" \| "equipment" \| "phone" \| "internet" \| "education" \| "utility" \| "rent" \| "mortgage" \| "property_tax" \| "food" \| "clothing" \| "transport" \| "personal" \| "event" \| "other"`	What the money is for. Rent, mortgage, property tax and utilities are housing (shelter). event means tickets to a game, show or other event; a birthday or holiday gift of money is other.
`needs[].vendor`	`string \| null`	The kind of business that would be paid, for example a van conversion shop.
`needs[].recurring`	`boolean`	True when the need comes back every month, such as rent.
`profile`	`object`	The person's own situation, so every check and route on the page uses their facts: where they live, Social Security or other benefits, wages, savings, a couple, and whether they can have an ABLE account. Send only the fields you know; the rest keep the sample situation's values. Left out, the page says it uses a sample situation (one adult on their own, no other income) until the organizer adds theirs.
`profile.couple`	`boolean`	True for a couple who both receive SSI. A couple's full check is higher ($1,491 a month in 2026) and their savings limit is $3,000. Default false.
`profile.livesInAnothersHousehold`	`boolean`	True when she lives all month in someone else's home, with no ownership or rental liability. Unless she pays her pro rata share of the household's costs (householdCosts with householdSize, or proRataShare, and householdPays; within $20 counts), the household's shelter lowers her check every month, gift or not: by the one-third reduction ($331.33 in 2026) when it gives her all her meals. With no householdPays she is taken to pay nothing. Default false.
`profile.householdProvidesAllMeals`	`boolean`	Only used when livesInAnothersHousehold is true: whether that household gives her all her meals. The one-third reduction applies only then. Leave it out to mean true; false values housing help at up to $351.33 instead.
`profile.otherUnearnedMonthly`	`number`	Other unearned income each month, in US dollars, such as a pension. It is counted along with any cash gift. Default 0.
`profile.earnedMonthly`	`number`	Wages each month, in US dollars. After the first $65 and any of the $20 exclusion that is left, half of the rest is counted. Default 0.
`profile.ableEligible`	`boolean`	False when she cannot have an ABLE account. Then no gift is routed to ABLE. Default true.
`profile.ableBalance`	`number`	Her ABLE account balance, in US dollars. The first $100,000 does not count toward savings; the part over it does, and with her savings over the limit no SSI is paid that month, though Medicaid continues when the ABLE balance is the reason (POMS SI 01130.740 D.1). An ABLE gift that would take the account past $100,000 says so. Default 0.
`profile.ableContributedThisYear`	`number`	Dollars already put into her ABLE account this year. An ABLE gift that would pass the $20,000 yearly limit comes back with ambiguous set to true. Default 0.
`profile.savings`	`number`	Her countable savings at the start of the month the gift arrives, in US dollars. Cash she keeps adds to it, and the answer says when it would pass the limit on the 1st ($2,000, or $3,000 for a couple). Over the limit, no SSI is paid for the month. Default 1240.
`profile.householdSize`	`integer`	The people in her household, herself included (both members of a couple). Housing paid from outside the household is divided equally among them and she is charged her share (POMS SI 00835.350 B.4). Leave it out when no one else lives with her.
`profile.householdCosts`	`number`	In someone else's household: its monthly operating costs, rent or mortgage, property tax, heat, gas, electricity, water, sewer and garbage, not food (20 CFR 416.1133(c)). With householdSize it gives her pro rata share.
`profile.proRataShare`	`number`	Her pro rata share of those costs, when it is known directly (the couple's together). It takes the place of householdCosts.
`profile.householdPays`	`number`	What she pays toward those costs each month, in cash, not counting money for her food or any services (POMS SI 00835.480 C). Leave it out to mean nothing.
`profile_source`	`"answers" \| "letter"`	How the facts were gathered: answers typed by the organizer, or read from the person's letter from Social Security and then confirmed. Optional; the letter itself is never stored.

Example request

{
  "name": "Jordan",
  "pronoun": "they",
  "organizer": "Sam",
  "needs": [
    {
      "title": "Van wheelchair lift",
      "amount": 1800,
      "category": "transport",
      "vendor": "a van conversion shop"
    },
    {
      "title": "Rent, December",
      "amount": 650,
      "category": "rent"
    }
  ],
  "profile": {
    "livesInAnothersHousehold": true,
    "otherUnearnedMonthly": 600
  },
  "profile_source": "answers"
}

Example response Recorded from the live API on November 10, 2026.

{
  "data": {
    "slug": "jordan-ca93a3",
    "url": "/g/jordan-ca93a3",
    "manage_url": "/manage/[private token, shown once]",
    "situation": "own",
    "profile": {
      "couple": false,
      "livesInAnothersHousehold": true,
      "otherUnearnedMonthly": 600,
      "earnedMonthly": 0,
      "ableEligible": true,
      "ableBalance": 0,
      "ableContributedThisYear": 0,
      "savings": 1240,
      "pronoun": "they"
    },
    "check": {
      "amount": 106,
      "payment_month": "2027-01"
    },
    "needs": [
      {
        "title": "Van wheelchair lift",
        "route": "vendor",
        "payee": "Van conversion shop",
        "amount": 1800,
        "check_after": 106
      },
      {
        "title": "Rent, December",
        "route": "able",
        "payee": "Jordan's ABLE account",
        "amount": 650,
        "check_after": 106
      }
    ]
  },
  "meta": {
    "request_id": "req_c2bf5fc2739e4e149ead",
    "version": "2026-11-08",
    "rules_version": "2026.1",
    "latency_ms": 29
  },
  "error": null
}

Try it in the playground

Monthly report to SSA

GET /api/v1/ssa-reportOne month of a gift page's gifts, written up as SSI reporting asks: what to tell Social Security by the 10th of the next month, and the PayPal capture or payout behind every gift that is not income. Add view=cash to see the report the same gifts would have needed as cash, or format=csv for a spreadsheet.

Example request

GET /api/v1/ssa-report?page=maya&month=2026-10

Example response Recorded from the live API on November 5, 2026.

{
  "data": {
    "month": "2026-10",
    "month_label": "October 2026",
    "view": "given",
    "name": "Maya",
    "pronoun": "she",
    "due": {
      "date": "2026-11-10",
      "label": "November 10, 2026",
      "days_left": 5,
      "state": "open"
    },
    "status": "nothing_counts",
    "headline": "Nothing here counts as income.",
    "summary": "All 5 gifts, $618 in all, went straight to a shop or her ABLE account. None of them changes her income, so there is no income change from these gifts to report for October. Her December check stays $994.",
    "lines": [
      {
        "id": "s38",
        "date": "2026-10-05",
        "giver": "Lucy",
        "need": "Electric bill",
        "paid_to": "Maya's ABLE account",
        "amount": 133,
        "delivery": "able",
        "category": "utility",
        "section": "records",
        "kind": "excluded",
        "what": "Deposit to her ABLE account",
        "why": "Money others put into the person's ABLE account is not income, and the first $100,000 in it does not count toward savings.",
        "rule_ids": [
          "R-ABLE-01",
          "R-ABLE-02"
        ],
        "sources": [
          {
            "id": "poms-si-01130-740",
            "title": "POMS SI 01130.740: ABLE accounts",
            "url": "https://secure.ssa.gov/poms.nsf/lnx/0501130740"
          },
          {
            "id": "ssa-spotlight-able-2026",
            "title": "SSA: Spotlight on ABLE accounts (2026 edition)",
            "url": "https://www.ssa.gov/ssi/spotlights/spot-able.html"
          }
        ],
        "evidence": {
          "kind": "sample"
        }
      },
      {
        "id": "s39",
        "date": "2026-10-08",
        "giver": "Priya",
        "need": "Phone bill",
        "paid_to": "Horizon Wireless",
        "amount": 65,
        "delivery": "vendor",
        "category": "phone",
        "section": "records",
        "kind": "excluded",
        "what": "Paid straight to Horizon Wireless",
        "why": "When someone pays a shop directly for something other than housing, it is not income.",
        "rule_ids": [
          "R-VEND-01"
        ],
        "sources": [
          {
            "id": "cfr-416-1103-g",
            "title": "20 CFR 416.1103(g): bills paid directly to the supplier are not income",
            "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-K/section-416.1103"
          },
          {
            "id": "poms-si-00815-400",
            "title": "POMS SI 00815.400: Bills Paid by Third Party",
            "url": "https://secure.ssa.gov/poms.nsf/lnx/0500815400"
          }
        ],
        "evidence": {
          "kind": "sample"
        }
      },
      {
        "id": "s40",
        "date": "2026-10-12",
        "giver": "Rosa",
        "need": "Therapy co-pay",
        "paid_to": "Northside Physical Therapy",
        "amount": 90,
        "delivery": "vendor",
        "category": "medical",
        "section": "records",
        "kind": "excluded",
        "what": "Paid straight to Northside Physical Therapy",
        "why": "When someone pays a shop directly for something other than housing, it is not income.",
        "rule_ids": [
          "R-VEND-01"
        ],
        "sources": [
          {
            "id": "cfr-416-1103-g",
            "title": "20 CFR 416.1103(g): bills paid directly to the supplier are not income",
            "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-K/section-416.1103"
          },
          {
            "id": "poms-si-00815-400",
            "title": "POMS SI 00815.400: Bills Paid by Third Party",
            "url": "https://secure.ssa.gov/poms.nsf/lnx/0500815400"
          }
        ],
        "evidence": {
          "kind": "sample"
        }
      },
      {
        "id": "s41",
        "date": "2026-10-19",
        "giver": "Dan",
        "need": "Wheelchair tires",
        "paid_to": "Riverside Mobility Repair",
        "amount": 180,
        "delivery": "vendor",
        "category": "equipment",
        "section": "records",
        "kind": "excluded",
        "what": "Paid straight to Riverside Mobility Repair",
        "why": "When someone pays a shop directly for something other than housing, it is not income.",
        "rule_ids": [
          "R-VEND-01"
        ],
        "sources": [
          {
            "id": "cfr-416-1103-g",
            "title": "20 CFR 416.1103(g): bills paid directly to the supplier are not income",
            "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-K/section-416.1103"
          },
          {
            "id": "poms-si-00815-400",
            "title": "POMS SI 00815.400: Bills Paid by Third Party",
            "url": "https://secure.ssa.gov/poms.nsf/lnx/0500815400"
          }
        ],
        "evidence": {
          "kind": "sample"
        }
      },
      {
        "id": "s42",
        "date": "2026-10-28",
        "giver": "Aunt June",
        "need": "Fall savings",
        "paid_to": "Maya's ABLE account",
        "amount": 150,
        "delivery": "able",
        "category": "other",
        "section": "records",
        "kind": "excluded",
        "what": "Deposit to her ABLE account",
        "why": "Money others put into the person's ABLE account is not income, and the first $100,000 in it does not count toward savings.",
        "rule_ids": [
          "R-ABLE-01"
        ],
        "sources": [
          {
            "id": "poms-si-01130-740",
            "title": "POMS SI 01130.740: ABLE accounts",
            "url": "https://secure.ssa.gov/poms.nsf/lnx/0501130740"
          },
          {
            "id": "ssa-spotlight-able-2026",
            "title": "SSA: Spotlight on ABLE accounts (2026 edition)",
            "url": "https://www.ssa.gov/ssi/spotlights/spot-able.html"
          }
        ],
        "evidence": {
          "kind": "sample"
        }
      }
    ],
    "totals": {
      "gifts": 5,
      "given": 618,
      "tell": 0,
      "counted": 0,
      "check_month": "2026-12",
      "check_month_label": "December 2026",
      "check": 994,
      "full_check": 994,
      "counted_if_cash": 538,
      "check_if_cash": 456
    },
    "todo": [
      {
        "id": "able-housing",
        "text": "Check that the electric bill was paid from the ABLE account during October. Money taken out for housing and spent in the same month is not income; money kept into the next month counts toward savings.",
        "rule_id": "R-ABLE-02"
      },
      {
        "id": "savings",
        "text": "On November 1, her countable savings will be $1,240, under the $2,000 limit.",
        "rule_id": "R-RES-01"
      },
      {
        "id": "receipts",
        "text": "Keep the receipts below. Each one shows PayPal paid the shop or the ABLE account, not Maya. If Social Security asks about help from family, they are the answer."
      }
    ],
    "savings": {
      "on_date": "2026-11-01",
      "amount": 1240,
      "limit": 2000,
      "over": false
    },
    "script": [],
    "how": {
      "phone": "1-800-772-1213",
      "tty": "1-800-325-0778",
      "office": "Or visit or write any Social Security office."
    },
    "penalty": {
      "amounts": [
        25,
        50,
        100
      ],
      "source": "cfr-416-724"
    },
    "passages": [
      {
        "id": "cfr-416-708-c",
        "cite": "20 CFR 416.708(c)(1)",
        "text": "Unless the circumstances in § 416.709(a) and (c) apply, you must report to us any increase or decrease in your income",
        "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-G/section-416.708"
      },
      {
        "id": "cfr-416-708-d",
        "cite": "20 CFR 416.708(d)",
        "text": "You must report to us any resources you receive or part with",
        "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-G/section-416.708"
      },
      {
        "id": "cfr-416-714-a",
        "cite": "20 CFR 416.714(a)",
        "text": "You should report to us as soon as an event listed in § 416.708 happens. If you do not report within 10 days after the close of the month in which the event happens, your report will be late. We may impose a penalty deduction from your benefits for a late report (see §§ 416.722 through 416.732).",
        "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-G/section-416.714"
      },
      {
        "id": "cfr-416-724-a",
        "cite": "20 CFR 416.724(a)",
        "text": "(1) $25 for a report overdue in the first penalty period; (2) $50 for a report overdue in the second penalty period; and (3) $100 for a report overdue in the third (or any following) penalty period.",
        "url": "https://www.ecfr.gov/current/title-20/chapter-III/part-416/subpart-G/section-416.724"
      },
      {
        "id": "ssa-reporting-help",
        "cite": "SSA, Reporting Responsibilities",
        "text": "Change in help with living expenses from friends or relatives.",
        "url": "https://www.ssa.gov/ssi/text-report-ussi.htm"
      },
      {
        "id": "ssa-reporting-when",
        "cite": "SSA, Reporting Responsibilities",
        "text": "Report any changes that may affect your SSI as soon as possible and no later than 10 days after the end of the month in which the change occurred.",
        "url": "https://www.ssa.gov/ssi/text-report-ussi.htm"
      },
      {
        "id": "ssa-spotlight-how",
        "cite": "SSA, Spotlight on Rights and Responsibilities",
        "text": "Please visit or write any Social Security office, or call our toll-free number at 1-800-772-1213.",
        "url": "https://www.ssa.gov/ssi/spotlights/spot-rights-responsibilities.htm"
      }
    ],
    "months": [
      {
        "month": "2026-10",
        "label": "October 2026",
        "gifts": 5
      },
      {
        "month": "2026-09",
        "label": "September 2026",
        "gifts": 4
      },
      {
        "month": "2026-08",
        "label": "August 2026",
        "gifts": 5
      },
      {
        "month": "2026-07",
        "label": "July 2026",
        "gifts": 4
      },
      {
        "month": "2026-06",
        "label": "June 2026",
        "gifts": 4
      },
      {
        "month": "2026-05",
        "label": "May 2026",
        "gifts": 4
      },
      {
        "month": "2026-04",
        "label": "April 2026",
        "gifts": 4
      },
      {
        "month": "2026-03",
        "label": "March 2026",
        "gifts": 4
      },
      {
        "month": "2026-02",
        "label": "February 2026",
        "gifts": 5
      },
      {
        "month": "2026-01",
        "label": "January 2026",
        "gifts": 4
      }
    ],
    "rules_version": "2026.1",
    "verify": {
      "code": "CX2W6-Y1S4X",
      "url": "https://giftwise-405i.onrender.com/v/maya/2026-10/CX2W6-Y1S4X"
    }
  },
  "meta": {
    "request_id": "req_54bc5a2528bf45cca289",
    "version": "2026-11-01",
    "rules_version": "2026.1",
    "latency_ms": 77
  },
  "error": null
}

Try it in the playground

Download a preset

GET /api/presets/{id}A sample case with its input and the engine's current answer. Add ?format=csv for gift lists. Ids: wheelchair-repair, birthday-cash, electric-bill, rent-help, laptop-college, groceries, van-fundraiser, march-month.

Example request

GET /api/presets/electric-bill

Example response Computed by the rules engine when this page was built.

{
  "preset": {
    "id": "electric-bill",
    "title": "Electric bill",
    "summary": "Her sister Lucy pays the $138 electric bill every month.",
    "gift": {
      "amount": 138,
      "delivery": "vendor",
      "category": "utility",
      "recurring": true,
      "date": "2026-04-10",
      "giver": "Lucy",
      "label": "Electric bill, Northside Electric Co-op (sample)"
    },
    "document": "northside-electric-bill.png",
    "expected": {
      "check_after": 876,
      "best_route": "able"
    }
  },
  "result": {
    "check_after": 876,
    "best_route": "able",
    "check_with_best_route": 994,
    "rule_ids": [
      "R-SHEL-01",
      "R-GIE-01"
    ],
    "explanation": {
      "plain": "Help with utilities counts as housing support, up to $351.33 a month. $118 would be counted, so her June 2026 check would be $876. Sending it to her ABLE account keeps her June 2026 check at $994.",
      "technical": "Rules R-SHEL-01 (Housing costs paid by others); R-GIE-01 (General income exclusion). Income month 2026-04, payment month 2026-06 (retrospective monthly accounting, lag 2). Cash $0; in kind $0; shelter paid by others $138; ISM value $138; infrequent exclusion $0; general exclusion $20; countable $118; FBR for June 2026 $994 gives $876. Resources on 2026-06-01 $1,240 (other $1,240, ABLE over $100,000 $0) against $2,000: under, check $876. Best route: able ($994 in June 2026)."
    }
  },
  "how_to_try": "POST the preset.gift (or each item of preset.gifts) to /api/v1/check-gift, or the gifts array to /api/v1/plan-month."
}

Try it in the playground

Verify the ledger

GET /api/ledger/verifyRecompute the audit ledger's SHA-256 hash chain from the first entry and report whether every entry still matches.

Example request

GET /api/ledger/verify

Example response Recorded from the live API on November 5, 2026.

{
  "data": {
    "ok": true,
    "count": 1284
  },
  "error": null
}

Try it in the playground

Service status

GET /api/healthWhether PayPal, Claude, the database and each sponsor tool are live or using a fallback right now.

Example request

GET /api/health

Example response Recorded from the live API on November 5, 2026.

{
  "ok": true,
  "checks": [
    {
      "id": "paypal",
      "name": "PayPal sandbox",
      "mode": "live",
      "detail": "Sandbox token issued",
      "ms": 0
    },
    {
      "id": "claude",
      "name": "Claude Opus 5.5",
      "mode": "live",
      "detail": "API key set; bill and fundraiser reading are live"
    },
    {
      "id": "webhooks",
      "name": "PayPal webhooks",
      "mode": "live",
      "detail": "Every event is signature-checked with PayPal before use"
    },
    {
      "id": "paypal-mcp",
      "name": "PayPal MCP server",
      "mode": "fallback",
      "detail": "Checked on the Status page"
    },
    {
      "id": "apimatic",
      "name": "PayPal Server SDK (APIMatic)",
      "mode": "live",
      "detail": "@paypal/paypal-server-sdk 2.5.0 creates, reads and captures orders"
    },
    {
      "id": "ag-studio",
      "name": "AG Studio",
      "mode": "live",
      "detail": "ag-studio-react 3.0.0, licensed"
    },
    {
      "id": "bryntum",
      "name": "Bryntum Calendar",
      "mode": "live",
      "detail": "@bryntum/calendar 7.3.7, the trial build, which shows a trial watermark"
    },
    {
      "id": "rules-watch",
      "name": "Federal Register watch",
      "mode": "live",
      "detail": "Checked on the Status page and every night by the outside checks"
    },
    {
      "id": "channel3",
      "name": "Channel3 product search",
      "mode": "live",
      "detail": "Key set; the gift finder searches real products, each checked against the SSI rules"
    },
    {
      "id": "elastic",
      "name": "Elasticsearch rulebook search",
      "mode": "live",
      "detail": "Hybrid keyword and semantic search with jina-embeddings-v3, reranked by jina-reranker-v3, over the regulations, SSA's manual and its worked examples"
    },
    {
      "id": "database",
      "name": "Postgres",
      "mode": "live",
      "detail": "Postgres answered a test query",
      "ms": 1
    },
    {
      "id": "checks",
      "name": "Outside checks",
      "mode": "live",
      "detail": "24 of 24 passed 9 h ago, run locally"
    }
  ],
  "at": "2026-11-05T15:08:02.868Z"
}

Errors

Every error has a code you can branch on and a plain message you can show to people.

invalid_request 400, 409, 413, 422: Something in the request is missing or not valid. The message says what; details lists each field.
unauthorized 401: The API key is not valid or was revoked. Create a new key on the Developers page.
not_found 404: The thing you asked for does not exist, such as an unknown preset or order.
rate_limited 429: Too many requests. Wait for the time in the Retry-After header. Keys allow 60 a minute and 1,000 a day.
upstream_unavailable 502, 503: PayPal or the AI service did not answer, or is not connected on this server. The message says which.
internal 500: Something went wrong on our side. The request id in meta helps us find it.