{"openapi":"3.1.0","info":{"title":"CredAI API","version":"2.0.0","description":"Score customers from raw alternative data (utility bills, mobile top-ups, wallet and bank transactions, instalments) and evaluate loan applications against an underwriting policy."},"servers":[{"url":"https://credai-nabeeghs-projects.vercel.app"}],"paths":{"/api/v1/score":{"post":{"summary":"Score raw customer records","description":"Stateless. Send a CustomerRecord (or { customer, loan, policy }). Returns score, grade, per-feature points and an optional policy decision.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CustomerRecord"},{"type":"object","required":["customer"],"properties":{"customer":{"$ref":"#/components/schemas/CustomerRecord"},"loan":{"$ref":"#/components/schemas/LoanRequest"},"policy":{"type":"object","additionalProperties":{"type":"number"}}}}]}}}},"responses":{"200":{"description":"Score report"},"422":{"description":"Record failed validation; issues listed by path"}}}},"/api/v1/customers":{"get":{"summary":"List customers from the configured data provider, with scores","responses":{"200":{"description":"Customer list"}}}},"/api/v1/customers/{id}":{"get":{"summary":"Score one customer from the data provider","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"amount","in":"query","schema":{"type":"number"},"description":"Loan amount in PKR; adds a policy decision"},{"name":"tenureMonths","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Score report and optional decision"},"404":{"description":"Unknown customer"}}}},"/api/v1/model":{"get":{"summary":"Model artifact, metrics and fairness audit","responses":{"200":{"description":"Model card"}}}},"/api/v1/health":{"get":{"summary":"Data provider and model health","responses":{"200":{"description":"Healthy"},"503":{"description":"Provider unreachable"}}}}},"components":{"schemas":{"CustomerRecord":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"customerId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1},"city":{"type":"string"},"segment":{"type":"string"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}"},"declaredMonthlyIncome":{"type":"number","minimum":0},"consent":{"default":{"utility":true,"telecom":true,"wallet":true,"bank":true,"credit":true},"type":"object","properties":{"utility":{"default":true,"type":"boolean"},"telecom":{"default":true,"type":"boolean"},"wallet":{"default":true,"type":"boolean"},"bank":{"default":true,"type":"boolean"},"credit":{"default":true,"type":"boolean"}}},"utility":{"type":"object","properties":{"accountRef":{"type":"string"},"bills":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"kind":{"default":"electricity","type":"string","enum":["electricity","gas","water","internet"]},"issuedAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}"},"dueDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}"},"paidAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}"},{"type":"null"}]},"amount":{"type":"number","minimum":0}},"required":["issuedAt","dueDate","paidAt","amount"]}}},"required":["bills"]},"telecom":{"type":"object","properties":{"operator":{"type":"string"},"accountOpenedAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}"},"payments":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}"},"amount":{"type":"number","minimum":0},"kind":{"default":"recharge","type":"string","enum":["recharge","postpaid_bill"]},"status":{"type":"string","enum":["success","failed"]}},"required":["date","amount","status"]}}},"required":["accountOpenedAt","payments"]},"wallet":{"type":"object","properties":{"provider":{"type":"string"},"transactions":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}"},"amount":{"type":"number","minimum":0},"direction":{"type":"string","enum":["in","out"]},"status":{"type":"string","enum":["success","failed"]},"balanceAfter":{"type":"number"},"counterparty":{"type":"string"}},"required":["date","amount","direction","status"]}}},"required":["transactions"]},"bank":{"type":"object","properties":{"institution":{"type":"string"},"transactions":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}"},"amount":{"type":"number","minimum":0},"direction":{"type":"string","enum":["in","out"]},"category":{"type":"string"},"balanceAfter":{"type":"number"}},"required":["date","amount","direction","balanceAfter"]}}},"required":["transactions"]},"credit":{"type":"object","properties":{"lender":{"type":"string"},"installments":{"type":"array","items":{"type":"object","properties":{"dueDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}"},"paidAt":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}"},{"type":"null"}]},"amount":{"type":"number","minimum":0}},"required":["dueDate","paidAt","amount"]}}},"required":["installments"]}},"required":["customerId","displayName","asOf"]},"LoanRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"tenureMonths":{"type":"integer","minimum":1,"maximum":60},"purpose":{"type":"string"}},"required":["amount","tenureMonths"]}}}}