{"openapi":"3.1.0","info":{"title":"Duesback","version":"0.1.0","description":"Finds money the user is owed or overpaying in bank transactions and returns playbooks an agent can execute. The agent acts (cancel, negotiate, request refunds) and reports outcomes; Duesback verifies results in later data and only then creates the agreed success fee (30% of first-year verified savings, 25% of verified refunds, min $1), paid through a payment link the user approves. No card is stored. Stores only recurring-charge signatures, never raw transactions."},"servers":[{"url":"https://duesback.com"}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"Preferred. OAuth 2.1 with PKCE and dynamic client registration; metadata at /.well-known/oauth-authorization-server. Do not ask the user for a token: open the authorization page.","flows":{"authorizationCode":{"authorizationUrl":"https://duesback.com/oauth/authorize","tokenUrl":"https://duesback.com/oauth/token","refreshUrl":"https://duesback.com/oauth/token","scopes":{"duesback":"Audit bills, follow playbooks, report outcomes, manage fees"}}}},"bearerAuth":{"type":"http","scheme":"bearer","description":"Fallback: a Duesback API key from /start, format dk_live_…"}},"schemas":{"Transaction":{"type":"object","required":["date","amount","name"],"properties":{"id":{"type":"string"},"date":{"type":"string","description":"YYYY-MM-DD"},"amount":{"type":"number","description":"Plaid convention: positive = charge, negative = refund/credit"},"name":{"type":"string","description":"Raw bank description"},"merchant_name":{"type":["string","null"]},"category":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"string"},{"type":"null"}]},"account_id":{"type":["string","null"],"description":"Opaque label only; never an account number"},"pending":{"type":"boolean"},"currency":{"type":"string"}}}}},"security":[{"oauth2":["duesback"]},{"bearerAuth":[]}],"paths":{"/v1/audit":{"post":{"operationId":"auditBills","summary":"Audit 12 months of transactions; also verifies pending outcomes and charges verified fees","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transactions"],"properties":{"transactions":{"type":"array","minItems":1,"maxItems":5000,"items":{"type":"object","required":["date","amount","name"],"properties":{"id":{"type":"string"},"date":{"type":"string","description":"YYYY-MM-DD"},"amount":{"type":"number","description":"Plaid convention: positive = charge, negative = refund/credit"},"name":{"type":"string","description":"Raw bank description"},"merchant_name":{"type":["string","null"]},"category":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"string"},{"type":"null"}]},"account_id":{"type":["string","null"],"description":"Opaque label only; never an account number"},"pending":{"type":"boolean"},"currency":{"type":"string"}}}},"as_of":{"type":"string"}}}}}},"responses":{"200":{"description":"Findings, summary, totals, verifications, next_steps"}}}},"/v1/findings":{"get":{"operationId":"listFindings","summary":"Open findings, best savings first","responses":{"200":{"description":"findings[]"}}}},"/v1/findings/{finding_id}/playbook":{"get":{"operationId":"getPlaybook","summary":"Exact actions, scripts and contacts for one finding","parameters":[{"name":"finding_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"finding + playbook"},"404":{"description":"unknown finding"}}}},"/v1/outcomes":{"post":{"operationId":"reportOutcome","summary":"Report what happened after acting on a finding (nothing is charged now)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["finding_id","action","result"],"properties":{"finding_id":{"type":"string"},"action":{"type":"string","enum":["cancel","negotiate","request_refund","downgrade","verify"]},"result":{"type":"string","enum":["succeeded","partial","failed","pending"]},"new_amount":{"type":"number"},"refund_amount":{"type":"number"},"evidence":{"type":"string"}}}}}},"responses":{"200":{"description":"outcome_id, fee_preview, next"}}}},"/v1/outcomes/{outcome_id}/verify":{"post":{"operationId":"verifyOutcome","summary":"Verify one outcome against fresh transactions; charges the fee only if verified","parameters":[{"name":"outcome_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transactions"],"properties":{"transactions":{"type":"array","minItems":1,"maxItems":5000,"items":{"type":"object","required":["date","amount","name"],"properties":{"id":{"type":"string"},"date":{"type":"string","description":"YYYY-MM-DD"},"amount":{"type":"number","description":"Plaid convention: positive = charge, negative = refund/credit"},"name":{"type":"string","description":"Raw bank description"},"merchant_name":{"type":["string","null"]},"category":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"string"},{"type":"null"}]},"account_id":{"type":["string","null"],"description":"Opaque label only; never an account number"},"pending":{"type":"boolean"},"currency":{"type":"string"}}}},"as_of":{"type":"string"}}}}}},"responses":{"200":{"description":"verification summary"}}}},"/v1/findings/{finding_id}/quote":{"get":{"operationId":"quoteFee","summary":"Quote the success fee a report would create. Read-only, no side effects.","parameters":[{"name":"finding_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"new_amount","in":"query","schema":{"type":"number"}},{"name":"refund_amount","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"Fee, installments and terms"},"400":{"description":"Unknown finding"}}}},"/v1/fees":{"get":{"operationId":"getDueFees","summary":"Verified success fees not yet paid, each with a Stripe Checkout link the user approves","responses":{"200":{"description":"fees_due[]"}}}},"/v1/account":{"get":{"operationId":"accountStatus","summary":"Membership, pending verifications, fees due and paid, fee rules","responses":{"200":{"description":"account"}}}},"/v1/disconnect":{"post":{"operationId":"disconnect","summary":"Revoke key and delete stored signatures and findings","responses":{"200":{"description":"confirmation"}}}}}}