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
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
DENIED_WITHOUT_PREJUDICE_DUE_TO_PENDING_SBA_REVIEW = 3   Under Review

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 Once authorized by SBA, EIDL advance from SBA system of record will only be shown for those Loans where Forgiveness decision has been submitted by Lender to SBA
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 both 3508 and 3508 EZ 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
9 Message - Request for Additional Documents (from SBA to lender) GET /api/ppp_loan_forgiveness_messages/ UI - Inbox  
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