Logo

Documentation for US SBA PPP Loan Forgiveness API

Home
3508 Form - Fields Mapping to API Elements
3508EZ Form - Fields Mapping to API Elements
3508S Form - Fields Mapping to API Elements
Use Case 1 - Submission of Forgiveness Request for SBA decisioning
Use Case 2 - Re-submission of Forgiveness
Use Case 3 - Get latest status of Forgiveness
Use Case 4 - Get document types
Use Case 5 - Additional Document Upload
Use Case 6 - Lookup/Validate disbursed Loans
Use Case 7 - Direct Forgiveness
Use Case 8 - Guaranteed purchase
API Dictionary
API HTTP Response Codes
Design Consideration
Github Repo - sample code
Forgiveness Decision - Status Map
Payment Processing
FAQ
Release notes
Originations Github Documentation

SBA Loan Forgiveness Platform FAQ - Developer Notes

1. How will client get Keys for the API

Client will need two keys to access the APIs for the Forgiveness platform: First, they will need vendor key that will uniquely identify their organization as a consumer of these APIs. This will be provided as part of their on-boarding.
(If you have previously interacted with the ETRAN APIs or have expressed an interest in the Forgiveness APIs, you will automatically be invited once the platform is ready. If not, please send an email to developer@ussbaforgiveness.com)

Second, they will need to obtain a Bank API key that will allow you access to perform work for (or on behalf of) a given financial institution. For production, this key will need to be provided directly from the financial institution and can be found within the Forgiveness portal. This key is found within the user profile of an enabled “API User”. Please note, we are advising as a best practice that the Lender to create an unique API user within the Forgiveness Portal.

2. Where is endpoint URL

Environment: All the forgiveness API’s are exposed in the Sandbox and Production environment

Environment URL
Sandbox https://sandbox.forgiveness.sba.gov/
Production https://forgiveness.sba.gov/

3. FQDN (Fully qualified domain name) to be whitelisted for calling API’s

forgiveness.sba.gov

Also to upload and access documents (Amazon S3), here are the details

Environment URL
Sandbox lenders-cooperative-sandbox-app.s3.us-gov-west-1.amazonaws.com
Production lenders-cooperative-prod-app.s3.us-gov-west-1.amazonaws.com
DR lenders-cooperative-prod-app-2.s3.us-gov-east-1.amazonaws.com

4. Do you have sample code which clients may be able to use for API interface

Sample C#, Java and Python code can be found at our github repositories here

5. What is the flow of API calls

See the 5 Use Cases for details of API calls flow

6. Some of our borrowers have submitted 10 documents in support of their PPP Forgiveness request, can we use your API to send all these documents at the time of forgiveness submission even if the SBA hasn’t requested all these documents?

Yes, the SBA will accept the required documents (3508, 3508EZ forms) and any other supporting documents a lender may wish to submit in support of their forgiveness decision. This may in-fact be prudent given SBA’s guidance on their review strategy for loans greater than $2MM.

7. Do you have a limit on maximum number of documents?

There is no max in terms of number of documents. We would ask you to be responsible on how you design your Forgiveness framework. We have some lenders and FinTechs that are aggregating documents, some that are doing individual documents. We recognize that how lenders and borrowers submit these are different and we are not imposing a max number of documents. We have a max document size limit of 35 MB/document.

8. Has this system been load tested, how much volume can the Forgiveness platform handle?

This system was sized to handle an extremely high number of API calls. We want to ensure optimum performance on status calls and submissions into the platform. As an industry platform, we would ask for your responsible stewardship using this platform. Questions on design, batch processing or other performance considerations can be directed to: developer@ussbaforgiveness.com

9. Looking at your process flow, there was not differentiation between loans above/below $2 million. Isn’t the process different both in terms of data, APIs and decisioning around $2 million? (as lenders approve those below, and the SBA approves those above?)

API’s support Forgivenss request for any Loan amount.The documentation set, if loans above $2 million are going to be reviewed, could potentially be richer than, as an example, than a decision supporting a 3508EZ submission.

10. When uploading documents does the API have the ability to know which document type it belongs to like payroll, rent, utilities?

Yes, we have document types defined in the platform. Please reference documentation on the Get Document Types API for this information.

11. Are there request limits on the forgiveness status endpoints?

We don’t have published limits that would throttle your ability to use these APIs. We have built this system with additional capacity to support frequent status inquiry by Lenders and Fintechs. Practically speaking, the request do not change statuses frequently. There will be multiple days, likely, between statuses. The idea that a given FinTech would pull these on a fifteen-minute basis would probably not be practical, so we ask that you design your systems accordingly. Be good stewards of the system. To maintain reliability and stability within our environments, Forgiveness portal operates with certain API call efficiency guidelines. To ensure effective load balance we continually monitor the API calls to our backend systems and we may throttle requests from developers that are putting unnecessary burden on the system. If the API call rate limit is reached, client will receive an exception

12. Do you need to submit a forgiveness request application for each individual PPP loan?

Yes. Each PPP Loan requires a Forgiveness submission. You can only submit a single forgiveness decision against a single PPP loan.

13. What frequency is the information updated in the platform?

The platform you are leveraging the APIs from is the platform that the requests are being worked upon by the SBA. It is inherently real-time. If the request is reviewed and dispositioned, and ultimately pushed for payment those would be available via the statuses in the APIs.

14. The size per document is 35MB. Is that before base64 encoding or after base64 encoding? Can you confirm this is not the json payload size?

We are enforcing using AWS WAF at 35 meg body size of request; your practical file size would be slightly less than 35 megs. Please ensure you are using multipart/form-data for data upload (and not base 64 encoding). Refer to GitHub page (API data dictionary) for sample

15. The getForgivenessStatus seemed to be return status for either one application at a time or everything for an org, with pagination. What is the input – is it just the keys in the header and possibly the lender organization id, and a page number?

To get all forgiveness requests (for an org) there is no additional mandatory input. Of-course all API’s need Auth token and Vendor key in the https header. The system maps the organization with the corresponding Auth key. This returns the paginated response with 50 requests/page. To loop through the individual pages the same API can be called with page number in the query parameter – there is a ‘next’ field which also contains the API url of the subsequent page and its value will be ‘null’ for the last page (this parameter can be used for your looping logic).

16. In the case of a pagination response, is the response sorted?

The response is sorted by earliest forgiveness ticket first

17. In a multi-paginated response, how many records would you return per page? Is there a limit on the number of pages?

There is no limit on number of pages. The response returns 50 requests/page.

18. Few Lenders expect to have between 150 thousand and 200 thousand forgiveness requests. What would be the response size and response time per page, and overall?

The responses are standard json format (few hundred KB’s) and response times are sub seconds for each API

19. Since there are new PPP requests coming in through August, how do you expect to treat those that came in after the first page request was made but before the final page request was completed?

New client applications (for PPP loans) will not flow into forgiveness platform, real time. Instead there is a nightly batch process which will synch up the delta between etran and forgiveness platforms. Ultimately those new applications will end up in forgiveness platform. As a reminder, for requests to be eligible, they must be fully disbursed within the system of record (ETRAN servicing or via the 1502 reporting process).

20. Can you confirm there is no explicit requirement to split up into 3508 and Schedule A? While having two doc types is logical, the SBA published 3508 and the Schedule A as one document on their website page, and we expect a fair number to be combined.

There is no specific requirement to break these documents from API perspective. API does support 3508 and Schedule A as different document types. Schedule A worksheet, Schedule A worksheet Table 1, Schedule A worksheet table 2 are also available as document types. Client applications have the flexibility to implement solutions based on their business needs.

21. How does a vendor get added to the distribution list and access to the API

Send an email to developer@ussbaforgiveness.com

22. Can you please clarify how we should understand the decision status from the SBA and the Payment Status from the SBA?

Within the platform, we expose two status values for an individual forgiveness decisions.

  1. status = this value indicates the overall phase of the Forgiveness decision – up to and including the Payment status (including: Pending Validation, Under Review, Fully Approved, Not Approved, Partially Approved, Lender Additional Info Needed, Payment Sent, Payment Confirmed, Payment Failed)
  2. sba_decision = this value will always indicate the status of the SBA Decision only. In this case, Fully Approved, Partially Approved, Not Approved. This may not include other reviews and approvals required for payment to the lender.

23. Is the Under Review status indicative of the SBA initiating a loan review, as described on page 7 of the Procedural Notice? By default, is it not expected that Lenders provide forgiveness application supporting documentation (such as payroll) unless the SBA has indicated that the loan is under review?

The Under-Review status in the platform is only for the Forgiveness process. This effectively means it is in processing by the SBA. This is not related to the SBA Loan Review process.

24. For 3508EZ, the Procedural Notice lists “the SBA Form 3508EZ or Lender’s equivalent form” and the PPP Borrower Demographic Form to be submitted to the Forgiveness Platform. Will we need to produce PDF versions of this data that will already be submitted to the Forgiveness API via the request parameters?

Yes; the guidance still requires the original 3508/3058EZ signed forms. This is important, as your lender decision is “your data” and in many cases it will match the signed PDFs. However, in some cases, it will not. Therefore, in all cases you will need to transmit the PDF/signed documentation via our API.

25. The Procedural Notice indicates on page 7 that, in the event of a Lender declining a borrower’s application, “the lender must…provide SBA with the reason(s) for its denial.” What API request parameter should we use to provide the “reason for denial”? Is there a predefined list of reasons?

Yes – if you look at the API documentation - > https://ussbaforgiveness.github.io/API-Dictionary.html you will see forgive_lender_decision and related documentation. At this point, we haven’t exposed a field to pass this information. We suggest on these rare denial situations you would use the document upload capability

26. What’s the API Certification process

Applications using SBA Forgiveness APIs must go through the certification process to operate in our production environment. As a pre-requisite, Vendors need to have sandbox API access, build and test their application interface using Sandbox API’s. Once vendors have completed sandbox interface development & testing succesfully, they need to open a ticket with developer@ussbaforgiveness.com asking for a Production access. SBA Development team will review Sandox API usage for the Vendor and will approve/reach out to Vendor.

27. If a Vendor supports many Lenders, do they need to certify for each lender?

No. API certification in Sandbox is intended to certify a vendor to engage and support forgiveness. This certification allows them to support an individual bank or many banks

28. What’s exposed via our messaging API

These message APIs are not intended to convey internal reasons or SBA internal comments to the file. These APIs are intended to communicate that documents are required, or other general messaging around certain requests have been sent to the Lender. This is also why we expose if they are past due, indicating that a Lender is overdue (the 5 days) in getting the documents back to the SBA.

29. When a Lender arrives at a decision that is the same as borrower, but the individual 3508 line items may be different. What’s the Lender decision suggested

In this case, a Lender would still submit an Approved in Full decision to the SBA. The decision is based on the overall bottom line amount.

30. Payment fields in API - Plz elaborate

In the API, the “interest to” date – will be based on the final_forgive_payment_date. Effectively, the SBA is paying interest until the point they are making the payments. Second, EIDL will be removed from the (final_forgive_amount) and the resulting value will be your net payment: (final_forgive_payment). This includes: Interest, Foveness and any netted EIDL). Refer to Forgiveness Decision - Status Map

31. Forgiveness Document - File extensions supported

.pdf,.xls,.xlsx,.csv,.doc,.docx,.jpg,.jpeg,.png with max 35 MB / payload

32. Can the document be uploaded using Portal

a) If the decision request is initiated by lender using Portal, documents need to be submitted along with decision in portal.
b) If the decision request is initiated using API, documents can also be submitted either by API or by Portal
c) In case SBA needs additional document from Lender, they can be attached via Portal or replied back via API

33. When can documents supporting a forgiveness request be provided to SBA

Documents can be provided after a forgiveness decision has been submitted by Lender to SBA. Need to have a Forgiveness decision created before you can associate documents.
For the initial document submissions, use this document API (ppp_loan_documents). Ensure that forgiveness status is either: Pending validation (SBA has not started processing this request) or Lender Additional Info Needed (Lender never submitted any documents to the SBA).
In response to SBA specifically asking for additional documentation, use API ppp_loan_forgiveness_message_reply or reply back via Portal

34. Is the Forgiveness amount submitted by Lender based on the original PPP disbursement amount or current outstanding balance of the loan

PPP forgiveness will be submitted using the PPP disbursement amount – which would be properly maintained within ETRAN. An originated loan of $1MM, which was subsequently only disbursed at $900k, would require a forgiveness decision of $900k to be submitted for full forgiveness. In this situation, the Lender should have maintenance ETRAN to reflect the disbursement of $900k and the resulting forgiveness amount would match.

35. How should Lenders and Software providers incorporate the lender confirmation language from the SBA when interacting with the API?

Lenders should use “forgive_lender_confirmation” element in the /api/ppp_loan_forgiveness_requests/ API. This Boolean provides the SBA of the status of the lender confirmation. Please ensure this flag is set to TRUE. When using the API, Lenders and Software providers should include the full language in the SBA Procedural Notice inside their application. The API does not remove the requirement of a Lender to confirm. The SBA does not intend to provide any additional forms to utilize.

36. What critical elements of Lender Confirmation language do lenders need to include on the existing API?

While the SBA Procedural notice should be referenced, please find the relevant sections below:

37. Borrower does not want to advance a Forgiveness request. Should Lender submit Forgiveness Decision?

In the situation where a customer does not want to advance a forgiveness application, Lender doesn’t have have to submit this to the platform. In this case, you don’t have a proper 3508/EZ form signed to submit as part of your decision.

38. Lenders will receive individual transactions per loan (not separate transactions for principle vs. interest or bulk payments for multiple loans), please confirm?

39. When performing a DELETE against a forgiveness request we receive a 404 “not found”?

Ensure you use the SLUG of the forgiveness request and NOT the slug of the SBA loan.

40. Does Client needs to pass Optional fields with null values in API input?

We recommend clients to omit optional fields in API input if they don’t have relevant borrower Loan/Forgiveness data instead of sending them with null values.

41. What is the valid Routing Number to be used in Sandbox?

We recommend clients to use 923456789 as a valid routing number and update Institutional Payment Settings. This will ensure interest and forgiveness payment calculation in Sandbox when test payment batch runs.