{"openapi":"3.1.0","info":{"title":"GET /api/v1/firm/capital/overview","version":"1.0.0","description":"The firm's capital desk"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/firm/capital/overview":{"get":{"tags":["firm-capital"],"summary":"The firm's capital desk","description":"One row per client the caller can see, ranked fundable first: Trust Scorecard grade, data readiness with its blockers, the best listed program the client would qualify for (published limit range and a read-only pre-check of the program's active scorecard over the client's books), existing lines and headroom, and `one_fix_away` when exactly one blocker remains. Totals: clients fundable now and the capital available. No assessment is run and nothing is decided.","operationId":"get_firm_capital_overview","parameters":[{"name":"firm_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The firm to read; defaults to the caller's staff firm.","title":"Firm Id"},"description":"The firm to read; defaults to the caller's staff firm."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_FirmCapitalOverviewResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"get_firm_capital_overview_api_v1_firm_capital_overview_get"}}},"components":{"schemas":{"FirmCapitalApplication":{"properties":{"id":{"type":"string","title":"Id","description":"Assessment id."},"status":{"type":"string","title":"Status","description":"pending, completed or failed."},"decision_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision Status","description":"approved or declined once the lender decided."},"credit_line_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Credit Line Id","description":"The line it opened."}},"type":"object","required":["id","status"],"title":"FirmCapitalApplication","description":"The client's application to the offer, if one is open."},"FirmCapitalBlocker":{"properties":{"code":{"type":"string","title":"Code","description":"Stable code (`bank_connection`, `scorecard:<key>`)."},"label":{"type":"string","title":"Label","description":"What to fix, in plain words."},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"Why it blocks, if known."},"fix_href":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fix Href","description":"In-app path where the fix is made, if there is one."}},"type":"object","required":["code","label"],"title":"FirmCapitalBlocker","description":"One thing standing between a client and an offer."},"FirmCapitalClientRow":{"properties":{"rank":{"type":"integer","title":"Rank","description":"Position in the ranked table, 1 first."},"business_id":{"type":"string","title":"Business Id","description":"The client's business."},"business_name":{"type":"string","title":"Business Name","description":"Display name."},"status":{"type":"string","enum":["fundable_now","one_fix_away","blocked"],"title":"Status","description":"fundable_now, one_fix_away (exactly one blocker) or blocked."},"one_fix_away":{"type":"boolean","title":"One Fix Away","description":"Exactly one blocker remains."},"trust_grade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trust Grade","description":"Latest Trust Scorecard grade (A-D), if computed."},"trust_month":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trust Month","description":"Month of that grade, YYYY-MM."},"readiness_ready":{"type":"boolean","title":"Readiness Ready","description":"The data an assessment measures is in."},"waiting_on":{"items":{"type":"string"},"type":"array","title":"Waiting On","description":"Readiness codes still outstanding."},"blockers":{"items":{"$ref":"#/components/schemas/FirmCapitalBlocker"},"type":"array","title":"Blockers","description":"Everything to fix, readiness first."},"best_offer":{"anyOf":[{"$ref":"#/components/schemas/FirmCapitalOffer"},{"type":"null"}],"description":"The best listed program, or null when none is open."},"offers_considered":{"type":"integer","title":"Offers Considered","description":"Listed programs the client could apply to."},"lines":{"items":{"$ref":"#/components/schemas/FirmCapitalLine"},"type":"array","title":"Lines","description":"Lines the client already borrows on."},"total_available_credit_cents":{"type":"integer","title":"Total Available Credit Cents","description":"Headroom across the client's active lines."},"can_apply":{"type":"boolean","title":"Can Apply","description":"The caller may write on this client, so Pre-qualify applies directly."},"referral":{"anyOf":[{"$ref":"#/components/schemas/FirmCapitalReferralSummary"},{"type":"null"}],"description":"The firm's latest referral for this client."}},"type":"object","required":["rank","business_id","business_name","status","one_fix_away","readiness_ready","offers_considered","total_available_credit_cents","can_apply"],"title":"FirmCapitalClientRow","description":"One client on the desk."},"FirmCapitalLine":{"properties":{"id":{"type":"string","title":"Id","description":"Line id."},"program_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Program Display Name","description":"The lender's program."},"status":{"type":"string","title":"Status","description":"pending, active, suspended or closed."},"credit_limit_cents":{"type":"integer","title":"Credit Limit Cents","description":"The line's limit."},"total_balance_cents":{"type":"integer","title":"Total Balance Cents","description":"Everything owed on the line."},"available_credit_cents":{"type":"integer","title":"Available Credit Cents","description":"Headroom left to spend."}},"type":"object","required":["id","status","credit_limit_cents","total_balance_cents","available_credit_cents"],"title":"FirmCapitalLine","description":"A line the client already borrows on."},"FirmCapitalOffer":{"properties":{"program_id":{"type":"string","title":"Program Id","description":"Program id."},"operator_business_id":{"type":"string","title":"Operator Business Id","description":"The lender's business."},"display_name":{"type":"string","title":"Display Name","description":"The program as the lender names it."},"limit_min_cents":{"type":"integer","title":"Limit Min Cents","description":"Published minimum limit."},"limit_max_cents":{"type":"integer","title":"Limit Max Cents","description":"Published maximum limit."},"default_rate_bps":{"type":"integer","title":"Default Rate Bps","description":"Annual rate in basis points."},"allowed_term_days":{"items":{"type":"integer"},"type":"array","title":"Allowed Term Days","description":"Payback terms the program offers."},"precheck":{"$ref":"#/components/schemas/FirmCapitalPrecheck","description":"The scorecard pre-check."},"application":{"anyOf":[{"$ref":"#/components/schemas/FirmCapitalApplication"},{"type":"null"}],"description":"The client's open application, if any."}},"type":"object","required":["program_id","operator_business_id","display_name","limit_min_cents","limit_max_cents","default_rate_bps","allowed_term_days","precheck"],"title":"FirmCapitalOffer","description":"The best listed program the client would qualify for today."},"FirmCapitalOverviewResponse":{"properties":{"firm_id":{"type":"string","title":"Firm Id","description":"The firm."},"as_of":{"type":"string","format":"date-time","title":"As Of","description":"When the desk was computed (UTC)."},"items":{"items":{"$ref":"#/components/schemas/FirmCapitalClientRow"},"type":"array","title":"Items","description":"Clients, fundable first."},"totals":{"$ref":"#/components/schemas/FirmCapitalTotals","description":"Headline figures."},"disclosure":{"type":"string","title":"Disclosure","description":"Shown with every referral action."},"referral_fee_display":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Referral Fee Display","description":"How the firm's referral compensation is shown; null means none."}},"type":"object","required":["firm_id","as_of","totals","disclosure"],"title":"FirmCapitalOverviewResponse","description":"The desk."},"FirmCapitalPrecheck":{"properties":{"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed","description":"True when every required rule passed, false when one failed, null when the program has no active scorecard or nothing could be measured."},"required_failed":{"items":{"type":"string"},"type":"array","title":"Required Failed","description":"Required rules that failed."},"required_unmeasured":{"items":{"type":"string"},"type":"array","title":"Required Unmeasured","description":"Required rules the books could not supply."},"scorecard_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scorecard Version Id","description":"The scorecard version measured against."}},"type":"object","required":["passed"],"title":"FirmCapitalPrecheck","description":"A read-only pass of the program's scorecard over the client's books."},"FirmCapitalReferralSummary":{"properties":{"id":{"type":"string","title":"Id","description":"Referral id."},"kind":{"type":"string","enum":["application","client_task"],"title":"Kind","description":"application opened for the client, or a to-do left for its owner."},"program_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Program Id","description":"The program referred to."},"application_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Application Id","description":"The assessment opened."},"todo_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Todo Id","description":"The owner's to-do."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the click happened (UTC)."}},"type":"object","required":["id","kind","created_at"],"title":"FirmCapitalReferralSummary","description":"The firm's most recent Pre-qualify click for the client."},"FirmCapitalTotals":{"properties":{"clients":{"type":"integer","title":"Clients","description":"Clients on the desk."},"fundable_now":{"type":"integer","title":"Fundable Now","description":"Clients with no blocker and a passing offer."},"one_fix_away":{"type":"integer","title":"One Fix Away","description":"Clients with exactly one blocker."},"blocked":{"type":"integer","title":"Blocked","description":"Everyone else."},"total_offer_capacity_cents":{"type":"integer","title":"Total Offer Capacity Cents","description":"Sum of the best offer's maximum limit over fundable clients."},"total_available_credit_cents":{"type":"integer","title":"Total Available Credit Cents","description":"Headroom across every client's active lines."},"total_available_cents":{"type":"integer","title":"Total Available Cents","description":"Offer capacity plus existing headroom."}},"type":"object","required":["clients","fundable_now","one_fix_away","blocked","total_offer_capacity_cents","total_available_credit_cents","total_available_cents"],"title":"FirmCapitalTotals","description":"The desk's headline figures."},"SuccessEnvelope_FirmCapitalOverviewResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/FirmCapitalOverviewResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[FirmCapitalOverviewResponse]"},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}