{"id":18326865,"url":"https://github.com/codatio/demo-loan-qualification","last_synced_at":"2026-01-05T01:15:13.311Z","repository":{"id":109680933,"uuid":"596556414","full_name":"codatio/demo-loan-qualification","owner":"codatio","description":"This project is to help build a backend for underwriting use cases. ","archived":false,"fork":false,"pushed_at":"2024-09-07T14:57:51.000Z","size":71,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-21T14:23:15.291Z","etag":null,"topics":["build-guide","codat","demo","dotnet","underwriting"],"latest_commit_sha":null,"homepage":"https://docs.codat.io/lending/guides/loan-qualification/introduction","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codatio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-02T12:54:52.000Z","updated_at":"2024-09-07T14:57:55.000Z","dependencies_parsed_at":"2023-07-24T13:15:23.519Z","dependency_job_id":"7369250f-477a-4dd3-970b-359d5fb63edf","html_url":"https://github.com/codatio/demo-loan-qualification","commit_stats":null,"previous_names":["codatio/demo-loan-qualification"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codatio%2Fdemo-loan-qualification","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codatio%2Fdemo-loan-qualification/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codatio%2Fdemo-loan-qualification/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codatio%2Fdemo-loan-qualification/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codatio","download_url":"https://codeload.github.com/codatio/demo-loan-qualification/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423469,"owners_count":20936621,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build-guide","codat","demo","dotnet","underwriting"],"created_at":"2024-11-05T19:08:30.997Z","updated_at":"2026-01-05T01:15:13.269Z","avatar_url":"https://github.com/codatio.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Demo Loan Qualification\n\n## Introduction\n\nThis project shows how you can integrate Codat into an automated underwriting web application.\nThe project is implemented in [.NET 7.0](https://dotnet.microsoft.com/en-us/download/dotnet/7.0) as a backend API that uses features of Codat's [Lending API](https://docs.codat.io/docs/lending/overview?utm_medium=referral\u0026utm_source=linked_website\u0026utm_campaign=2023_github_underwriting_code_demo) product.\n\nYou'll learn how to:\n- Create a test Company via API.\n- Use Codat's webhooks to trigger the underwriting of a loan.\n- Access and create custom financial metrics using our categorized Profit and Loss statement and categorized Balance Sheet.\n\n\u003e NOTE: We use an example underwriting model to highlight how you can use Codat to fully automate a loan for SMBs.\n\n## Prerequisites\n\nYou need these to run and test the code locally: \n- A Codat account that you can [create for free](https://signup.codat.io/?utm_medium=referral\u0026utm_source=linked_website\u0026utm_campaign=2023_github_underwriting_code_demo)\n- Your Codat [API keys](https://app.codat.io/developers/api-keys?utm_medium=referral\u0026utm_source=linked_website\u0026utm_campaign=2023_github_underwriting_code_demo)\n- A way to access remote systems from your locally hosted server (we used [ngrok](https://ngrok.com/))\n\n## Getting started\n\nTo run the underwriting demo app: \n1. Add your API key (`CodatApiKey`) and local machine's publicly available base url (`BaseWebhookUrl`) to the `appSettings.json` file.\n2. Start your local application.\n3. Apply for a loan:\n   1. Call `GET applications/start` to start a new loan application. This returns an application ID and a `linkUrl`. \n   2. Use the application ID to complete the form. Then, submit it using the `POST applications/form` endpoint.\n   3. Link your test Company's accounting data using the `linkUrl`.\n4. Call the `GET applications/{applicationId}` endpoint to view the status of the loan.\n\n#### Request body of an example application form \n```json\n{\n   \"id\": \"applicationId\", \n   \"companyName\": \"Example Company\",\n   \"fullName\": \"John Smith\",\n   \"loanAmount\": 25000.00, // must be greater than zero \n   \"loanTerm\": 36, // must be at least 12 months\n   \"loanPurpose\": \"Growth marketing campaign.\"\n}\n```\n\n## Implementing the solution\n\nThe underwriting model we use in the demo requires the following data about the company and the borrower:\n- Validate application details\n- Chart of accounts\n- Balance sheet\n- Profit and loss statement\n- Categorized accounts\n\nWe will now demonstrate how Codat enables you to access this data. It will help you understand how you may implement your own automated underwriting solution.\n\nOur example app contains several endpoints:\n* Three public endpoints allow the prospective borrower request a new application, submit specific loan details, and retrieve an application via an imaginary front end.  \n* Three webhook endpoints update the data requirements needed to underwrite the loan: the company's Balance Sheet, Profit \u0026 Loss statement, and a fully categorised Chart of Accounts.\n\nReview the sequence diagram to visualize the steps performed by the app. We used solid arrows to depict public endpoints and dotted arrows for webhooks. \n\n```mermaid\nsequenceDiagram\n    participant frontend as Underwriting Frontend \n    participant backend as Underwriting Backend \n    participant codat as Codat API\n    frontend -\u003e\u003e backend: Request new application\n    backend -\u003e\u003e codat: Create company\n    codat -\u003e\u003e backend: New company\n    backend -\u003e\u003e frontend: New application\n    par\n        frontend -\u003e\u003e backend: Submit application\n    and \n        frontend -\u003e\u003e codat: Link accounting platform\n    end\n    par\n        break when status is accepted/rejected\n        loop\n            frontend -\u003e\u003e backend: Get application status\n            backend -\u003e\u003e frontend: application status\n        end\n        end\n    and\n        par \n            codat --\u003e\u003e backend: Data connection status \n        and \n            codat --\u003e\u003e backend: Data type sync complete\n        and\n            codat --\u003e\u003e backend: Account categorisation\n            backend -\u003e\u003e codat: Get enhanced P\u0026L\n            codat -\u003e\u003e backend: Enhanced P\u0026L\n        end\n        par\n            backend -\u003e\u003e codat: Get enhanced P\u0026L\n            codat -\u003e\u003e backend: Enhanced P\u0026L\n        and\n            backend -\u003e\u003e codat: Get enhanced Balance Sheet\n            codat -\u003e\u003e backend: Enhanced Balance Sheet\n        end\n        backend -\u003e\u003e backend: Underwrite loan\n    end\n```\n\n### Applying for a loan\n\nWe begin when the prospect initiates a new loan application by calling the `application/start` endpoint. It returns an \napplication ID, which we then use as the company name to create a Company using Codat's `POST /companies` endpoint. \n\nThis allows us to assign the application a reference in Codat's system, even though we don't have the Company name yet.\nWhen the new Codat company is created, the company and application IDs are stored, and then returned to the prospective borrower. \n\nWe also store the date the application was created to use as a reference date later.\n\n#### Example response returned by the `start` endpoint\n\n```json\n{\n   \"id\": \"1c727866-6923-4f81-aa7b-c7fd8c533586\",\n   \"dateCreated\": \"2023-01-18T00:00:00Z\",\n   \"codatCompanyId\": \"a9e28b79-6a98-4190-948d-3bd4d60e7c0a\",\n   \"status\": \"Started\", \n   \"linkUrl\": \"https://link.codat.io/company/a9e28b79-6a98-4190-948d-3bd4d60e7c0a\"\n}\n```\n\nOnce the prospective borrower receives the application and Codat company ID, they should complete the application details and link their\naccounting platform. They can: \n- Pass the `codatCompanyId` to [embedded link](https://docs.codat.io/auth-flow/authorize-embedded-link?utm_medium=referral\u0026utm_source=linked_website\u0026utm_campaign=2023_github_underwriting_code_demo), or\n- Use the `linkUrl`.\n\n\nIn the example app, we only request the borrower's full name, company name, and the loan amount, length and purpose. These details are posted to the `applications/forms` endpoint, which validates \nthat the required fields exist and are within acceptable limits.\n\nIf the details provided are valid, they are stored against the application ID with an acknowledgement of their receipt. Acknowledging receipt of details allows for a strongly decoupled \nsystem and enables the submission of details and connection of a company to be performed independently of each other.\n\nUpon acknowledgement of the receipt, we check on the data requirements to assess if the application can be underwritten. \n\n### Listening to Codat's webhooks\n\nWhen the prospective borrower's accounting platform is connected, the remaining steps will update the data requirements of the application.\nThese are activated by Codat's webhooks that trigger specific `POST` endpoints in our example app:\n* `webhooks/codat/data-connection-status` listens to the [DataConnectionStatusChanged](https://docs.codat.io/introduction/webhooks/core-rules-types#company-data-connection-status-changed?utm_medium=referral\u0026utm_source=linked_website\u0026utm_campaign=2023_github_underwriting_code_demo) webhook.\n\nIt verifies that the received data connection is an accounting platform, and assigns it to the related application via the Codat company ID. \nIt also checks that the accounting data connection's `newStatus` is `Linked` in order to set the application status to `CollectingData`.\n\n* `webhooks/codat/datatype-sync-complete` listens to the [Data sync completed](https://docs.codat.io/introduction/webhooks/core-rules-types#data-sync-completed?utm_medium=referral\u0026utm_source=linked_website\u0026utm_campaign=2023_github_underwriting_code_demo) webhook.\n\nIt verifies the successful fetching of the `chartOfAccounts`, `balanceSheet`, and `profitAndLoss` data types from the underlying platform. It checks each data type to ensure that they \nrelate to the accounting connection ID before the requirements are updated as fulfilled.\n\n* `webhooks/codat/account-categorisation-update` listens to the [account-categories-updated](https://docs.codat.io/introduction/webhooks/core-rules-types#account-categories-updated?utm_medium=referral\u0026utm_source=linked_website\u0026utm_campaign=2023_github_underwriting_code_demo) webhook.\n\nIt looks for any updates occuring when accounts are categorized according to Codat's standardized financial taxonomy. The webhook is delivered when the categorization engine completes\nautomatic categorization, or when someone manually categorizes accounts the engine was unable to reliably define. Then, we make a call to Codat's enhanced profit and loss API to \ncheck that there are no `UncategorizedAccounts` errors do not contain any of type. If passed, the final data requirement is confirmed. \n\n### Using Assess' enhanced financials\n\nFirst, we fetch the enhanced Profit and Loss statement and enhanced Balance Sheet for analysis.\nBoth endpoints require a `reportDate`, `periodLength`, and `numberOfPeriods` as query parameters.\nThe application's `createdDate` is used where the year and previous month are set as the `reportDate`. This ensures that a full year of financial data is returned by Codat.\nIn addition, `includeDisplayNames` parameter is set to true in the request because it allows accounts to be accessed via Codat's standardized taxonomy display names.\n\n### Underwriting the loan\n\nOnce both enhanced data types have been fetched, they are passed to the [LoanUnderwriter](Codat.Demos.Underwriting.Api/Services/LoanUnderwriter.cs) service\ntogether with the application's loan amount and term length. This is to perform an assessment of the prospective borrower's credit worthiness.\n\nThe LoanUnderwriter service returns a status of Accepted/Rejected when a loan is successfully underwritten, or UnderwritingFailure in the event of any programmatic failure.\nThe underwriting model we use as our example is a rules-based model that requires thresholds to be passed for growth profit margin, revenue, and gearing ratio. \n\n🗣️ Anything unclear in this guide? Got feedback? We're working on a whole host of new content for you, so [let us know](https://github.com/orgs/codatio/discussions/new?category=general).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodatio%2Fdemo-loan-qualification","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodatio%2Fdemo-loan-qualification","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodatio%2Fdemo-loan-qualification/lists"}