Design Consideration for API’s
API - Design Consideration for Client Application
| API Purpose | API End Point | Design Consideration for Client Application |
|---|---|---|
| The API is used to get the list of available document types in the SBA Forgiveness portal. These document types are needed when sharing documents with SBA, for borrowers forgiveness application. | GET /api/ppp_loan_document_types/ | Document list will not change frequently. For efficiency, Client application may choose to call this API once a day and store results in their cache/storage |
| This API is used to create new forgiveness request for a SBA loan | POST /api/ppp_loan_forgiveness_requests/ | One API call per Forgiveness request.In case Client has large number of forgiveness requests, they may like to call this API using a batch process at their end |
| This API is used to provide supporting documents for a particular Forgiveness request | POST /api/ppp_loan_documents/ | Client may like to call this API immediately after Forgiveness request API call. Documents can only be uploaded using this API when Forgiveness status is Pending validation or Lender additional info needed (scenario - Lender has not submitted any document in first place to SBA, in conjunction with Reply message API). This API also requires document type as input which client can get from 1. Get Document Types. One API call supports sending one document for a forgiveness request.If client is submitting multiple documents for a Forgiveness request, they would have to call this API multiple times. In case Client has large number of forgiveness supporting documents, they may like to call this API by designing batch process at their end. |
| This API fetches the list of ALL forgiveness request for a lender | GET /api/ppp_loan_forgiveness_requests/ | This API provides Status/Details of all submitted forgiveness requests for a Lender. This API supports pagination functionality and if client is designing a UI or batch process to call this API, they may like to have page up and page down feature. Every page returns 50 maximum records. Also this API saves data in cache for 30 seconds after making database call and uses data from cache to send back to client.If client is calling this API without slug id and client’s application takes more than 30 seconds to process complete loan set, its possible that result count may change and order in which data is being send back by API may also change, so client application should handle such scenarios. For Large volume clients, we recommend calling this API end point with slug id as parameter |
| This API is used for getting details of existing forgiveness request using unique slug id (Forgiveness request UUID) | GET /api/ppp_loan_forgiveness_requests/{slug}/ | This API provides Status/Details of a specific submitted forgiveness request. Client may choose to use this API in case they would lke to get latest details of a particular forgiveness request. |
| This API is used for getting details of existing forgiveness request using SBA Number | GET /api/ppp_loan_forgiveness_requests/?sba_number={sba_number} | This API provides Status/Details of a specific submitted forgiveness request. Client may choose to use this API in case they would lke to get latest details of a particular forgiveness request. |
| This API is used for deleting the existing Forgiveness request | DELETE /api/ppp_loan_forgiveness_requests/{slug}/ | Client may use this API to delete forgiveness request and corresponding supporting documents.Please note - For any reason, if client would like to delete Forgiveness request, they may to call this API within 24 hrs of original submission, before SBA starts reviewing forgiveness. Once SBA starts reviewing a request, it cannot be deleted. |
| During review of a Forgiveness request, SBA may require additional information from Lender or Lender may have questions for SBA. This API is used to retrieve all messages for a Lender. | GET /api/ppp_loan_forgiveness_messages/ | Client may like to call this API to retrieve all messages for all their Forgiveness requests. This API supports pagination functionality and if client is designing a UI or batch process to call this API, they may like to have next page and previous page feature. Every page returns 50 maximum records. |
| During review of a Forgiveness request, SBA may require additional information from lender. This API is used to retrieve additional document messages sent by SBA to Lender using Forgiveness UUID. SBA can send single message to the Lender at a time which is indicated by the API field is_complete: false. Once Lender replies back the API field updates to is_complete: true and then SBA may send additional message if required. | GET /api/ppp_loan_forgiveness_messages/{slug}/ | Client may like to call this API to retrieve messages send by SBA to Lender for a particular forgiveness request. |
| During review of a Forgiveness request, SBA may require additional information from lender. This API is used to retrieve messages sent by SBA to lender using SBA number.SBA can send single message to the Lender at a time which is indicated by the API field is_complete: false. Once Lender replies back the API field updates to is_complete: true and then SBA may send additional message if required. | GET /api/ppp_loan_forgiveness_messages/?sba_number={sba_number} | Client may like to call this API to retrieve messages send by SBA to Lender for a particular forgiveness request. |
| During review of a Forgiveness request, SBA may require additional information from lender. This API is used by lender to respond back to SBA | PUT /api/ppp_loan_forgiveness_message_reply/{slug}/ Content-type: multipart/form-data/ | This API needs the forgiveness request slug as path parameter in input. Client would have to call Get Forgiveness Message API to get details of additional document/s SBA is asking Lender to provide. If Lender wants to reply back with multiple documents, they must include all of them in single API call.Lender also has an option to use POST /api/ppp_loan_documents/ to send all additional documents and finally reply back with ppp_loan_forgiveness_message_reply API confirming SBA to resume decision review |
| Allows Lender/Vendor to ensure a loan is in a proper disposition to accept a forgiveness decision. Using this API, you can look up disbursed PPP loans | GET /api/ppp_loan_validations/ | This API can be used by Lender/Vendor to lookup disbursed loan data. This API supports pagination functionality and if client is designing a UI or batch process to call this API, they may like to have page up and page down feature. Every page returns 50 maximum records. New disbursed Loans will be added once a day. |
Slug ID or UUID - Usage
| Slug ID type | Usage |
|---|---|
| Forgiveness Request - Slug ID | Client will receive it as part of the response of Create Forgiveness Request API. This slug can be used by client while making following API calls - Get status of Forgiveness, Delete Forgivenes, Get Forgiveness message & replying back to SBA with additional documents (Reply to SBA message) |
| Etran Loan - Slug ID | Client will receive it as part of response of Create Forgiveness Request API. This slug can be used by client while sending supporting documents for a Forgiveness request (Upload Forgiveness documents) |
| Ticket Slug ID | This is same as Forgiveness Request Slug id & Client will also receive it as part of response of Get Forgiveness Messages API. This slug can be used by client while replying back to SBA with additional documents (Reply to SBA message) |
| Document Slug ID | Client will receive this slug as part of response of Upload Forgiveness documents API |
| Organization Slug ID | Client will receive this slug as part of response of Get Forgiveness Request API |
Lender Decision Vs Forgiveness Decision Mapping
| Lender Decision | SBA Decision | Forgiveness Decision Status |
|---|---|---|
| APPROVED_IN_FULL = 0 | Fully Approved | Fully Approved |
| APPROVED_IN_FULL = 0 | Partially Approved | Partially Approved |
| APPROVED_IN_FULL = 0 | Not Approved | Not Approved |
| APPROVED_IN_PART = 1 | Fully Approved | Fully Approved |
| APPROVED_IN_PART = 1 | Partially Approved | Partially Approved |
| APPROVED_IN_PART = 1 | Not Approved | Not Approved |
| DENIED = 2 | Not Approved | Not Approved |
| DENIED = 2 | Fully Approved | Fully Approved |
API vs Portal - Functionality
| SNo | Functionality | API | SBA Forgiveness Portal | Comments |
|---|---|---|---|---|
| 1 | Review Disbursed PPP Loans | GET /api/ppp_loan_validations/ | UI - Lookup Disbursed PPP Loans | Reflects data from SBA system of records including EIDL advance details |
| 2 | Save Forgiveness Decision entry as Draft | N/A | UI - Submit New PPP Forgiveness Decision | This is UI only functionality |
| 3 | Submit Forgiveness Decision to SBA | POST /api/ppp_loan_forgiveness_requests/ | UI - Submit New PPP Forgiveness Decision | Supports 3508, 3508 EZ and 3508S format |
| 4 | Upload supporting documents along with Decision | POST /api/ppp_loan_documents/ | UI - Submit New PPP Forgiveness Decision | Forgiveness Portal can also be used to upload initial set of documents for those Forgiveness decisions which were submitted through API. GET /api/ppp_loan_document_types/ provides list of valid document types |
| 5 | Withdraw Forgiveness Decision | DELETE /api/ppp_loan_forgiveness_requests/{slug}/ | UI - All Forgiveness Submission (Withdraw Application) | Decision can only be withdrawn by Lender within 24 Hrs of submission. If after 24 Hrs, lender can request SBA to withdraw Decisions through Inbox Message Functionality. Decisions submitted by API can be withdrawn from Portal and vice versa |
| 6 | Edit Submitted Forgiveness Decisions | N/A | N/A | Once submitted, Decisions data cannot be edited by Lender.Supporting Documents can be uploaded till status is Pending Validation or Lender Additional Info Needed |
| 7 | View Status of a Forgiveness Decision | GET /api/ppp_loan_forgiveness_requests/ | UI - All Forgiveness Submission and select SBA number for details | Status of Decisions submitted by API can be viewed on Portal and vice versa |
| 8 | View Forgiveness Payment Details | GET /api/ppp_loan_forgiveness_requests/ | UI - Payment Dashboard | Only after SBA decision has been made, Forgiveness Decisions are shown on Payment Dashboard. Once Payment is confirmed, notification letter also gets generated |
| 9 | Message - Request for Additional Documents (from SBA to lender) | GET /api/ppp_loan_forgiveness_messages/ | UI - Inbox | For Decision review, notification letter gets generated which is available in both Forgiveness portal and in Get status API |
| 10 | Message - Reply with Additional Documents (from Lender to SBA) | PUT /api/ppp_loan_forgiveness_message_reply/{slug}/ Or POST /api/ppp_loan_documents/ PUT /api/ppp_loan_forgiveness_message_reply/{slug}/ |
UI - Inbox Or UI - All Forgiveness Submission and select SBA number to upload documents UI - Inbox (Please note - Document related Messages cannot be closed without replying using Inbox. This will ensure decisions moving to Pending validation from lender additional info needed, once a lender has uploaded the document and replied back to message). |
If Lender has a complete package; respond to the message and upload documents which will close request. This would indicate SBA is ready for review. Or If Lender doesn’t have full package, they have option to upload documents in stages (Lender and then Borrower docs), and when complete they would formally mark the original request message complete/done to indicate they are completed, and SBA is authorized to review. |
| 11 | Generic/Other Messages (Not document related) between SBA and Lender | GET /api/ppp_loan_forgiveness_messages/ | UI - Inbox | SBA number and Ticket UUID will be null in API response, for messages which are not document related Also such messages can only be replied back via SBA Forgiveness Portal - Inbox |
layout: default title: Design Consideration rank: 850 —
Design Consideration for API’s
API - Design Consideration for Client Application
| API Purpose | API End Point | Design Consideration for Client Application |
|---|---|---|
| The API is used to get the list of available document types in the SBA Forgiveness portal. These document types are needed when sharing documents with SBA, for borrowers forgiveness application. | GET /api/ppp_loan_document_types/ | Document list will not change frequently. For efficiency, Client application may choose to call this API once a day and store results in their cache/storage |
| This API is used to create new forgiveness request for a SBA loan | POST /api/ppp_loan_forgiveness_requests/ | One API call per Forgiveness request.In case Client has large number of forgiveness requests, they may like to call this API using a batch process at their end |
| This API is used to provide supporting documents for a particular Forgiveness request | POST /api/ppp_loan_documents/ | Client may like to call this API immediately after Forgiveness request API call. Documents can only be uploaded using this API when Forgiveness status is Pending validation or Lender additional info needed (scenario - Lender has not submitted any document in first place to SBA, in conjunction with Reply message API). This API also requires document type as input which client can get from 1. Get Document Types. One API call supports sending one document for a forgiveness request.If client is submitting multiple documents for a Forgiveness request, they would have to call this API multiple times. In case Client has large number of forgiveness supporting documents, they may like to call this API by designing batch process at their end. |
| This API fetches the list of ALL forgiveness request for a lender | GET /api/ppp_loan_forgiveness_requests/ | This API provides Status/Details of all submitted forgiveness requests for a Lender. This API supports pagination functionality and if client is designing a UI or batch process to call this API, they may like to have page up and page down feature. Every page returns 50 maximum records. Also this API saves data in cache for 30 seconds after making database call and uses data from cache to send back to client.If client is calling this API without slug id and client’s application takes more than 30 seconds to process complete loan set, its possible that result count may change and order in which data is being send back by API may also change, so client application should handle such scenarios. For Large volume clients, we recommend calling this API end point with slug id as parameter |
| This API is used for getting details of existing forgiveness request using unique slug id (Forgiveness request UUID) | GET /api/ppp_loan_forgiveness_requests/{slug}/ | This API provides Status/Details of a specific submitted forgiveness request. Client may choose to use this API in case they would lke to get latest details of a particular forgiveness request. |
| This API is used for getting details of existing forgiveness request using SBA Number | GET /api/ppp_loan_forgiveness_requests/?sba_number={sba_number} | This API provides Status/Details of a specific submitted forgiveness request. Client may choose to use this API in case they would lke to get latest details of a particular forgiveness request. |
| This API is used for deleting the existing Forgiveness request | DELETE /api/ppp_loan_forgiveness_requests/{slug}/ | Client may use this API to delete forgiveness request and corresponding supporting documents.Please note - For any reason, if client would like to delete Forgiveness request, they may to call this API within 24 hrs of original submission, before SBA starts reviewing forgiveness. Once SBA starts reviewing a request, it cannot be deleted. |
| During review of a Forgiveness request, SBA may require additional information from Lender or Lender may have questions for SBA. This API is used to retrieve all messages for a Lender. | GET /api/ppp_loan_forgiveness_messages/ | Client may like to call this API to retrieve all messages for all their Forgiveness requests. This API supports pagination functionality and if client is designing a UI or batch process to call this API, they may like to have next page and previous page feature. Every page returns 50 maximum records. |
| During review of a Forgiveness request, SBA may require additional information from lender. This API is used to retrieve additional document messages sent by SBA to Lender using Forgiveness UUID. SBA can send single message to the Lender at a time which is indicated by the API field is_complete: false. Once Lender replies back the API field updates to is_complete: true and then SBA may send additional message if required. | GET /api/ppp_loan_forgiveness_messages/{slug}/ | Client may like to call this API to retrieve messages send by SBA to Lender for a particular forgiveness request. |
| During review of a Forgiveness request, SBA may require additional information from lender. This API is used to retrieve messages sent by SBA to lender using SBA number.SBA can send single message to the Lender at a time which is indicated by the API field is_complete: false. Once Lender replies back the API field updates to is_complete: true and then SBA may send additional message if required. | GET /api/ppp_loan_forgiveness_messages/?sba_number={sba_number} | Client may like to call this API to retrieve messages send by SBA to Lender for a particular forgiveness request. |
| During review of a Forgiveness request, SBA may require additional information from lender. This API is used by lender to respond back to SBA | PUT /api/ppp_loan_forgiveness_message_reply/{slug}/ Content-type: multipart/form-data/ | This API needs the forgiveness request slug as path parameter in input. Client would have to call Get Forgiveness Message API to get details of additional document/s SBA is asking Lender to provide. If Lender wants to reply back with multiple documents, they must include all of them in single API call.Lender also has an option to use POST /api/ppp_loan_documents/ to send all additional documents and finally reply back with ppp_loan_forgiveness_message_reply API confirming SBA to resume decision review |
| Allows Lender/Vendor to ensure a loan is in a proper disposition to accept a forgiveness decision. Using this API, you can look up disbursed PPP loans | GET /api/ppp_loan_validations/ | This API can be used by Lender/Vendor to lookup disbursed loan data. This API supports pagination functionality and if client is designing a UI or batch process to call this API, they may like to have page up and page down feature. Every page returns 50 maximum records. New disbursed Loans will be added once a day. |
Slug ID or UUID - Usage
| Slug ID type | Usage |
|---|---|
| Forgiveness Request - Slug ID | Client will receive it as part of the response of Create Forgiveness Request API. This slug can be used by client while making following API calls - Get status of Forgiveness, Delete Forgivenes, Get Forgiveness message & replying back to SBA with additional documents (Reply to SBA message) |
| Etran Loan - Slug ID | Client will receive it as part of response of Create Forgiveness Request API. This slug can be used by client while sending supporting documents for a Forgiveness request (Upload Forgiveness documents) |
| Ticket Slug ID | This is same as Forgiveness Request Slug id & Client will also receive it as part of response of Get Forgiveness Messages API. This slug can be used by client while replying back to SBA with additional documents (Reply to SBA message) |
| Document Slug ID | Client will receive this slug as part of response of Upload Forgiveness documents API |
| Organization Slug ID | Client will receive this slug as part of response of Get Forgiveness Request API |
Lender Decision Vs Forgiveness Decision Mapping
| Lender Decision | SBA Decision | Forgiveness Decision Status |
|---|---|---|
| APPROVED_IN_FULL = 0 | Fully Approved | Fully Approved |
| APPROVED_IN_FULL = 0 | Partially Approved | Partially Approved |
| APPROVED_IN_FULL = 0 | Not Approved | Not Approved |
| APPROVED_IN_PART = 1 | Fully Approved | Fully Approved |
| APPROVED_IN_PART = 1 | Partially Approved | Partially Approved |
| APPROVED_IN_PART = 1 | Not Approved | Not Approved |
| DENIED = 2 | Not Approved | Not Approved |
| DENIED = 2 | Fully Approved | Fully Approved |
API vs Portal - Functionality
| SNo | Functionality | API | SBA Forgiveness Portal | Comments |
|---|---|---|---|---|
| 1 | Review Disbursed PPP Loans | GET /api/ppp_loan_validations/ | UI - Lookup Disbursed PPP Loans | Reflects data from SBA system of records including EIDL advance details |
| 2 | Save Forgiveness Decision entry as Draft | N/A | UI - Submit New PPP Forgiveness Decision | This is UI only functionality |
| 3 | Submit Forgiveness Decision to SBA | POST /api/ppp_loan_forgiveness_requests/ | UI - Submit New PPP Forgiveness Decision | Supports 3508, 3508 EZ and 3508S format |
| 4 | Upload supporting documents along with Decision | POST /api/ppp_loan_documents/ | UI - Submit New PPP Forgiveness Decision | Forgiveness Portal can also be used to upload initial set of documents for those Forgiveness decisions which were submitted through API. GET /api/ppp_loan_document_types/ provides list of valid document types |
| 5 | Withdraw Forgiveness Decision | DELETE /api/ppp_loan_forgiveness_requests/{slug}/ | UI - All Forgiveness Submission (Withdraw Application) | Decision can only be withdrawn by Lender within 24 Hrs of submission. If after 24 Hrs, lender can request SBA to withdraw Decisions through Inbox Message Functionality. Decisions submitted by API can be withdrawn from Portal and vice versa |
| 6 | Edit Submitted Forgiveness Decisions | N/A | N/A | Once submitted, Decisions data cannot be edited by Lender.Supporting Documents can be uploaded till status is Pending Validation or Lender Additional Info Needed |
| 7 | View Status of a Forgiveness Decision | GET /api/ppp_loan_forgiveness_requests/ | UI - All Forgiveness Submission and select SBA number for details | Status of Decisions submitted by API can be viewed on Portal and vice versa |
| 8 | View Forgiveness Payment Details | GET /api/ppp_loan_forgiveness_requests/ | UI - Payment Dashboard | Only after SBA decision has been made, Forgiveness Decisions are shown on Payment Dashboard. Once Payment is confirmed, notification letter also gets generated |
| 9 | Message - Request for Additional Documents (from SBA to lender) | GET /api/ppp_loan_forgiveness_messages/ | UI - Inbox | For Decision review, notification letter gets generated which is available in both Forgiveness portal and in Get status API |
| 10 | Message - Reply with Additional Documents (from Lender to SBA) | PUT /api/ppp_loan_forgiveness_message_reply/{slug}/ Or POST /api/ppp_loan_documents/ PUT /api/ppp_loan_forgiveness_message_reply/{slug}/ |
UI - Inbox Or UI - All Forgiveness Submission and select SBA number to upload documents UI - Inbox (Please note - Document related Messages cannot be closed without replying using Inbox. This will ensure decisions moving to Pending validation from lender additional info needed, once a lender has uploaded the document and replied back to message). |
If Lender has a complete package; respond to the message and upload documents which will close request. This would indicate SBA is ready for review. Or If Lender doesn’t have full package, they have option to upload documents in stages (Lender and then Borrower docs), and when complete they would formally mark the original request message complete/done to indicate they are completed, and SBA is authorized to review. |
| 11 | Generic/Other Messages (Not document related) between SBA and Lender | GET /api/ppp_loan_forgiveness_messages/ | UI - Inbox | SBA number and Ticket UUID will be null in API response, for messages which are not document related Also such messages can only be replied back via SBA Forgiveness Portal - Inbox |
Direct Forgiveness - Life cycle and Status Mapping
| SNo | Functionality | Direct Forgiveness Portal - Borrower Facing Status | SBA Forgiveness Portal - Direct Forgiveness Menu - Lender Facing Status or GET /api/direct_forgiveness_requests/ | SBA Forgiveness Portal - All Forgiveness Portal - Lender Facing Status |
|---|---|---|---|---|
| 1 | Borrower editing direct forgiveness application | Request in Progress | N/A | N/A |
| 2 | Borrower submitted direct forgiveness application but have signature pending | E-Signature Pending | N/A | N/A |
| 3 | Borrower completed e-signature | E-Signature Processing | N/A | N/A |
| 4 | Borrower application pending transmission to SBA portal for Lender to review | Submission pending | N/A | N/A |
| 5 | Borrower application transmitted to SBA portal for Lender to review | Submitted to lender | Pending | N/A |
| 6 | Lender Approves Direct Forgiveness application | Lender Decision (Accepted) | Approved | Pending Validation |
| 7 | Lender declines Direct Forgiveness application | Lender Decision (Rejected) | Rejected | N/A |
| 8 | Lender asks borrower to edit and resubmit application | Lender Decision (Correction) | Borrower correction | N/A |
| 9 | Lender approval to SBA fails due to change in etran loan data | Submitted to lender | Failed validation | N/A |
| 10 | SBA reviewing direct forgiveness application | Lender Decision (Accepted) | Approved | Under Review |
| 11 | SBA approves application - full approval | SBA Decision (Fully Approved) | Approved | Fully Approved |
| 12 | SBA approves application - Partial approval | SBA Decision (Partially Approved) | Approved | Partially Approved |
| 13 | SBA doesnot approve application | SBA Decision (Not Approved) | Approved | Not Approved |
| 14 | SBA processes Payment | SBA Decision (Fully Approved) or SBA Decision (Partially Approved) | Approved | Fully Approved or Partially Approved |