Forgiveness Portal APIs - API Dictionary
Table of Contents
- Pre-requisites
- Environment
- 1. Get Document Types
- 2. Create Forgiveness Request
- 3. Upload Forgiveness documents
- 4. Get Details of ALL Forgiveness Requests
- 5. Get Forgiveness Request Details using UUID
- 6. Get Forgiveness Request Details using SBA Number
- 7. Delete Forgiveness Request
- 8. Get Forgiveness Messages
- 9. Get Forgiveness Message using UUID
- 10. Get Forgiveness Message using SBA Number
- 11. Reply to SBA Message
- 12. Validate/Lookup Disbursed PPP Loan
- 13. Get All Forgiveness Documents
- 14. Get Direct Forgiveness Details
- 15. Get Guarantee purchase Details
- 16. Get Guarantee purchase Details by SBA Number
This document gives an overview for the API’s that are exposed by the forgiveness portal.
Pre-requisites:
Authorization: All the API’s require Authorization parameters that are needed to be passed in each of the API request. Please refer to the API Pre-requisites section on Home page.
Important: All API end points must match API dictionary format, for instance having “/” at the end of the URL request for POST, PUT & DELETE API requests.
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/ |
1. Get Document Types
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 on behalf of borrowers.
Request type: HTTPS
API Endpoint:
GET /api/ppp_loan_document_types/
Request (Sample)
/api/ppp_loan_document_types/
Request Parameters
Not Applicable (No request body)
Request Path Parameters
Not Applicable
Request Query Parameters
Not Applicable
Request Form Data Parameters
Not Applicable
Response (Sample)
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"name": "SBA Form 2483",
"description": "SBA Form 2483"
}
]
}
Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| count | Number | 1 | The total count of the document types |
| next | String | null | The URI of the next set of document types to be fetched |
| previous | String | null | The URI of the previous set of document types to be fetched |
| results | JSON Array |
||
| id | Number | 1 | The id of the document type as defined in SBA System |
| name | String | SBA Form 2483 | The name of the document |
| description | String | SBA Form 2483 | The description of the document |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
Document list will not change frequently. For efficiency, Client applications may choose to call this API once a day and store results in their cache/storage.
2. Create Forgiveness Request
This API is used to create a new forgiveness request (decision) for an SBA PPP loan.
- Note - If field is optional and user does not have a valid value for that field, those fields may be omitted in JSON input
Request type: HTTPS
API Endpoint:
POST /api/ppp_loan_forgiveness_requests/
Request (Sample Body 3508)
{
"etran_loan": {
"bank_notional_amount": 900000.00,
"sba_number": "9999114733",
"loan_number": "7777777",
"entity_name": "Abc Inc",
"ein": "997114733",
"funding_date": "2020-07-06",
"forgive_payroll": 1000.00,
"forgive_rent": 1000.00,
"forgive_utilities": 1000.00,
"forgive_mortgage": 1000.00,
"forgive_covered_operations_expenditures": 1000.00,
"forgive_covered_property_damage_costs": 1000.00,
"forgive_covered_supplier_costs": 1000.00,
"forgive_covered_protection_expenditures": 1000.00,
"naics_code" : 722513, (available in prod - 03/05)
"ppp_loan_draw" : 1, (available in prod - 03/05)
"address1": "5050 Ritter Road – Suite B",
"address2": "Mechanicsburg, PA",
"dba_name": "Abc Inc",
"phone_number": "6102342123",
"forgive_fte_at_loan_application": 10,
"demographics": [
{
"name": "Jason",
"position": "self-employed individual",
"veteran_status": "1",
"gender": "M",
"ethnicity": "H",
"races": [
{
"race": "1"
}
]
}
],
"forgive_line_6_3508_or_line_5_3508ez": 3999.00,
"forgive_modified_total": 3999.00,
"forgive_payroll_cost_60_percent_requirement": 1666.66,
"forgive_amount": 1666.66,
"forgive_fte_at_forgiveness_application": 10,
"forgive_schedule_a_line_1": 1.00,
"forgive_schedule_a_line_2": 1.00,
"forgive_schedule_a_line_3_checkbox": true,
"forgive_schedule_a_line_3": 1.00,
"forgive_schedule_a_line_4": 1.00,
"forgive_schedule_a_line_5": 1.00,
"forgive_schedule_a_line_6": 1.00,
"forgive_schedule_a_line_7": 1.00,
"forgive_schedule_a_line_8": 1.00,
"forgive_schedule_a_line_9": 1.00,
"forgive_schedule_a_line_10": 6.00,
"forgive_schedule_a_line_10_checkbox": true,
"forgive_schedule_a_line_11": 10.00,
"forgive_schedule_a_line_12": 10.00,
"forgive_schedule_a_line_13": 1.00,
"forgive_covered_period_from": "2020-07-06",
"forgive_covered_period_to": "2020-09-06",
"primary_email": "user@example.com",
"primary_name": "Jason",
"ez_form": false,
"no_reduction_in_employees": true,
"no_reduction_in_employees_and_covid_impact": true,
"forgive_lender_confirmation": true,
"forgive_lender_decision": 1,
"loan_increase": 1000.00,
"loan_increase_date": "2020-07-09"
}
}
Request (Sample Body 3508 EZ)
{
"etran_loan": {
"bank_notional_amount": 900000.00,
"sba_number": "9999114733",
"loan_number": "7777777",
"entity_name": "Abc Inc",
"ein": "997114733",
"funding_date": "2020-07-06",
"forgive_payroll": 1000.00,
"forgive_rent": 1000.00,
"forgive_utilities": 1000.00,
"forgive_mortgage": 1000.00,
"forgive_covered_operations_expenditures": 1000.00,
"forgive_covered_property_damage_costs": 1000.00,
"forgive_covered_supplier_costs": 1000.00,
"forgive_covered_protection_expenditures": 1000.00,
"naics_code" : 722513, (available in prod - 03/05)
"ppp_loan_draw" : 1, (available in prod - 03/05)
"address1": "5050 Ritter Road – Suite B",
"address2": "Mechanicsburg, PA",
"dba_name": "Abc Inc",
"phone_number": "6102342123",
"forgive_fte_at_loan_application": 10,
"demographics": [
{
"name": "Jason",
"position": "self-employed individual",
"veteran_status": "1",
"gender": "M",
"ethnicity": "H",
"races": [
{
"race": "1"
}
]
}
],
"forgive_line_6_3508_or_line_5_3508ez": 4000.00,
"forgive_payroll_cost_60_percent_requirement": 1666.66,
"forgive_amount": 1666.66,
"forgive_fte_at_forgiveness_application": 10,
"forgive_covered_period_from": "2020-07-06",
"forgive_covered_period_to": "2020-09-06",
"primary_email": "user@example.com",
"primary_name": "Jason",
"ez_form": true,
"forgive_lender_confirmation": true,
"forgive_lender_decision": 1,
"loan_increase": 1000.00,
"loan_increase_date": "2020-07-09"
}
}
Request (Sample Body 3508 S)
{
"etran_loan": {
"bank_notional_amount": 900000.00,
"sba_number": "9999114733",
"loan_number": "7777777",
"entity_name": "Abc Inc",
"ein": "997114733",
"funding_date": "2020-07-06",
"forgive_payroll": 1000.00,
"naics_code" : 722513, (available in prod - 03/05)
"ppp_loan_draw" : 1, (available in prod - 03/05)
"address1": "5050 Ritter Road – Suite B",
"address2": "Mechanicsburg, PA",
"dba_name": "Abc Inc",
"phone_number": "6102342123",
"forgive_fte_at_loan_application": 10,
"demographics": [
{
"name": "Jason",
"position": "self-employed individual",
"veteran_status": "1",
"gender": "M",
"ethnicity": "H",
"races": [
{
"race": "1"
}
]
}
],
"forgive_amount": 1666.66,
"forgive_fte_at_forgiveness_application": 10,
"forgive_covered_period_from": "2020-07-06",
"forgive_covered_period_to": "2020-09-06",
"primary_email": "user@example.com",
"primary_name": "Jason",
"ez_form": false,
"forgive_lender_confirmation": true,
"forgive_lender_decision": 1,
"s_form": true,
"loan_increase": 1000.00,
"loan_increase_date": "2020-12-29"
}
}
Request Parameters
| Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| etran_loan | JSON Object |
Mandatory | ||
| bank_notional_amount | Number | Mandatory | 900000.00 | The PPP loan amount |
| sba_number | String | Mandatory | 9999114733 | The SBA loan number. Only Numbers are allowed. |
| loan_number | String | Mandatory | 7777777 | The Lender’s loan number. |
| entity_name | String | Mandatory | Abc Inc | The entity name of the borrower |
| ein | String | Mandatory | 997114733 | The SSN or Business TIN of the borrower. Only Numbers are allowed. |
| funding_date | String | Mandatory | 2020-07-06 | PPP loan Disbursement date in YYYY-MM-DD |
| forgive_eidl_amount | Number | Optional | 100.00 | The EIDL amount. Can be provided without providing the EIDL application number. (Not-applicable in prod - 03/05) |
| forgive_eidl_application_number | Number | Optional | 123456789 | The Application number of the EIDL, decimals values are not allowed. This number is validated against SBA system of records. (Not-applicable in prod - 03/05) |
| forgive_payroll | Number | Mandatory (for 3508, 3508EZ (& 3508S from 03/05 in prod, should be >= 60% of Forgiveness amount)) |
1000.00 | Payroll Cost. Should be same as Schedule A Line 10 (forgive_schedule_a_line_10) |
| forgive_rent | Number | Mandatory (for 3508, 3508EZ) |
1000.00 | Business Rent or Lease Payments |
| forgive_utilities | Number | Mandatory (for 3508, 3508EZ) |
1000.00 | Business Utility Payments |
| forgive_mortgage | Number | Mandatory (for 3508, 3508EZ) |
1000.00 | Business Mortgage Interest Payments |
| address1 | String | Mandatory | 5050 Ritter Road – Suite B | Business Address Line 1 |
| address2 | String | Mandatory | Mechanicsburg, PA | Business Address Line 2 |
| dba_name | String | Optional | Abc Inc | The DBA Name or Trade Name of the borrower |
| phone_number | String | Mandatory | 6102342123 | The Business Phone Number of the borrower |
| forgive_fte_at_loan_application | Number | Mandatory | 10 | The full time employees at the time of loan application, decimal values are not allowed |
| demographics | JSON Array |
Optional | If demographics is selected, then use the below demographic fields as applicable | |
| name | String | Optional | Jason | The Principal name |
| position | String | Optional | self-employed individual | Identify the Principal’s position; for example, self-employed individual; independent contractor; sole proprietor; general partner; owner; officer; director; member; or key employee. |
| veteran_status | String | Optional | 1 | The veteran status of the borr ower. Possible Values: [ 1, 2, 3, 4, X ] 1=Non-Veteran; 2=Veteran; 3=Service-Disabled Veteran; 4=Spouse of Veteran; X=Not Disclosed |
| gender | String | Optional | M | The gender of the borrower. Possible Values: [M, F, X ] M=Male; F=Female; X=Not Disclosed |
| ethnicity | String | Optional | H | The ethnicity of the borrower. Possible Values: [H, N, X ] H=Hispanic or Latino; N=Not Hispanic or Latino; X=Not Disclosed |
| races | JSON Array |
Mandatory | ||
| race | String | Optional | 1 | The race of the borrower. Possible Values: [1, 2, 3, 4, 5, X ] 1=American Indian or Alaska Native; 2=Asian; 3=Black or African-American; 4=Native Hawaiian or Pacific Islander; 5=White; X=Not Disclosed |
| forgive_line_6_3508_or_line_5_3508ez | Number | Mandatory (for 3508, 3508EZ) |
3999.00 | Line 6 (Line 10 of new form) of 3508 or line 5 (Line 9 of new form) of 3508 EZ, starting 03/05 in prod they will reflect new lines |
| forgive_modified_total | Number | Mandatory (for 3508) |
3999.00 | Modified Total - line 8 |
| forgive_payroll_cost_60_percent_requirement | Number | Mandatory (for 3508, 3508EZ) |
1666.66 | Payroll cost 60% requirement |
| forgive_amount | Number | Mandatory | 1666.66 | Forgiveness Amount. This field must be 0 if the lender decision is Denied. API validation also expects other amount related fields used in determining forgive amount, as per 3508/3508EZ, to be 0.For approved in full or partial approved Lender decision,the forgiveness amount should be greater than zero and cannot be greater than loan amount |
| forgive_fte_at_forgiveness_application | Number | Mandatory | 10 | Full time employees at the time of forgiveness application, decimal values are not allowed |
| forgive_schedule_a_line_1 | Number | Mandatory (for 3508) |
1.00 | Cash Compensation (Box 1) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_2 | Number | Mandatory (for 3508) |
1.00 | Average FTE (Box 2) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_3_checkbox | Boolean | Mandatory (for 3508) |
true | Salary/Hourly Wage Reduction (Box 3) from PPP Schedule A Worksheet, Table 1: If the average annual salary or hourly wage for each employee listed on the PPP Schedule A Worksheet, Table 1 during the Covered Period or the Alternative Payroll Covered Period was at least 75% of such employee’s average annual salary or hourly wage between January 1, 2020 and March 31, 2020, then set to true and put the value as 0 for field forgive_schedule_a_line_3 |
| forgive_schedule_a_line_3 | Number | Mandatory (for 3508) |
1.00 | Salary/Hourly Wage Reduction (Box 3) from PPP Schedule A Worksheet, Table 1. Should have value of 0, in case check box (forgive_schedule_a_line_3_checkbox) is selected |
| forgive_schedule_a_line_4 | Number | Mandatory (for 3508) |
1.00 | Cash Compensation (Box 4) from PPP Schedule A Worksheet, Table 2 |
| forgive_schedule_a_line_5 | Number | Mandatory (for 3508) |
1.00 | Average FTE (Box 5) from PPP Schedule A Worksheet, Table 2 |
| forgive_schedule_a_line_6 | Number | Mandatory (for 3508) |
1.00 | Total amount paid or incurred by Borrower for employer contributions for employee health insurance |
| forgive_schedule_a_line_7 | Number | Mandatory (for 3508) |
1.00 | Total amount paid or incurred by Borrower for employer contributions to employee retirement plans |
| forgive_schedule_a_line_8 | Number | Mandatory (for 3508) |
1.00 | Total amount paid or incurred by Borrower for employer state and local taxes assessed on employee compensation |
| forgive_schedule_a_line_9 | Number | Mandatory (for 3508) |
1.00 | Total amount paid to owner-employees/self-employed individual/general partners |
| forgive_schedule_a_line_10 | Number | Mandatory (for 3508) |
6.00 | Total Payroll Costs (add lines 1, 4, 6, 7, 8, and 9) |
| forgive_schedule_a_line_10_checkbox | Boolean | Mandatory (for 3508) |
true | If you satisfy FTE Reduction Safe Harbor 2 (see PPP Schedule A Worksheet), set to true |
| forgive_schedule_a_line_11 | Number | Optional (for 3508) |
10.00 | Average FTE during the Borrower’s chosen reference period. If a safe harbor is met then skip this field |
| forgive_schedule_a_line_12 | Number | Optional (for 3508) |
10.00 | Total Average FTE. Value of this field should be equal to Average FTE Box 2 (forgive_schedule_a_line_2) + Average FTE Box 5 (forgive_schedule_a_line_5). If a safe harbor is met then skip this field |
| forgive_schedule_a_line_13 | Number | Mandatory (for 3508) |
1.00 | FTE Reduction Quotient (divide line 12 by line 11) or enter 1.0 if any of the above criteria are met. This field supports upto 9 decimals. |
| forgive_covered_period_from | String | Mandatory (for 3508, 3508EZ & (3508S - in prod 03/05) |
2020-07-06 | The covered period start date in YYYY-MM-DD |
| forgive_covered_period_to | String | Mandatory (for 3508, 3508EZ & (3508S - in prod 03/05) ) |
2020-09-06 | The covered period end date in YYYY-MM-DD. Please note - Requirement for Covered period for 2020 PPP loans to end on or before 12/31/2020 has been removed |
| forgive_alternate_covered_period_from | String | Optional | 2020-07-06 | The alternate covered period start date in YYYY-MM-DD. (Not-applicable in prod - 03/05) |
| forgive_alternate_covered_period_to | String | Optional | 2020-09-06 | The alternate covered period end date in YYYY-MM-DD. (Not-applicable in prod - 03/05) |
| forgive_payroll_schedule | String | Mandatory (for 3508, 3508EZ) |
Weekly | The payroll schedule. Possible Values: “Weekly”,”Biweekly”,”Twice Per Month”,”Monthly”,”Other”. (Other is free form to match 3508 options) (Not-applicable in prod - 03/05) |
| primary_email | String | Mandatory | user@example.com | The primary contact persons email |
| primary_name | String | Mandatory | Jason | The primary contact for the loan |
| ez_form | Boolean | Mandatory | true | Indicates whether the application submitted via EZ form |
| no_reduction_in_employees | Boolean | Mandatory (for 3508) |
true | No reduction in employees or average paid hours: If you have not reduced the number of employees or the average paid hours of your employees between January 1, 2020 and the end of the Covered Period, set to true |
| no_reduction_in_employees_and_ covid_impact |
Boolean | Mandatory (for 3508) |
true | FTE Reduction Safe Harbor 1: If you were unable to operate between February 15, 2020, and the end of the Covered Period at the same level of business activity as before February 15, 2020 due to compliance with requirements established or guidance issued between March 1, 2020 and December 31, 2020, by the Secretary of Health and Human Services, the Director of the Centers for Disease Control and Prevention, or the Occupational Safety and Health Administration related to the maintenance of standards for sanitation, social distancing, or any other worker or customer safety requirement related to COVID-19, set to true |
| forgive_lender_confirmation | Boolean | Mandatory | true | Confirmation from lender that they reviewed borrowers forgiveness application before submitting to SBA. Only ‘true’ value submits the request successfully |
| forgive_lender_decision | Number | Mandatory | 1 | Final lender decision regarding forgiveness of this PPP loan. Valid Values (API needs to pass integer value associated with the decision): APPROVED_IN_FULL = 0 APPROVED_IN_PART = 1 DENIED = 2 (If a “Denied” decision is issued to the SBA, Lender must populate API with zero values where appropriate.) |
| s_form | Boolean | Mandatory (for 3508S) |
false | Indicates whether the application submitted via 3508S form |
| naics_code | Number | Mandatory | 722513 | Borrower/Business - Valid 6 digit NAICS code (In prod - 03/05) |
| ppp_loan_draw | Number | Mandatory | 1 | Indicates whether it’s a first draw or second draw forgiveness , 1 for first draw & 2 for second draw (In prod - 03/05).Please note - For Second Draw PPP Loans in excess of $150,000, the borrower must submit its loan forgiveness application for the First Draw PPP Loan before or simultaneously with the loan forgiveness application for the Second Draw PPP Loan, even if the calculated amount of forgiveness on the First Draw PPP Loan is zero |
| forgive_covered_operations_expenditures | Number | Mandatory (for 3508, 3508EZ) |
1000.00 | Covered Operations expenditure (In prod - 03/05) |
| forgive_covered_property_damage_costs | Number | Mandatory (for 3508, 3508EZ) |
1000.00 | covered property damage cost (In prod - 03/05) |
| forgive_covered_supplier_costs | Number | Mandatory (for 3508, 3508EZ) |
1000.00 | covered supplier cost (In prod - 03/05) |
| forgive_covered_protection_expenditures | Number | Mandatory (for 3508, 3508EZ) |
1000.00 | covered worker protection expenditure (In prod - 03/05) |
| loan_increase | Number | Optional | 1000.00 | Any Loan increase which lender did on the Loan after initial Loan approval. This amount is already included in PPP Loan amount. If loan_increase is provided, loan_increase_date should also be provided and vice versa |
| loan_increase_date | String | Optional | 2020-12-29 | Date on which increased Loan was disbursed by Lender. Lender will be paid interest on Loan increased amount from this date |
Request Path Parameters
Not Applicable
Request Query Parameters
Not Applicable
Request Form Data Parameters
Not Applicable
Response (Sample)
{
"slug": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"etran_loan": {
"slug": "df481fbb-c41f-46f3-b96f-94374d747a8d",
"bank_notional_amount": 900000.00,
"sba_number": "9999114733",
"loan_number": "7777777",
"entity_name": "Abc Inc",
"ein": "997114733",
"funding_date": "2020-07-06",
"forgive_eidl_amount": 100.00,
"forgive_eidl_application_number": 123456789,
"forgive_payroll": 1000.00,
"forgive_rent": 1000.00,
"forgive_utilities": 1000.00,
"forgive_mortgage": 1000.00,
"address1": "5050 Ritter Road – Suite B",
"address2": "Mechanicsburg, PA",
"dba_name": "Abc Inc",
"phone_number": "6102342123",
"forgive_fte_at_loan_application": 10,
"demographics": [
{
"name": "Jason",
"position": "self-employed individual",
"veteran_status": "1",
"gender": "M",
"ethnicity": "H",
"races": [
{
"race": "1"
}
]
}
],
"status": "Pending Validation",
"forgive_line_6_3508_or_line_5_3508ez": 3999.00,
"forgive_modified_total": 1.00,
"forgive_payroll_cost_60_percent_requirement": 1666.66,
"forgive_amount": 1666.66,
"forgive_fte_at_forgiveness_application": 10,
"forgive_schedule_a_line_1": 1.00,
"forgive_schedule_a_line_2": 1.00,
"forgive_schedule_a_line_3_checkbox": true,
"forgive_schedule_a_line_3": 1.00,
"forgive_schedule_a_line_4": 1.00,
"forgive_schedule_a_line_5": 1.00,
"forgive_schedule_a_line_6": 1.00,
"forgive_schedule_a_line_7": 1.00,
"forgive_schedule_a_line_8": 1.00,
"forgive_schedule_a_line_9": 1.00,
"forgive_schedule_a_line_10": 6.00,
"forgive_schedule_a_line_10_checkbox": true,
"forgive_schedule_a_line_11": 10.00,
"forgive_schedule_a_line_12": 10.00,
"forgive_schedule_a_line_13": 1.00,
"forgive_covered_period_from": "2020-07-06",
"forgive_covered_period_to": "2020-09-06",
"forgive_alternate_covered_period_from": "2020-07-06",
"forgive_alternate_covered_period_to": "2020-09-06",
"forgive_payroll_schedule": "Weekly",
"primary_email": "user@example.com",
"primary_name": "Jason",
"ez_form": true,
"no_reduction_in_employees": true,
"no_reduction_in_employees_and_covid_impact": true,
"forgive_lender_confirmation": true,
"forgive_lender_decision": 1,
"sba_decision": "",
"approval_date": "2020-08-20",
"final_forgive_amount": 1000.00,
"calculated_interest": 10.00,
"final_forgive_payment": 910.00,
"final_forgive_payment_date": "2020-08-25",
"final_forgive_payment_batch": "PPY08091",
"final_forgive_amount_with_interest": 910.00,
"s_form": false
"naics_code": null,
"ppp_loan_draw": 1,
"forgive_covered_operations_expenditures": null,
"forgive_covered_property_damage_costs": null,
"forgive_covered_supplier_costs": null,
"forgive_covered_protection_expenditures": null,
"loan_increase": 1000.00,
"loan_increase_date": "2020-12-29"
}
}
Response Parameters
HTTP Response Code: 201
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| slug | UUID | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | The UUID of the Forgiveness request |
| etran_loan | JSON Object |
||
| slug | UUID | df481fbb-c41f-46f3-b96f-94374d747a8d | The UUID of the etran loan request |
| bank_notional_amount | Number | 900000.00 | The PPP loan amount |
| sba_number | String | 9999114733 | The SBA loan number |
| loan_number | String | 7777777 | The Lender’s loan number |
| entity_name | String | Abc Inc | The entity name of the borrower |
| ein | String | 997114733 | The SSN or Business TIN of the borrower |
| funding_date | String | 2020-07-06 | PPP loan Disbursement date in YYYY-MM-DD |
| forgive_eidl_amount | Number | 100.00 | The EIDL amount |
| forgive_eidl_application_number | Number | 123456789 | The Application number of the EIDL, decimals values are not allowed |
| forgive_payroll | Number | 1000.00 | Payroll Cost |
| forgive_rent | Number | 1000.00 | Business Rent or Lease Payments |
| forgive_utilities | Number | 1000.00 | Business Utility Payments |
| forgive_mortgage | Number | 1000.00 | Business Mortgage Interest Payments |
| address1 | String | 5050 Ritter Road – Suite B | Business Address Line 1 |
| address2 | String | Mechanicsburg, PA | Business Address Line 2 |
| dba_name | String | Abc Inc | The DBA Name or Trade Name of the borrower |
| phone_number | String | 6102342123 | The Business Phone Number of the borrower |
| forgive_fte_at_loan_application | Number | 10 | The full time employees at the time of loan application, decimal values are not allowed |
| demographics | JSON Array |
||
| name | String | Jason | The Principal name |
| position | String | self-employed individual | Identify the Principal’s position; for example, self-employed individual; independent contractor; sole proprietor; general partner; owner; officer; director; member; or key employee. |
| veteran_status | String | 1 | The veteran status of the borrower. Possible Values: [ 1, 2, 3, 4, X ] 1=Non-Veteran; 2=Veteran; 3=Service-Disabled Veteran; 4=Spouse of Veteran; X=Not Disclosed |
| gender | String | M | The gender of the borrower. Possible Values: [M, F, X ] M=Male; F=Female; X=Not Disclosed |
| ethnicity | String | H | The ethnicity of the borrower. Possible Values: [H, N, X ] H=Hispanic or Latino; N=Not Hispanic or Latino; X=Not Disclosed |
| races | JSON Array |
||
| race | String | 1 | The race of the borrower. Possible Values: [1, 2, 3, 4, 5, X ] 1=American Indian or Alaska Native; 2=Asian; 3=Black or African-American; 4=Native Hawaiian or Pacific Islander; 5=White; X=Not Disclosed |
| status | String | Pending Validation | 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) |
| forgive_line_6_3508_or_line_5_3508ez | Number | 3999.00 | Line 6 of 3508 or line 5 of 3508 EZ |
| forgive_modified_total | Number | 3999.00 | Forgiveness Amount calculation line 8 |
| forgive_payroll_cost_60_percent_requirement | Number | 1666.66 | Payroll cost 60% requirement |
| forgive_amount | Number | 1666.66 | Forgiveness Amount |
| forgive_fte_at_forgiveness_application | Number | 10 | Full time employees at the time of forgiveness application, decimal values are not allowed |
| forgive_schedule_a_line_1 | Number | 1.00 | Cash Compensation (Box 1) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_2 | Number | 1.00 | Average FTE (Box 2) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_3_checkbox | Boolean | true | Salary/Hourly Wage Reduction (Box 3) from PPP Schedule A Worksheet, Table 1: If the average annual salary or hourly wage for each employee listed on the PPP Schedule A Worksheet, Table 1 during the Covered Period or the Alternative Payroll Covered Period was at least 75% of such employee’s average annual salary or hourly wage between January 1, 2020 and March 31, 2020, then set to true and put the value as 0 for field forgive_schedule_a_line_3 |
| forgive_schedule_a_line_3 | Number | 1.00 | Salary/Hourly Wage Reduction (Box 3) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_4 | Number | 1.00 | Cash Compensation (Box 4) from PPP Schedule A Worksheet, Table 2 |
| forgive_schedule_a_line_5 | Number | 1.00 | Average FTE (Box 5) from PPP Schedule A Worksheet, Table 2 |
| forgive_schedule_a_line_6 | Number | 1.00 | Total amount paid or incurred by Borrower for employer contributions for employee health insurance |
| forgive_schedule_a_line_7 | Number | 1.00 | Total amount paid or incurred by Borrower for employer contributions to employee retirement plans |
| forgive_schedule_a_line_8 | Number | 1.00 | Total amount paid or incurred by Borrower for employer state and local taxes assessed on employee compensation |
| forgive_schedule_a_line_9 | Number | 1.00 | Total amount paid to owner-employees/self-employed individual/general partners |
| forgive_schedule_a_line_10 | Number | 6.00 | Total Payroll Costs (add lines 1, 4, 6, 7, 8, and 9) |
| forgive_schedule_a_line_10_checkbox | Boolean | true | If you satisfy FTE Reduction Safe Harbor 2 (see PPP Schedule A Worksheet), set to true |
| forgive_schedule_a_line_11 | Number | 10.00 | Average FTE during the Borrower’s chosen reference period |
| forgive_schedule_a_line_12 | Number | 10.00 | Total Average FTE |
| forgive_schedule_a_line_13 | Number | 1.00 | FTE Reduction Quotient (divide line 12 by line 11) or enter 1.0 if any of the above criteria are met. This field supports upto 9 decimals. |
| forgive_covered_period_from | String | 2020-07-06 | The covered period start date in YYYY-MM-DD |
| forgive_covered_period_to | String | 2020-09-06 | The covered period end date in YYYY-MM-DD |
| forgive_alternate_covered_period_from | String | 2020-07-06 | The alternate covered period start date in YYYY-MM-DD |
| forgive_alternate_covered_period_to | String | 2020-09-06 | The alternate covered period end date in YYYY-MM-DD |
| forgive_payroll_schedule | String | Weekly | The payroll schedule. Possible Values: “Weekly”,”Biweekly”,”Twice Per Month”,”Monthly”,”Other”. (Other is free form to match 3508 options) |
| primary_email | String | user@example.com | The primary contact persons email |
| primary_name | String | Jason | The primary contact for the loan |
| ez_form | Boolean | true | Indicates whether the application submitted via EZ form |
| no_reduction_in_employees | Boolean | true | No reduction in employees or average paid hours: If you have not reduced the number of employees or the average paid hours of your employees between January 1, 2020 and the end of the Covered Period, set to true |
| no_reduction_in_employees_and_ covid_impact |
Boolean | true | FTE Reduction Safe Harbor 1: If you were unable to operate between February 15, 2020, and the end of the Covered Period at the same level of business activity as before February 15, 2020 due to compliance with requirements established or guidance issued between March 1, 2020 and December 31, 2020, by the Secretary of Health and Human Services, the Director of the Centers for Disease Control and Prevention, or the Occupational Safety and Health Administration related to the maintenance of standards for sanitation, social distancing, or any other worker or customer safety requirement related to COVID-19, set to true |
| forgive_lender_confirmation | Boolean | true | Confirmation from lender that they reviewed borrowers forgiveness application before submitting to SBA. Only ‘true’ value submits the request successfully |
| forgive_lender_decision | Number | 1 | Final lender decision regarding forgiveness of this PPP loan. Valid Values (API needs to pass integer value associated with the decision): APPROVED_IN_FULL = 0 APPROVED_IN_PART = 1 DENIED = 2 |
| sba_decision | String | Fully Approved | 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. |
| approval_date | String | 2020-08-20 | The date on which Forgiveness application was decisioned by SBA |
| final_forgive_amount | Number | 1000.00 | The final Forgiveness amount approved SBA. You will only see this populate once we run the payment processing jobs. |
| calculated_interest | Number | 10.00 | The calculated interest on ther Forgiveness amount |
| final_forgive_payment | Number | 910.00 | This is the final Forgiveness payment (Principal - EIDL Advance) + Interest Due on Net Amount) |
| final_forgive_payment_date | String | 2020-08-25 | The date on which SBA initiates payment to lender (our process generally runs at 11:00am EST during Fed processing days |
| final_forgive_payment_batch | String | PPY08091 | Internal Payment Processing Batch. |
| final_forgive_amount_with_interest | Number | 910.00 | final_forgive_amount - EIDL Advances + Interest accrued over the period of the loan (Funding Date to Payment Date) |
| s_form | Boolean | false | Indicates whether the application submitted via 3508S form |
| naics_code | Number | 722513 | Borrower/Business - Valid 6 digit NAICS code (In prod - 03/05) |
| ppp_loan_draw | Number | 1 | Indicates whether it’s a first draw or second draw forgiveness , 1 for first draw & 2 for second draw (In prod - 03/05). Please note - For Second Draw PPP Loans in excess of $150,000, the borrower must submit its loan forgiveness application for the First Draw PPP Loan before or simultaneously with the loan forgiveness application for the Second Draw PPP Loan, even if the calculated amount of forgiveness on the First Draw PPP Loan is zero |
| forgive_covered_operations_expenditures | Number | null | Covered Operations expenditure (In prod - 03/05) |
| forgive_covered_property_damage_costs | Number | null | covered property damage cost (In prod - 03/05) |
| forgive_covered_supplier_costs | Number | 1000.00 | covered supplier cost (In prod - 03/05) |
| forgive_covered_protection_expenditures | Number | 1000.00 | covered worker protection expenditure (In prod - 03/05) |
| loan_increase | Number | 1000.00 | Any Loan increase which lender did on the Loan after initial Loan approval. This amount is already included in PPP Loan amount |
| loan_increase_date | String | 2020-12-29 | Date on which increased Loan was disbursed by Lender. Lender will be paid interest on Loan increased amount from this date |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 400
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
JSON |
{ “etran_loan”: { “forgive_mortgage”:[ “A valid number is required.” ], “sba_number”: [ “Etran Loan with this sba number already exists.”] } } |
The detail of the 400 error response for the field which failed validation. | |
JSON |
{ “non_field_errors”: [ “Loan is not valid for your institution” ], “status_code”: 400 } |
The detail of the 400 error response for non field related errors. | |
| detail | String | Significant error in calculation detected. | SBA Platform Calculated amount not matching API input values. |
| status | Number | 400 | The HTTP status code of the error. |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Considerations for Client Application
One API call per Forgiveness request. In the case where a client has large number of forgiveness requests, they may prefer to call this API using a batch process.
3. Upload Forgiveness documents
This API is used to provide supporting documents for a particular forgiveness decision.
** Important: This API requires the data and the document file attachment to be sent as form parameters. The Content-type must be multipart/form-data **
Request type: HTTPS
API Endpoint:
POST /api/ppp_loan_documents/
Content-type: multipart/form-data
Request (Sample)
/api/ppp_loan_documents/
Request Parameters
Not Applicable (No request body)
Request Path Parameters
Not Applicable
Request Query Parameters
Not Applicable
Request Form Data Parameters
| Form Data Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| name | String | Mandatory | Payroll.pdf | The name of the document |
| document_type | Number | Mandatory | 1 | The type of document uploaded. Possible Values can be found by calling the GET API: 1. Get Document Types |
| etran_loan | UUID | Mandatory | df481fbb-c41f-46f3-b96f-94374d747a8d | The UUID(Slug) of the etran loan which came as part of the forgiveness request creation. This ensures the document gets attached to the corresponding forgiveness request |
| document | File | Mandatory | Payroll.pdf | Actual file to be uploaded. The file that needs to be part of the multipart/form-data request. Allowed file types include .pdf,.xls,.xlsx,.csv,.doc,.docx,.jpg,.jpeg,.png |
Response (Sample)
{
"slug": "5ae02dd4-a7f7-4c40-90fc-20cba32e8de0",
"name": "Payroll.pdf",
"created_at": "2020-07-06T17:17:58.218Z",
"updated_at": "2020-07-06T17:17:58.218Z",
"document": "https://lenders-co-operative/../Payroll.pdf",
"document_type": 1,
"url": "https://lenders-co-operative/../Payroll.pdf",
"etran_loan": "df481fbb-c41f-46f3-b96f-94374d747a8d"
}
Response Parameters :
HTTP Response Code: 201
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| slug | UUID | 5ae02dd4-a7f7-4c40-90fc-20cba32e8de0 | The UUID of the document |
| name | String | Payroll.pdf | The name of the document |
| created_at | String | 2020-07-06T17:17:58.218Z | The created date time of the document in UTC |
| updated_at | String | 2020-07-06T17:17:58.218Z | The updated date time of the document in UTC |
| document | String | https://lenders-co-operative/../Payroll.pdf | The short lived URL of the document on the server |
| document_type | Number | 1 | The type of document uploaded. Possible Values can be found by calling the GET API: 1. Get Document Types |
| url | String | https://lenders-co-operative/../Payroll.pdf | The permalink URL of the document on the server |
| etran_loan | UUID | df481fbb-c41f-46f3-b96f-94374d747a8d | The UUID(Slug) of the etran loan which came as part of the forgiveness request creation. This ensures the document gets attached to the corresponding forgiveness request |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 404
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | JSON |
{“detail”:”[‘Additional documents not allowed at this time’]”, “status_code”:404 }. |
The detail of the 404 error response |
HTTP Response Code: 400
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
JSON |
{ “document_type”: [ “Incorrect type. Expected pk value, received str.” ],”status_code”: 400 } |
The request sent was not correct. |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
This API should be called immediately after the Forgiveness request API. This API also requires document type as input which the client can get from 1. Get Document Types One API call per document type per forgiveness request. If client is submitting multiple documents for a Forgiveness request, they would have to call this API multiple times. In the case where a Client has large number of forgiveness supporting documents, they may prefer to call this API using a batch process.
4. Get Details of ALL Forgiveness Requests
This API fetches the list of ALL forgiveness decisions for a lender
Request type: HTTPS
API Endpoint:
GET /api/ppp_loan_forgiveness_requests/
Request (Sample)
/api/ppp_loan_forgiveness_requests/
Request Parameters
Not Applicable (No request body)
Request Path Parameters
Not Applicable
Request Query Parameters
| Query Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| page | Number | Optional | 1 | The page number of the records to be fetched (for pagination) |
Request Form Data Parameters
Not Applicable
Response (Sample)
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"slug": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"borrower_name": "Jason",
"etran_loan": {
"slug": "df481fbb-c41f-46f3-b96f-94374d747a8d",
"bank_notional_amount": 900000.00,
"sba_number": "9999114733",
"loan_number": "7777777",
"entity_name": "Abc Inc",
"ein": "997114733",
"funding_date": "2020-07-06",
"forgive_eidl_amount": 100.00,
"forgive_eidl_application_number": 123456789,
"forgive_payroll": 1000.00,
"forgive_rent": 1000.00,
"forgive_utilities": 1000.00,
"forgive_mortgage": 1000.00,
"address1": "5050 Ritter Road – Suite B",
"address2": "Mechanicsburg, PA",
"dba_name": "Abc Inc",
"organization": {
"name": "Abc Bank",
"etran_location_id": "string",
"slug": "e2f282d3-33e4-408e-9f2d-07a837c894e5"
},
"phone_number": "6102342123",
"forgive_fte_at_loan_application": 10,
"documents": [
{
"slug": "5ae02dd4-a7f7-4c40-90fc-20cba32e8de0",
"name": "Payroll.pdf",
"created_at": "2020-07-06T17:50:43.369Z",
"updated_at": "2020-07-06T17:50:43.369Z",
"document": "https://lenders-co-operative/../Payroll.pdf",
"url": "https://lenders-co-operative/../Payroll.pdf",
"etran_loan": "df481fbb-c41f-46f3-b96f-94374d747a8d",
"document_type": {
"id": 1,
"name": "Loan Application Supporting Docs (Payroll)",
"description": "Loan Application Supporting Docs (Payroll)"
}
}
],
"status": "Pending Validation",
"demographics": [
{
"name": "Jason",
"position": "self-employed individual",
"veteran_status": "1",
"gender": "M",
"ethnicity": "H",
"races": [
{
"race": "1"
}
]
}
],
"forgive_line_6_3508_or_line_5_3508ez": 3999.00,
"forgive_modified_total": 3999.00,
"forgive_payroll_cost_60_percent_requirement": 1666.66,
"forgive_amount": 1666.66,
"forgive_fte_at_forgiveness_application": 10,
"forgive_schedule_a_line_1": 1.00,
"forgive_schedule_a_line_2": 1.00,
"forgive_schedule_a_line_3_checkbox": true,
"forgive_schedule_a_line_3": 1.00,
"forgive_schedule_a_line_4": 1.00,
"forgive_schedule_a_line_5": 1.00,
"forgive_schedule_a_line_6": 1.00,
"forgive_schedule_a_line_7": 1.00,
"forgive_schedule_a_line_8": 1.00,
"forgive_schedule_a_line_9": 1.00,
"forgive_schedule_a_line_10": 6.00,
"forgive_schedule_a_line_10_checkbox": true,
"forgive_schedule_a_line_11": 10.00,
"forgive_schedule_a_line_12": 10.00,
"forgive_schedule_a_line_13": 1.00,
"forgive_covered_period_from": "2020-07-06",
"forgive_covered_period_to": "2020-09-06",
"forgive_alternate_covered_period_from": "2020-07-06",
"forgive_alternate_covered_period_to": "2020-09-06",
"forgive_payroll_schedule": "Weekly",
"primary_email": "user@example.com",
"primary_name": "Jason",
"ez_form": true,
"no_reduction_in_employees": true,
"no_reduction_in_employees_and_covid_impact": true,
"forgive_lender_confirmation": true,
"forgive_lender_decision": 1,
"sba_decision": "Fully Approved",
"approval_date": "2020-08-20",
"final_forgive_amount": 1000.00,
"calculated_interest": 10.00,
"final_forgive_payment": 910.00,
"final_forgive_payment_date": "2020-08-25",
"final_forgive_payment_batch": "PPY08091",
"final_forgive_amount_with_interest": 910.00,
"payment_status": "Payment Sent",
"s_form": false,
"adjustments": [
{
"payment_amount": 50095.83,
"payment_date": "2020-11-21",
"status": "Payment Confirmed",
"payment_batch": "PF011224",
"payment_confirmed_at": "2020-11-22",
"document": "28328262-a0ea-4f85-81da-60a9191e714f",
"principal_amount": 50000.0,
"interest_amount": 95.83,
"disbursement_date": "2021-03-14",
"reason": "Lender Input Error",
"calculation_method": "Calculate interest from Disbursement Date to Original Payment Date"
"payment_type": "Under Payment"
},
{
"payment_amount": 100000.0,
"payment_date": "2021-09-19",
"status": "Eligible for payment",
"payment_batch": "PF011224",
"payment_confirmed_at": "2021-09-20",
"document": null,
"principal_amount": 100000.0,
"interest_amount": 0.0,
"disbursement_date": null,
"reason": "None",
"calculation_method": null,
"payment_type": "Over Payment"
},
],
"total_adjustments": 50095.83
"naics_code": null,
"ppp_loan_draw": 1,
"forgive_covered_operations_expenditures": null,
"forgive_covered_property_damage_costs": null,
"forgive_covered_supplier_costs": null,
"forgive_covered_protection_expenditures": null,
"source": 2,
"loan_increase": 1000.00,
"loan_increase_date": "2020-12-29"
},
"created": "07/02/2021"
}
]
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| count | Number | 1 | The total count of the forgiveness requests |
| next | String | null | The URI of the next set forgiveness requests to be fetched |
| previous | String | null | The URI of the previous set of forgiveness requests to be fetched |
| results | JSON Array |
||
| slug | UUID | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | The UUID of the Forgiveness request |
| borrower_name | String | Jason | The name of the borrower |
| etran_loan | JSON Object |
||
| slug | UUID | df481fbb-c41f-46f3-b96f-94374d747a8d | The UUID of the etran loan request |
| bank_notional_amount | Number | 900000.00 | The PPP loan amount |
| sba_number | String | 9999114733 | The SBA loan number |
| loan_number | String | 7777777 | The Lender’s loan number |
| entity_name | String | Abc Inc | The entity name of the borrower |
| ein | String | 997114733 | The SSN or Business TIN of the borrower |
| funding_date | String | 2020-07-06 | PPP loan Disbursement date in YYYY-MM-DD |
| forgive_eidl_amount | Number | 100.00 | The EIDL advance. This will be Lender provided till SBA payment batch runs. Once the SBA payment processing is done, this will be populated with SBA EIDL advance |
| forgive_eidl_application_number | Number | 123456789 | Lender provided EIDL application number |
| forgive_payroll | Number | 1000.00 | Payroll Cost |
| forgive_rent | Number | 1000.00 | Business Rent or Lease Payments |
| forgive_utilities | Number | 1000.00 | Business Utility Payments |
| forgive_mortgage | Number | 1000.00 | Business Mortgage Interest Payments |
| address1 | String | 5050 Ritter Road – Suite B | Business Address Line 1 |
| address2 | String | Mechanicsburg, PA | Business Address Line 2 |
| dba_name | String | Abc Inc | The DBA Name or Trade Name of the borrower |
| organization | JSON Object |
||
| name | String | Abc Bank | Name of the Lender |
| etran_location_id | String | Location ID | Location ID of Lender in SBA System |
| slug | UUID | e2f282d3-33e4-408e-9f2d-07a837c894e5 | The UUID of the Lender in the SBA System |
| phone_number | String | 6102342123 | The Business Phone Number of the borrower |
| forgive_fte_at_loan_application | Number | 10 | The full time employees at the time of loan application, decimal values are not allowed |
| documents | JSON Array |
||
| slug | UUID | 5ae02dd4-a7f7-4c40-90fc-20cba32e8de0 | The UUID of the document |
| name | String | Payroll.pdf | The name of the document |
| created_at | String | 2020-07-06T17:17:58.218Z | The created date time of the document in UTC |
| updated_at | String | 2020-07-06T17:17:58.218Z | The updated date time of the document in UTC |
| document | String | https://lenders-co-operative/../Payroll.pdf | The short lived URL of the document on the server |
| url | String | https://lenders-co-operative/../Payroll.pdf | Permalink for document on server |
| etran_loan | String | df481fbb-c41f-46f3-b96f-94374d747a8d | The UUID(Slug) of the etran loan which came as part of the forgiveness request creation. This ensures the document gets attached to the corresponding forgiveness request |
| document_type | JSON Object |
||
| id | Number | 1 | The id of the document type as defined in SBA System |
| name | String | Loan Application Supporting Docs (Payroll) | The name of the document type |
| description | String | Loan Application Supporting Docs (Payroll) | The description of the document type |
| status | String | Pending Validation | 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) |
| demographics | JSON Array |
||
| name | String | Jason | The Principal name |
| position | String | self-employed individual | Identify the Principal’s position; for example, self-employed individual; independent contractor; sole proprietor; general partner; owner; officer; director; member; or key employee. |
| veteran_status | String | 1 | The veteran status of the borrower. Possible Values: [ 1, 2, 3, 4, X ] 1=Non-Veteran; 2=Veteran; 3=Service-Disabled Veteran; 4=Spouse of Veteran; X=Not Disclosed |
| gender | String | M | The gender of the borrower. Possible Values: [M, F, X ] M=Male; F=Female; X=Not Disclosed |
| ethnicity | String | H | The ethnicity of the borrower. Possible Values: [H, N, X ] H=Hispanic or Latino; N=Not Hispanic or Latino; X=Not Disclosed |
| races | JSON Array |
||
| race | String | 1 | The race of the borrower. Possible Values: [1, 2, 3, 4, 5, X ] 1=American Indian or Alaska Native; 2=Asian; 3=Black or African-American; 4=Native Hawaiian or Pacific Islander; 5=White; X=Not Disclosed |
| forgive_line_6_3508_or_line_5_3508ez | Number | 3999.00 | Line 6 of 3508 or line 5 of 3508 EZ |
| forgive_modified_total | Number | 3999.00 | Forgiveness Amount calculation line 8 |
| forgive_payroll_cost_60_percent_requirement | Number | 1666.66 | Payroll cost 60% requirement |
| forgive_amount | Number | 1666.66 | Forgiveness Amount |
| forgive_fte_at_forgiveness_application | Number | 10 | Full time employees at the time of forgiveness application, decimal values are not allowed |
| forgive_schedule_a_line_1 | Number | 1.00 | Cash Compensation (Box 1) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_2 | Number | 1.00 | Average FTE (Box 2) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_3_checkbox | Boolean | true | Salary/Hourly Wage Reduction (Box 3) from PPP Schedule A Worksheet, Table 1: If the average annual salary or hourly wage for each employee listed on the PPP Schedule A Worksheet, Table 1 during the Covered Period or the Alternative Payroll Covered Period was at least 75% of such employee’s average annual salary or hourly wage between January 1, 2020 and March 31, 2020, then set to true and put the value as 0 for field forgive_schedule_a_line_3 |
| forgive_schedule_a_line_3 | Number | 1.00 | Salary/Hourly Wage Reduction (Box 3) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_4 | Number | 1.00 | Cash Compensation (Box 4) from PPP Schedule A Worksheet, Table 2 |
| forgive_schedule_a_line_5 | Number | 1.00 | Average FTE (Box 5) from PPP Schedule A Worksheet, Table 2 |
| forgive_schedule_a_line_6 | Number | 1.00 | Total amount paid or incurred by Borrower for employer contributions for employee health insurance |
| forgive_schedule_a_line_7 | Number | 1.00 | Total amount paid or incurred by Borrower for employer contributions to employee retirement plans |
| forgive_schedule_a_line_8 | Number | 1.00 | Total amount paid or incurred by Borrower for employer state and local taxes assessed on employee compensation |
| forgive_schedule_a_line_9 | Number | 1.00 | Total amount paid to owner-employees/self-employed individual/general partners |
| forgive_schedule_a_line_10 | Number | 6.00 | Total Payroll Costs (add lines 1, 4, 6, 7, 8, and 9) |
| forgive_schedule_a_line_10_checkbox | Boolean | true | If you satisfy FTE Reduction Safe Harbor 2 (see PPP Schedule A Worksheet), set to true |
| forgive_schedule_a_line_11 | Number | 10.00 | Average FTE during the Borrower’s chosen reference period |
| forgive_schedule_a_line_12 | Number | 10.00 | Total Average FTE |
| forgive_schedule_a_line_13 | Number | 1.00 | FTE Reduction Quotient (divide line 12 by line 11) or enter 1.0 if any of the above criteria are met. This field supports upto 9 decimals. |
| forgive_covered_period_from | String | 2020-07-06 | The covered period start date in YYYY-MM-DD |
| forgive_covered_period_to | String | 2020-09-06 | The covered period end date in YYYY-MM-DD |
| forgive_alternate_covered_period_from | String | 2020-07-06 | The alternate covered period start date in YYYY-MM-DD |
| forgive_alternate_covered_period_to | String | 2020-09-06 | The alternate covered period end date in YYYY-MM-DD |
| forgive_payroll_schedule | String | Weekly | The payroll schedule. Possible Values: “Weekly”,”Biweekly”,”Twice Per Month”,”Monthly”,”Other”. (Other is free form to match 3508 options) |
| primary_email | String | user@example.com | The primary contact persons email |
| primary_name | String | Jason | The primary contact for the loan |
| ez_form | Boolean | true | Indicates whether the application submitted via EZ form |
| no_reduction_in_employees | Boolean | true | No reduction in employees or average paid hours: If you have not reduced the number of employees or the average paid hours of your employees between January 1, 2020 and the end of the Covered Period, set to true |
| no_reduction_in_employees_and_ covid_impact |
Boolean | true | FTE Reduction Safe Harbor 1: If you were unable to operate between February 15, 2020, and the end of the Covered Period at the same level of business activity as before February 15, 2020 due to compliance with requirements established or guidance issued between March 1, 2020 and December 31, 2020, by the Secretary of Health and Human Services, the Director of the Centers for Disease Control and Prevention, or the Occupational Safety and Health Administration related to the maintenance of standards for sanitation, social distancing, or any other worker or customer safety requirement related to COVID-19, set to true |
| forgive_lender_confirmation | Boolean | true | Confirmation from lender that they reviewed borrowers forgiveness application before submitting to SBA. Only ‘true’ value submits the request successfully |
| forgive_lender_decision | Number | 1 | Final lender decision regarding forgiveness of this PPP loan. Valid Values (API needs to pass integer value associated with the decision): APPROVED_IN_FULL = 0 APPROVED_IN_PART = 1 DENIED = 2 |
| sba_decision | String | Fully Approved | 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. |
| approval_date | String | 2020-08-20 | The date on which Forgiveness application was decisioned by SBA |
| final_forgive_amount | Number | 1000.00 | The final Forgiveness amount approved SBA. You will only see this populate once we run the payment processing jobs. |
| calculated_interest | Number | 10.00 | The calculated interest on ther Forgiveness amount |
| final_forgive_payment | Number | 910.00 | This is the final Forgiveness payment (Principal - EIDL Advance) + Interest Due on Net Amount) |
| final_forgive_payment_date | String | 2020-08-25 | The date on which SBA initiates payment to lender (our process generally runs at 11:00am EST during Fed processing days |
| final_forgive_payment_batch | String | PPY08091 | Internal Payment Processing Batch |
| final_forgive_amount_with_interest | Number | 910.00 | final_forgive_amount - EIDL Advances + Interest accrued over the period of the loan (Funding Date to Payment Date) |
| s_form | Boolean | false | Indicates whether the application submitted via 3508S form |
| payment_status | String | Payment Sent | The payment status of forgiveness request. Possible Values: Payment Sent,Payment Confirmed,Payment Failed |
| adjustments | JSON Array |
Adjustment array | |
| payment_amount | Number | 100.00 | Total Adjustment amount |
| payment_date | String | 2020-11-21 | Date on which adjustment payment was initiated by Forgiveness platform |
| status | string | Payment Confirmed | Adjustment payment status, can have values of Payment Sent or Payment Confirmed for under payment request and Under Review or Eligible for payment for over payment request |
| payment_batch | string | PF011224 | Payment Batch in which adjustment payment was initiated, applicable for under payment only |
| payment_confirmed_at | string | 2020-11-22 | Date on which adjustment payment was confirmed by SBA. It gets populated with date when status is Payment Confirmed |
| document | string | 09deacc4-a0af-47ec-93fd-a30e9bc45701 | Slug id of the adjustment document, applicable for under payment requests only |
| principal_amount | Number | 50000.0 | Principal amount of adjustment |
| interest_amount | Number | 95.83 | Interest amount of adjustment |
| disbursement_date | String | 2021-03-14 | Disbursement date of adjusted payment, applicable for under payment only |
| reason | String | Lender Input Error | Reason of the payment adjustment, applicable for under payment only |
| calculation_method | String | Calculate interest from Disbursement Date to Original Payment Date | Calculation method used for payment adjustment, applicable for under payment only |
| payment_type | String | Over Payment | Reason for payment adjustment, valid values are Under Payment or Over Payment |
| total_adjustments | Number | 100.00 | Total adjustment amount, will be sum of the all under adjustments for SBA number |
| naics_code | Number | 722513 | Borrower/Business - Valid 6 digit NAICS code (In prod - 03/05) |
| ppp_loan_draw | Number | 1 | Indicates whether it’s a first draw or second draw forgiveness , 1 for first draw & 2 for second draw (In prod - 03/05) |
| forgive_covered_operations_expenditures | Number | null | Covered Operations expenditure (In prod - 03/05) |
| forgive_covered_property_damage_costs | Number | null | covered property damage cost (In prod - 03/05) |
| forgive_covered_supplier_costs | Number | 1000.00 | covered supplier cost (In prod - 03/05) |
| forgive_covered_protection_expenditures | Number | 1000.00 | covered worker protection expenditure (In prod - 03/05) |
| source | Number | 1 | If the Forgiveness was initiated by Lender, it’s value by 1 else if it was intiiated by borrower (direct forgiveness) its value will be 2 |
| loan_increase | Number | 1000.00 | Any Loan increase which lender did on the Loan after initial Loan approval. This amount is already included in PPP Loan amount |
| loan_increase_date | String | 2020-12-29 | Date on which increased Loan was disbursed by Lender. Lender will be paid interest on Loan increased amount from this date |
| created | String | 2021-01-12 | The created date of the Forgiveness request in YYYY-MM-DD |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
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
5. Get Forgiveness Request Details using Forgiveness request uuid
This API is used for getting details of existing forgiveness requests using unique slug id (Forgiveness request UUID)
Request type: HTTPS
API Endpoint:
GET /api/ppp_loan_forgiveness_requests/{slug}/
Request (Sample)
/api/ppp_loan_forgiveness_requests/3fa85f64-5717-4562-b3fc-2c963f66afa6/
Request Parameters
Not Applicable (No request body)
Request Path Parameters
| Path Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| slug | UUID | Mandatory | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | The UUID of the forgiveness request |
Request Query Parameters
Not Applicable
Request Form Data Parameters
Not Applicable
Response (Sample)
{
"slug": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"borrower_name": "Jason",
"etran_loan": {
"slug": "df481fbb-c41f-46f3-b96f-94374d747a8d",
"bank_notional_amount": 900000.00,
"sba_number": "9999114733",
"loan_number": "7777777",
"entity_name": "Abc Inc",
"ein": "997114733",
"funding_date": "2020-07-06",
"forgive_eidl_amount": 100.00,
"forgive_eidl_application_number": 123456789,
"forgive_payroll": 1000.00,
"forgive_rent": 1000.00,
"forgive_utilities": 1000.00,
"forgive_mortgage": 1000.00,
"address1": "5050 Ritter Road – Suite B",
"address2": "Mechanicsburg, PA",
"dba_name": "Abc Inc",
"organization": {
"name": "Abc bank",
"etran_location_id": "string",
"slug": "e2f282d3-33e4-408e-9f2d-07a837c894e5"
},
"phone_number": "6102342123",
"forgive_fte_at_loan_application": 10,
"documents": [
{
"slug": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "SBA 2408 Form",
"created_at": "2020-07-06T19:19:04.657Z",
"updated_at": "2020-07-06T19:19:04.657Z",
"document": "https://lenders-co-operative/../Payroll.pdf",
"url": "https://lenders-co-operative/../Payroll.pdf",
"etran_loan": "df481fbb-c41f-46f3-b96f-94374d747a8d",
"document_type": {
"id": 1,
"name": "Loan Application Supporting Docs (Payroll)",
"description": "Loan Application Supporting Docs (Payroll)"
}
}
],
"status": "Pending Validation",
"demographics": [
{
"name": "Jason",
"position": "self-employed individual",
"veteran_status": "1",
"gender": "M",
"ethnicity": "H",
"races": [
{
"race": "1"
}
]
}
],
"forgive_line_6_3508_or_line_5_3508ez": 3999.00,
"forgive_modified_total": 3999.00,
"forgive_payroll_cost_60_percent_requirement": 1666.66,
"forgive_amount": 1666.66,
"forgive_fte_at_forgiveness_application": 10,
"forgive_schedule_a_line_1": 1.00,
"forgive_schedule_a_line_2": 1.00,
"forgive_schedule_a_line_3_checkbox": true,
"forgive_schedule_a_line_3": 1.00,
"forgive_schedule_a_line_4": 1.00,
"forgive_schedule_a_line_5": 1.00,
"forgive_schedule_a_line_6": 1.00,
"forgive_schedule_a_line_7": 1.00,
"forgive_schedule_a_line_8": 1.00,
"forgive_schedule_a_line_9": 1.00,
"forgive_schedule_a_line_10": 6.00,
"forgive_schedule_a_line_10_checkbox": true,
"forgive_schedule_a_line_11": 10.00,
"forgive_schedule_a_line_12": 10.00,
"forgive_schedule_a_line_13": 1.00,
"forgive_covered_period_from": "2020-07-06",
"forgive_covered_period_to": "2020-09-06",
"forgive_alternate_covered_period_from": "2020-07-06",
"forgive_alternate_covered_period_to": "2020-09-06",
"forgive_payroll_schedule": "Weekly",
"primary_email": "user@example.com",
"primary_name": "Jason",
"ez_form": true,
"no_reduction_in_employees": true,
"no_reduction_in_employees_and_covid_impact": true,
"forgive_lender_confirmation": true,
"forgive_lender_decision": 1,
"sba_decision": "Fully Approved",
"approval_date": "2020-08-20",
"final_forgive_amount": 1000.00,
"calculated_interest": 10.00,
"final_forgive_payment": 910.00,
"final_forgive_payment_date": "2020-08-25",
"final_forgive_payment_batch": PPY08091,
"final_forgive_amount_with_interest": 910.00,
"payment_status": "Payment Sent",
"s_form": false,
"adjustments": [
{
"payment_amount": 50095.83,
"payment_date": "2020-11-21",
"status": "Payment Confirmed",
"payment_batch": "PF011224",
"payment_confirmed_at": "2020-11-22",
"document": "28328262-a0ea-4f85-81da-60a9191e714f",
"principal_amount": 50000.0,
"interest_amount": 95.83,
"disbursement_date": "2021-03-14",
"reason": "Lender Input Error",
"calculation_method": "Calculate interest from Disbursement Date to Original Payment Date"
"payment_type": "Under Payment"
},
{
"payment_amount": 100000.0,
"payment_date": "2021-09-19",
"status": "Eligible for payment",
"payment_batch": "PF011224",
"payment_confirmed_at": "2021-09-20",
"document": null,
"principal_amount": 100000.0,
"interest_amount": 0.0,
"disbursement_date": null,
"reason": "None",
"calculation_method": null,
"payment_type": "Over Payment"
},
"total_adjustments": 100.00
"naics_code": null,
"ppp_loan_draw": 1,
"forgive_covered_operations_expenditures": null,
"forgive_covered_property_damage_costs": null,
"forgive_covered_supplier_costs": null,
"forgive_covered_protection_expenditures": null,
"source": 2,
"loan_increase": 1000.00,
"loan_increase_date": "2021-01-01"
},
"created": "01/02/2021"
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| slug | UUID | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | The UUID of the Forgiveness request |
| borrower_name | String | Jason | The name of the borrower |
| etran_loan | JSON Object |
||
| slug | UUID | df481fbb-c41f-46f3-b96f-94374d747a8d | The UUID of the etran loan request |
| bank_notional_amount | Number | 900000.00 | The PPP loan amount |
| sba_number | String | 9999114733 | The SBA loan number |
| loan_number | String | 7777777 | The Lender’s loan number |
| entity_name | String | Abc Inc | The entity name of the borrower |
| ein | String | 997114733 | The SSN or Business TIN of the borrower |
| funding_date | String | 2020-07-06 | PPP loan Disbursement date in YYYY-MM-DD |
| forgive_eidl_amount | Number | 100.00 | The EIDL advance. This will be Lender provided till SBA payment batch runs. Once the SBA payment processing is done, this will be populated with SBA EIDL advance |
| forgive_eidl_application_number | Number | 123456789 | Lender provided EIDL application number |
| forgive_payroll | Number | 1000.00 | Payroll Cost |
| forgive_rent | Number | 1000.00 | Business Rent or Lease Payments |
| forgive_utilities | Number | 1000.00 | Business Utility Payments |
| forgive_mortgage | Number | 1000.00 | Business Mortgage Interest Payments |
| address1 | String | 5050 Ritter Road – Suite B | Business Address Line 1 |
| address2 | String | Mechanicsburg, PA | Business Address Line 2 |
| dba_name | String | Abc Inc | The DBA Name or Trade Name of the borrower |
| organization | JSON Object |
||
| name | String | Abc Bank | Name of the Lender |
| etran_location_id | String | Location ID | Location ID of Lender in SBA System |
| slug | UUID | e2f282d3-33e4-408e-9f2d-07a837c894e5 | The UUID of the Lender in the SBA System |
| phone_number | String | 6102342123 | The Business Phone Number of the borrower |
| forgive_fte_at_loan_application | Number | 10 | The full time employees at the time of loan application, decimal values are not allowed |
| documents | JSON Array |
||
| slug | UUID | 5ae02dd4-a7f7-4c40-90fc-20cba32e8de0 | The UUID of the document |
| name | String | Payroll.pdf | The name of the document |
| created_at | String | 2020-07-06T17:17:58.218Z | The created date time of the document in UTC |
| updated_at | String | 2020-07-06T17:17:58.218Z | The updated date time of the document in UTC |
| document | String | https://lenders-co-operative/../Payroll.pdf | Short lived direct access to download document |
| url | String | https://lenders-co-operative/../Payroll.pdf | Permalink for document on server |
| etran_loan | String | df481fbb-c41f-46f3-b96f-94374d747a8d | The UUID(Slug) of the etran loan which came as part of the forgiveness request creation. This ensures the document gets attached to the corresponding forgiveness request |
| document_type | JSON Object |
||
| id | Number | 1 | The id of the document type as defined in SBA System |
| name | String | Loan Application Supporting Docs (Payroll) | The name of the documenttype |
| description | String | Loan Application Supporting Docs (Payroll) | The description of the document type |
| status | String | Pending Validation | 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) |
| demographics | JSON Array |
||
| name | String | Jason | The Principal name |
| position | String | self-employed individual | Identify the Principal’s position; for example, self-employed individual; independent contractor; sole proprietor; general partner; owner; officer; director; member; or key employee. |
| veteran_status | String | 1 | The veteran status of the borrower. Possible Values: [ 1, 2, 3, 4, X ] 1=Non-Veteran; 2=Veteran; 3=Service-Disabled Veteran; 4=Spouse of Veteran; X=Not Disclosed |
| gender | String | M | The gender of the borrower. Possible Values: [M, F, X ] M=Male; F=Female; X=Not Disclosed |
| ethnicity | String | H | The ethnicity of the borrower. Possible Values: [H, N, X ] H=Hispanic or Latino; N=Not Hispanic or Latino; X=Not Disclosed |
| races | JSON Array |
||
| race | String | 1 | The race of the borrower. Possible Values: [1, 2, 3, 4, 5, X ] 1=American Indian or Alaska Native; 2=Asian; 3=Black or African-American; 4=Native Hawaiian or Pacific Islander; 5=White; X=Not Disclosed |
| forgive_line_6_3508_or_line_5_3508ez | Number | 3999.00 | Line 6 of 3508 or line 5 of 3508 EZ |
| forgive_modified_total | Number | 3999.00 | Forgiveness Amount calculation line 8 |
| forgive_payroll_cost_60_percent_requirement | Number | 1666.66 | Payroll cost 60% requirement |
| forgive_amount | Number | 1666.66 | Forgiveness Amount |
| forgive_fte_at_forgiveness_application | Number | 10 | Full time employees at the time of forgiveness application, decimal values are not allowed |
| forgive_schedule_a_line_1 | Number | 1.00 | Cash Compensation (Box 1) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_2 | Number | 1.00 | Average FTE (Box 2) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_3_checkbox | Boolean | true | Salary/Hourly Wage Reduction (Box 3) from PPP Schedule A Worksheet, Table 1: If the average annual salary or hourly wage for each employee listed on the PPP Schedule A Worksheet, Table 1 during the Covered Period or the Alternative Payroll Covered Period was at least 75% of such employee’s average annual salary or hourly wage between January 1, 2020 and March 31, 2020, then set to true and put the value as 0 for field forgive_schedule_a_line_3 |
| forgive_schedule_a_line_3 | Number | 1.00 | Salary/Hourly Wage Reduction (Box 3) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_4 | Number | 1.00 | Cash Compensation (Box 4) from PPP Schedule A Worksheet, Table 2 |
| forgive_schedule_a_line_5 | Number | 1.00 | Average FTE (Box 5) from PPP Schedule A Worksheet, Table 2 |
| forgive_schedule_a_line_6 | Number | 1.00 | Total amount paid or incurred by Borrower for employer contributions for employee health insurance |
| forgive_schedule_a_line_7 | Number | 1.00 | Total amount paid or incurred by Borrower for employer contributions to employee retirement plans |
| forgive_schedule_a_line_8 | Number | 1.00 | Total amount paid or incurred by Borrower for employer state and local taxes assessed on employee compensation |
| forgive_schedule_a_line_9 | Number | 1.00 | Total amount paid to owner-employees/self-employed individual/general partners |
| forgive_schedule_a_line_10 | Number | 6.00 | Total Payroll Costs (add lines 1, 4, 6, 7, 8, and 9) |
| forgive_schedule_a_line_10_checkbox | Boolean | true | If you satisfy FTE Reduction Safe Harbor 2 (see PPP Schedule A Worksheet), set to true |
| forgive_schedule_a_line_11 | Number | 10.00 | Average FTE during the Borrower’s chosen reference period |
| forgive_schedule_a_line_12 | Number | 10.00 | Total Average FTE |
| forgive_schedule_a_line_13 | Number | 1.00 | FTE Reduction Quotient (divide line 12 by line 11) or enter 1.0 if any of the above criteria are met. This field supports upto 9 decimals. |
| forgive_covered_period_from | String | 2020-07-06 | The covered period start date in YYYY-MM-DD |
| forgive_covered_period_to | String | 2020-07-06 | The covered period end date in YYYY-MM-DD |
| forgive_alternate_covered_period_from | String | 2020-07-06 | The alternate covered period start date in YYYY-MM-DD |
| forgive_alternate_covered_period_to | String | 2020-07-06 | The alternate covered period end date in YYYY-MM-DD |
| forgive_payroll_schedule | String | Weekly | The payroll schedule. Possible Values: “Weekly”,”Biweekly”,”Twice Per Month”,”Monthly”,”Other”. (Other is free form to match 3508 options) |
| primary_email | String | user@example.com | The primary contact persons email |
| primary_name | String | Some Name | The primary contact for the loan |
| ez_form | Boolean | true | Indicates whether the application submitted via EZ form |
| no_reduction_in_employees | Boolean | true | No reduction in employees or average paid hours: If you have not reduced the number of employees or the average paid hours of your employees between January 1, 2020 and the end of the Covered Period, set to true |
| no_reduction_in_employees_and_ covid_impact |
Boolean | true | FTE Reduction Safe Harbor 1: If you were unable to operate between February 15, 2020, and the end of the Covered Period at the same level of business activity as before February 15, 2020 due to compliance with requirements established or guidance issued between March 1, 2020 and December 31, 2020, by the Secretary of Health and Human Services, the Director of the Centers for Disease Control and Prevention, or the Occupational Safety and Health Administration related to the maintenance of standards for sanitation, social distancing, or any other worker or customer safety requirement related to COVID-19, set to true |
| forgive_lender_confirmation | Boolean | true | Confirmation from lender that they reviewed borrowers forgiveness application before submitting to SBA. Only ‘true’ value submits the request successfully |
| forgive_lender_decision | Number | 1 | Final lender decision regarding forgiveness of this PPP loan. Valid Values (API needs to pass integer value associated with the decision): APPROVED_IN_FULL = 0 APPROVED_IN_PART = 1 DENIED = 2 |
| sba_decision | String | Fully Approved | 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. |
| approval_date | String | 2020-08-20 | The date on which Forgiveness application was approved by SBA |
| approval_date | String | 2020-08-20 | The date on which Forgiveness application was decisioned by SBA |
| calculated_interest | Number | 10.00 | The calculated interest on ther Forgiveness amount |
| final_forgive_payment | Number | 910.00 | This is the final Forgiveness payment (Principal - EIDL Advance) + Interest Due on Net Amount) |
| final_forgive_payment_date | String | 2020-08-25 | The date on which SBA initiates payment to lender (our process generally runs at 11:00am EST during Fed processing days |
| final_forgive_payment_batch | String | PPY08091 | Internal Payment Processing Batch |
| final_forgive_amount_with_interest | Number | 910.00 | final_forgive_amount - EIDL Advances + Interest accrued over the period of the loan (Funding Date to Payment Date) |
| payment_status | String | Payment Sent | The payment status of forgiveness request. Possible Values: Payment Sent,Payment Confirmed,Payment Failed |
| s_form | Boolean | true | Indicates whether the application submitted via 3508S form |
| adjustments | JSON Array |
Adjustment array | |
| payment_amount | Number | 100.00 | Total Adjustment amount |
| payment_date | String | 2020-11-21 | Date on which adjustment payment was initiated by Forgiveness platform |
| status | string | Payment Confirmed | Adjustment payment status, can have values of Payment Sent or Payment Confirmed for under payment request and Under Review or Eligible for payment for over payment request |
| payment_batch | string | PF011224 | Payment Batch in which adjustment payment was initiated, applicable for under payment only |
| payment_confirmed_at | string | 2020-11-22 | Date on which adjustment payment was confirmed by SBA. It gets populated with date when status is Payment Confirmed |
| document | string | 09deacc4-a0af-47ec-93fd-a30e9bc45701 | Slug id of the adjustment document, applicable for under payment requests only |
| principal_amount | Number | 50000.0 | Principal amount of adjustment |
| interest_amount | Number | 95.83 | Interest amount of adjustment |
| disbursement_date | String | 2021-03-14 | Disbursement date of adjusted payment, applicable for under payment only |
| reason | String | Lender Input Error | Reason of the payment adjustment, applicable for under payment only |
| calculation_method | String | Calculate interest from Disbursement Date to Original Payment Date | Calculation method used for payment adjustment, applicable for under payment only |
| payment_type | String | Over Payment | Reason for payment adjustment, valid values are Under Payment or Over Payment |
| total_adjustments | Number | 100.00 | Total adjustment amount, will be sum of the all under adjustments for SBA number |
| naics_code | Number | 722513 | Borrower/Business - Valid 6 digit NAICS code (In prod - 03/05) |
| ppp_loan_draw | Number | 1 | Indicates whether it’s a first draw or second draw forgiveness , 1 for first draw & 2 for second draw (In prod - 03/05) |
| forgive_covered_operations_expenditures | Number | null | Covered Operations expenditure (In prod - 03/05) |
| forgive_covered_property_damage_costs | Number | null | covered property damage cost (In prod - 03/05) |
| forgive_covered_supplier_costs | Number | 1000.00 | covered supplier cost (In prod - 03/05) |
| forgive_covered_protection_expenditures | Number | 1000.00 | covered worker protection expenditure (In prod - 03/05) |
| source | Number | 1 | If the Forgiveness was initiated by Lender, it’s value by 1 else if it was intiiated by borrower (direct forgiveness) its value will be 2 |
| loan_increase | Number | 1000.00 | Any Loan increase which lender did on the Loan after initial Loan approval. This amount is already included in PPP Loan amount |
| loan_increase_date | String | 2021-01-09 | Date on which increased Loan was disbursed by Lender. Lender will be paid interest on Loan increased amount from this date |
| created | String | 2020-07-12 | The created date of the Forgiveness request in YYYY-MM-DD |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 404
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | JSON |
{ “detail”: “Not found.”, “status_code”: 404 } |
If the forgiveness request is not found |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
This API provides Status/Details of a specific submitted forgiveness request. Client may choose to use this API in case they would like to get the latest details of a particular forgiveness request.
6. Get Forgiveness Request Details using SBA Number
This API is used for getting details of existing forgiveness request using an SBA Number
Request type: HTTPS
API Endpoint:
GET /api/ppp_loan_forgiveness_requests/?sba_number={sba_number}
Request (Sample)
/api/ppp_loan_forgiveness_requests/?sba_number=9999114733
Request Parameters
Not Applicable (No request body)
Request Path Parameters
Not Applicable
Request Query Parameters
| Query Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| sba_number | String | Mandatory | 9999114733 | The SBA Number for the etran loan |
Request Form Data Parameters
Not Applicable
Response (Sample)
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"slug": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"etran_loan": {
"slug": "df481fbb-c41f-46f3-b96f-94374d747a8d",
"bank_notional_amount": 900000.00,
"sba_number": "9999114733",
"loan_number": "7777777",
"entity_name": "Abc Inc",
"ein": "997114733",
"funding_date": "2020-07-06",
"forgive_eidl_amount": 100.00,
"forgive_eidl_application_number": 123456789,
"forgive_payroll": 1000.00,
"forgive_rent": 1000.00,
"forgive_utilities": 1000.00,
"forgive_mortgage": 1000.00,
"address1": "5050 Ritter Road – Suite B",
"address2": "Mechanicsburg, PA",
"dba_name": "Abc Inc",
"organization": {
"name": "Abc Bank",
"etran_location_id": "string",
"slug": "e2f282d3-33e4-408e-9f2d-07a837c894e5"
},
"phone_number": "6102342123",
"forgive_fte_at_loan_application": 10,
"documents": [
{
"slug": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Payroll.pdf",
"created_at": "2020-07-06T19:19:04.657Z",
"updated_at": "2020-07-06T19:19:04.657Z",
"document": "https://lenders-co-operative/../Payroll.pdf",
"url": "https://lenders-co-operative/../Payroll.pdf",
"etran_loan": "1234567",
"document_type": {
"id": 1,
"name": "Loan Application Supporting Docs (Payroll)",
"description": "Loan Application Supporting Docs (Payroll)"
}
}
],
"status": "Pending Validation",
"demographics": [
{
"name": "Jason",
"position": "self-employed individual",
"veteran_status": "1",
"gender": "M",
"ethnicity": "H",
"races": [
{
"race": "1"
}
]
}
],
"forgive_line_6_3508_or_line_5_3508ez": 3999.00,
"forgive_modified_total": 3999.00,
"forgive_payroll_cost_60_percent_requirement": 1666.66,
"forgive_amount": 1666.66,
"forgive_fte_at_forgiveness_application": 10,
"forgive_schedule_a_line_1": 1.00,
"forgive_schedule_a_line_2": 1.00,
"forgive_schedule_a_line_3_checkbox": true,
"forgive_schedule_a_line_3": 1.00,
"forgive_schedule_a_line_4": 1.00,
"forgive_schedule_a_line_5": 1.00,
"forgive_schedule_a_line_6": 1.00,
"forgive_schedule_a_line_7": 1.00,
"forgive_schedule_a_line_8": 1.00,
"forgive_schedule_a_line_9": 1.00,
"forgive_schedule_a_line_10": 6.00,
"forgive_schedule_a_line_10_checkbox": true,
"forgive_schedule_a_line_11": 10.00,
"forgive_schedule_a_line_12": 10.00,
"forgive_schedule_a_line_13": 1.00,
"forgive_covered_period_from": "2020-07-06",
"forgive_covered_period_to": "2020-09-06",
"forgive_alternate_covered_period_from": "2020-07-06",
"forgive_alternate_covered_period_to": "2020-09-06",
"forgive_payroll_schedule": "Weekly",
"primary_email": "user@example.com",
"primary_name": "Jason",
"ez_form": true,
"no_reduction_in_employees": true,
"no_reduction_in_employees_and_covid_impact": true,
"forgive_lender_confirmation": true,
"forgive_lender_decision": 1,
"sba_decision": "Fully Approved",
"approval_date": "2020-08-20",
"final_forgive_amount": 1000.00,
"calculated_interest": 10.00,
"final_forgive_payment": 910.00,
"final_forgive_payment_date": "2020-08-25",
"final_forgive_payment_batch": PPY08091,
"final_forgive_amount_with_interest": 910.00,
"payment_status": "Payment Sent",
"s_form": false,
"adjustments": [
{
"payment_amount": 50095.83,
"payment_date": "2020-11-21",
"status": "Payment Confirmed",
"payment_batch": "PF011224",
"payment_confirmed_at": "2020-11-22",
"document": "28328262-a0ea-4f85-81da-60a9191e714f",
"principal_amount": 50000.0,
"interest_amount": 95.83,
"disbursement_date": "2021-03-14",
"reason": "Lender Input Error",
"calculation_method": "Calculate interest from Disbursement Date to Original Payment Date"
"payment_type": "Under Payment"
},
{
"payment_amount": 100000.0,
"payment_date": "2021-09-19",
"status": "Eligible for payment",
"payment_batch": "PF011224",
"payment_confirmed_at": "2021-09-20",
"document": null,
"principal_amount": 100000.0,
"interest_amount": 0.0,
"disbursement_date": null,
"reason": "None",
"calculation_method": null,
"payment_type": "Over Payment"
},
],
"total_adjustments": 100.00,
"naics_code": null,
"ppp_loan_draw": 1,
"forgive_covered_operations_expenditures": null,
"forgive_covered_property_damage_costs": null,
"forgive_covered_supplier_costs": null,
"forgive_covered_protection_expenditures": null,
"source": 2,
"loan_increase": 1000.00,
"loan_increase_date": "2020-07-09"
},
"created": "07/02/2020"
}
]
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| count | Number | 1 | The count of the records returned in response |
| next | String | null | The URI of the next set of forgiveness requests to be fetched |
| previous | String | null | The URI of the previous set of forgiveness requests to be fetched |
| results | JSON Array |
||
| slug | UUID | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | The UUID of the Forgiveness request |
| borrower_name | String | Jason | The name of the borrower |
| etran_loan | JSON Object |
||
| slug | UUID | df481fbb-c41f-46f3-b96f-94374d747a8d | The UUID of the etran loan request |
| bank_notional_amount | Number | 900000.00 | The PPP loan amount |
| sba_number | String | 9999114733 | The SBA loan number |
| loan_number | String | 7777777 | The Lender’s loan number |
| entity_name | String | Abc Inc | The entity name of the borrower |
| ein | String | 997114733 | The SSN or Business TIN of the borrower |
| funding_date | String | 2020-07-06 | PPP loan Disbursement date in YYYY-MM-DD |
| forgive_eidl_amount | Number | 100.00 | The EIDL advance. This will be Lender provided till SBA payment batch runs. Once the SBA payment processing is done, this will be populated with SBA EIDL advance |
| forgive_eidl_application_number | Number | 123456789 | Lender provided EIDL application number |
| forgive_payroll | Number | 1000.00 | Payroll Cost |
| forgive_rent | Number | 1000.00 | Business Rent or Lease Payments |
| forgive_utilities | Number | 1000.00 | Business Utility Payments |
| forgive_mortgage | Number | 1000.00 | Business Mortgage Interest Payments |
| address1 | String | 5050 Ritter Road – Suite B | Business Address Line 1 |
| address2 | String | Mechanicsburg, PA | Business Address Line 2 |
| dba_name | String | Abc Inc | The DBA Name or Trade Name of the borrower |
| organization | JSON Object |
||
| name | String | Abc Bank | Name of the Lender |
| etran_location_id | String | Location ID | Location ID of Lender in SBA System |
| slug | UUID | e2f282d3-33e4-408e-9f2d-07a837c894e5 | The UUID of the Lender in the SBA System |
| phone_number | String | 6102342123 | The Business Phone Number of the borrower |
| forgive_fte_at_loan_application | Number | 10 | The full time employees at the time of loan application, decimal values are not allowed |
| documents | JSON Array |
||
| slug | UUID | 5ae02dd4-a7f7-4c40-90fc-20cba32e8de0 | The UUID of the document |
| name | String | Payroll.pdf | The name of the document |
| created_at | String | 2020-07-06T17:17:58.218Z | The created date time of the document in UTC |
| updated_at | String | 2020-07-06T17:17:58.218Z | The updated date time of the document in UTC |
| document | String | https://lenders-co-operative/../Payroll.pdf | Short lived direct access to download document |
| url | String | https://lenders-co-operative/../Payroll.pdf | Permalink for document on server |
| etran_loan | String | 1234567 | The UUID(Slug) of the etran loan which came as part of the forgiveness request creation. This ensures the document gets attached to the corresponding forgiveness request |
| document_type | JSON Object |
||
| id | Number | 1 | The id of the document type as defined in SBA System |
| name | String | Loan Application Supporting Docs (Payroll) | The name of the document type |
| description | String | Loan Application Supporting Docs (Payroll) | The description of the document type |
| status | String | Pending Validation | 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) |
| demographics | JSON Array |
||
| name | String | Jason | The Principal name |
| position | String | self-employed individual | Identify the Principal’s position; for example, self-employed individual; independent contractor; sole proprietor; general partner; owner; officer; director; member; or key employee. |
| veteran_status | String | 1 | The veteran status of the borrower. Possible Values: [ 1, 2, 3, 4, X ] 1=Non-Veteran; 2=Veteran; 3=Service-Disabled Veteran; 4=Spouse of Veteran; X=Not Disclosed |
| gender | String | M | The gender of the borrower. Possible Values: [M, F, X ] M=Male; F=Female; X=Not Disclosed |
| ethnicity | String | H | The ethnicity of the borrower. Possible Values: [H, N, X ] H=Hispanic or Latino; N=Not Hispanic or Latino; X=Not Disclosed |
| races | JSON Array |
||
| race | String | 1 | The race of the borrower. Possible Values: [1, 2, 3, 4, 5, X ] 1=American Indian or Alaska Native; 2=Asian; 3=Black or African-American; 4=Native Hawaiian or Pacific Islander; 5=White; X=Not Disclosed |
| forgive_line_6_3508_or_line_5_3508ez | Number | 3999.00 | Line 6 of 3508 or line 5 of 3508 EZ |
| forgive_modified_total | Number | 3999.00 | Forgiveness Amount calculation line 8 |
| forgive_payroll_cost_60_percent_requirement | Number | 1666.66 | Payroll cost 60% requirement |
| forgive_amount | Number | 1666.66 | Forgiveness Amount |
| forgive_fte_at_forgiveness_application | Number | 10 | Full time employees at the time of forgiveness application, decimal values are not allowed |
| forgive_schedule_a_line_1 | Number | 1.00 | Cash Compensation (Box 1) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_2 | Number | 1.00 | Average FTE (Box 2) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_3_checkbox | Boolean | true | Salary/Hourly Wage Reduction (Box 3) from PPP Schedule A Worksheet, Table 1: If the average annual salary or hourly wage for each employee listed on the PPP Schedule A Worksheet, Table 1 during the Covered Period or the Alternative Payroll Covered Period was at least 75% of such employee’s average annual salary or hourly wage between January 1, 2020 and March 31, 2020, then set to true and put the value as 0 for field forgive_schedule_a_line_3 |
| forgive_schedule_a_line_3 | Number | 1.00 | Salary/Hourly Wage Reduction (Box 3) from PPP Schedule A Worksheet, Table 1 |
| forgive_schedule_a_line_4 | Number | 1.00 | Cash Compensation (Box 4) from PPP Schedule A Worksheet, Table 2 |
| forgive_schedule_a_line_5 | Number | 1.00 | Average FTE (Box 5) from PPP Schedule A Worksheet, Table 2 |
| forgive_schedule_a_line_6 | Number | 1.00 | Total amount paid or incurred by Borrower for employer contributions for employee health insurance |
| forgive_schedule_a_line_7 | Number | 1.00 | Total amount paid or incurred by Borrower for employer contributions to employee retirement plans |
| forgive_schedule_a_line_8 | Number | 1.00 | Total amount paid or incurred by Borrower for employer state and local taxes assessed on employee compensation |
| forgive_schedule_a_line_9 | Number | 1.00 | Total amount paid to owner-employees/self-employed individual/general partners |
| forgive_schedule_a_line_10 | Number | 6.00 | Total Payroll Costs (add lines 1, 4, 6, 7, 8, and 9) |
| forgive_schedule_a_line_10_checkbox | Boolean | true | If you satisfy FTE Reduction Safe Harbor 2 (see PPP Schedule A Worksheet), set to true |
| forgive_schedule_a_line_11 | Number | 10.00 | Average FTE during the Borrower’s chosen reference period |
| forgive_schedule_a_line_12 | Number | 10.00 | Total Average FTE |
| forgive_schedule_a_line_13 | Number | 1.00 | FTE Reduction Quotient (divide line 12 by line 11) or enter 1.0 if any of the above criteria are met. This field supports upto 9 decimals. |
| forgive_covered_period_from | String | 2020-07-06 | The covered period start date in YYYY-MM-DD |
| forgive_covered_period_to | String | 2020-09-06 | The covered period end date in YYYY-MM-DD |
| forgive_alternate_covered_period_from | String | 2020-07-06 | The alternate covered period start date in YYYY-MM-DD |
| forgive_alternate_covered_period_to | String | 2020-09-06 | The alternate covered period end date in YYYY-MM-DD |
| forgive_payroll_schedule | String | Weekly | The payroll schedule. Possible Values: “Weekly”,”Biweekly”,”Twice Per Month”,”Monthly”,”Other”. (Other is free form to match 3508 options) |
| primary_email | String | user@example.com | The primary contact persons email |
| primary_name | String | jason | The primary contact for the loan |
| ez_form | Boolean | true | Indicates whether the application submitted via EZ form |
| no_reduction_in_employees | Boolean | true | No reduction in employees or average paid hours: If you have not reduced the number of employees or the average paid hours of your employees between January 1, 2020 and the end of the Covered Period, set to true |
| no_reduction_in_employees_and_ covid_impact |
Boolean | true | FTE Reduction Safe Harbor 1: If you were unable to operate between February 15, 2020, and the end of the Covered Period at the same level of business activity as before February 15, 2020 due to compliance with requirements established or guidance issued between March 1, 2020 and December 31, 2020, by the Secretary of Health and Human Services, the Director of the Centers for Disease Control and Prevention, or the Occupational Safety and Health Administration related to the maintenance of standards for sanitation, social distancing, or any other worker or customer safety requirement related to COVID-19, set to true |
| forgive_lender_confirmation | Boolean | true | Confirmation from lender that they reviewed borrowers forgiveness application before submitting to SBA. Only ‘true’ value submits the request successfully |
| forgive_lender_decision | Number | 1 | Final lender decision regarding forgiveness of this PPP loan. Valid Values (API needs to pass integer value associated with the decision): APPROVED_IN_FULL = 0 APPROVED_IN_PART = 1 DENIED = 2 |
| sba_decision | String | Fully Approved | 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. |
| approval_date | String | 2020-08-20 | The date on which Forgiveness application was decisioned by SBA |
| final_forgive_amount | Number | 1000.00 | The final Forgiveness amount approved SBA. You will only see this populate once we run the payment processing jobs. |
| calculated_interest | Number | 10.00 | The calculated interest on ther Forgiveness amount |
| final_forgive_payment | Number | 910.00 | This is the final Forgiveness payment (Principal - EIDL Advance) + Interest Due on Net Amount) |
| final_forgive_payment_date | String | 2020-08-25 | The date on which SBA initiates payment to lender (our process generally runs at 11:00am EST during Fed processing days |
| final_forgive_payment_batch | String | PPY08091 | Internal Payment Processing Batch |
| final_forgive_amount_with_interest | Number | 910.00 | final_forgive_amount - EIDL Advances + Interest accrued over the period of the loan (Funding Date to Payment Date) |
| payment_status | String | Payment Sent | The payment status of forgiveness request. Possible Values: Payment Sent,Payment Confirmed,Payment Failed |
| s_form | Boolean | true | Indicates whether the application submitted via 3508S form |
| adjustments | JSON Array |
Adjustment array | |
| payment_amount | Number | 100.00 | Total Adjustment amount |
| payment_date | String | 2020-11-21 | Date on which adjustment payment was initiated by Forgiveness platform |
| status | string | Payment Confirmed | Adjustment payment status, can have values of Payment Sent or Payment Confirmed for under payment request and Under Review or Eligible for payment for over payment request |
| payment_batch | string | PF011224 | Payment Batch in which adjustment payment was initiated, applicable for under payment only |
| payment_confirmed_at | string | 2020-11-22 | Date on which adjustment payment was confirmed by SBA. It gets populated with date when status is Payment Confirmed |
| document | string | 09deacc4-a0af-47ec-93fd-a30e9bc45701 | Slug id of the adjustment document, applicable for under payment requests only |
| principal_amount | Number | 50000.0 | Principal amount of adjustment |
| interest_amount | Number | 95.83 | Interest amount of adjustment |
| disbursement_date | String | 2021-03-14 | Disbursement date of adjusted payment, applicable for under payment only |
| reason | String | Lender Input Error | Reason of the payment adjustment, applicable for under payment only |
| calculation_method | String | Calculate interest from Disbursement Date to Original Payment Date | Calculation method used for payment adjustment, applicable for under payment only |
| payment_type | String | Over Payment | Reason for payment adjustment, valid values are Under Payment or Over Payment |
| total_adjustments | Number | 100.00 | Total adjustment amount, will be sum of the all under adjustments for SBA number |
| naics_code | Number | 722513 | Borrower/Business - Valid 6 digit NAICS code (In prod - 03/05) |
| ppp_loan_draw | Number | 1 | Indicates whether it’s a first draw or second draw forgiveness , 1 for first draw & 2 for second draw (In prod - 03/05) |
| forgive_covered_operations_expenditures | Number | null | Covered Operations expenditure (In prod - 03/05) |
| forgive_covered_property_damage_costs | Number | null | covered property damage cost (In prod - 03/05) |
| forgive_covered_supplier_costs | Number | 1000.00 | covered supplier cost (In prod - 03/05) |
| forgive_covered_protection_expenditures | Number | 1000.00 | covered worker protection expenditure (In prod - 03/05) |
| source | Number | 1 | If the Forgiveness was initiated by Lender, it’s value by 1 else if it was intiiated by borrower (direct forgiveness) its value will be 2 |
| loan_increase | Number | 1000.00 | Any Loan increase which lender did on the Loan after initial Loan approval. This amount is already included in PPP Loan amount |
| loan_increase_date | String | 2020-07-09 | Date on which increased Loan was disbursed by Lender. Lender will be paid interest on Loan increased amount from this date |
| created | String | 2020-07-12 | The created date of the Forgiveness request in YYYY-MM-DD |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
This API provides Status/Details of a specific submitted forgiveness request. Client may choose to use this API in case they would like to get latest details of a particular forgiveness request.
7. Delete Forgiveness Request
This API is used for deleting the existing Forgiveness request
Please note:
- Forgiveness requests can only be deleted if their status is “Pending Validation”.
- Delete Forgiveness request also deletes corresponding supporting documents.
- This is a destructive operation and is only allowed in certain circumstances where SBA has not started their internal review.
- You must escalate to the Lender Support team at the SBA to have requested authorized for removal after they are under review.
- UUID SLUG corresponds to the Forgiveness Request SLUG, not the SBA Loan SLUG UUID
Request type: HTTPS
API Endpoint:
DELETE /api/ppp_loan_forgiveness_requests/{slug}/
Request (Sample)
/api/ppp_loan_forgiveness_requests/3fa85f64-5717-4562-b3fc-2c963f66afa6/
Request Parameters
Not Applicable (No request body)
Request Path Parameters
| Path Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| slug | UUID | Mandatory | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | The UUID of the forgiveness request |
Request Query Parameters
Not Applicable
Request Form Data Parameters
Not Applicable
HTTP Response Code: 204
The request was successfully processed
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 404
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Not found | The detail of the 404 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
Client may use this API to delete forgiveness request and supporting documents. For any reason, if client would like to delete Forgiveness request, try to call this API as soon as possible, before SBA starts reviewing it. Once SBA starts reviewing a request, Forgiveness cannot be deleted.
8. Get Forgiveness Messages
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.
Request type: HTTPS
API Endpoint:
GET /api/ppp_loan_forgiveness_messages/
Request (Sample)
/api/ppp_loan_forgiveness_messages/
Request Parameters
Not Applicable (No request body)
Request Path Parameters
Not Applicable
Request Query Parameters
| Query Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| sba_number | String | Optional | 9999114733 | sba loan number |
| is_complete | Boolean | Optional | true | false: Message has not been replied by the lender. true: Message has been replied by the lender. |
| page | Number | Optional | 1 | The page number of the records to be fetched (for pagination) |
Form Data Request Parameters
Not Applicable
Response (Sample)
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"sba_number": "9999114733",
"subject": "Need Attention - Payroll Document",
"ticket": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"messages": [
{
"sent_at": "2020-07-10T16:48:37.820Z",
"content": "Missing supporting payroll document, please upload"
}
],
"is_complete": true,
"needs_attention": false
}
]
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| count | Number | 1 | The total count of the records |
| next | String | null | The URI of the next set of forgiveness request messages to be fetched |
| previous | String | null | The URI of the previous set of forgiveness request messages to be fetched |
| results | JSON Array |
||
| sba_number | Number | 9999114733 | The sba loan number. This will be null for Generic/Other messages (not requiring documents). |
| subject | String | Need Attention - Payroll Document | The subject line of the ticket |
| ticket | UUID | c492c620-1f86-4a4d-a3b1-6c69ab2e44ca | The unique Id of the ticket. This will be null for Generic/Other messages (not requiring documents). |
| messages | JSON Array |
||
| sent_at | String | 2020-07-10T16:48:37.820Z | The date time of the message in UTC |
| content | String | Missing supporting payroll document, please upload | The message content |
| is_complete | Boolean | true | false: Message has not been replied by the Lender. true: Message has been replied and completed by the Lender. |
| needs_attention | Boolean | true | false: Response by Lender is not past due. true: Response by Lender is past due. |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
Client may like to call this API to retrieve all messages for all their Forgiveness requests. If client is only looking for messages which Lender has not replied back, look for field - “is_complete” having value of false. 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.
9. Get Forgiveness Message using Forgiveness request uuid
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 for a specific Forgiveness UUID.
Request type: HTTPS
API Endpoint:
GET /api/ppp_loan_forgiveness_messages/{slug}/
Request (Sample)
/api/ppp_loan_forgiveness_messages/3fa85f64-5717-4562-b3fc-2c963f66afa6/
Request Parameters
Not Applicable (No request body)
Request Path Parameters
| Path Parameter | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| slug | UUID | Mandatory | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | The UUID of the forgiveness request |
Request Query Parameters
Not Applicable
Form Data Request Parameters
Not Applicable
Response (Sample)
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"sba_number": "9999114733",
"subject": "Need Attention - Payroll Document",
"ticket": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"messages": [
{
"sent_at": "2020-07-10T17:17:49.608Z",
"content": "Missing supporting payroll document, please upload"
}
],
"is_complete": true,
"needs_attention": false
}
]
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| count | Number | 1 | The total count of the records |
| next | String | null | The URI of the next set of forgiveness request messages to be fetched |
| previous | String | null | The URI of the previous set of forgiveness request messages to be fetched |
| results | JSON Array |
||
| sba_number | String | 9999114733 | The sba loan number |
| subject | String | Need Attention - Payroll Document | The subject line of the ticket |
| ticket | UUID | c492c620-1f86-4a4d-a3b1-6c69ab2e44ca | The unique Id of the forgiveness request |
| messages | JSON Array |
||
| sent_at | String | 2020-07-10T16:48:37.820Z | The date time of the message in UTC |
| content | String | Missing supporting payroll document, please upload | The message content |
| is_complete | Boolean | true | false: Message has not been replied by the lender. true: Message has been replied by the lender. |
| needs_attention | Boolean | true | false: SLA for response by Lender has not breached. true: Response by Lender is past due. |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
Client may like to call this API to retrieve messages sent by SBA to Lender for a particular forgiveness request.
10. Get Forgiveness Message using SBA Number
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 for a specific SBA number.
Request type: HTTPS
API Endpoint:
GET /api/ppp_loan_forgiveness_messages/?sba_number={sba_number}
Request (Sample)
/api/ppp_loan_forgiveness_messages/?sba_number=9999114733
Request Parameters
Not Applicable (No request body)
Request Path Parameters
Not Applicable
Request Query Parameters
| Query Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| sba_number | String | Mandatory | 9999114733 | The SBA Number for the etran loan |
Request Form Data Parameters
Not Applicable
Response (Sample)
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"sba_number": "9999114733",
"subject": "Need Attention - Payroll Document",
"ticket": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"messages": [
{
"sent_at": "2020-07-10T17:17:49.608Z",
"content": "Missing supporting payroll document, please upload"
}
],
"is_complete": true,
"needs_attention": false
}
]
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| count | Number | 1 | The total count of the records |
| next | String | null | The URI of the next set of forgiveness request messages to be fetched |
| previous | String | null | The URI of the previous set of forgiveness request messages to be fetched |
| results | JSON Array |
||
| sba_number | String | 9999114733 | The sba loan number |
| subject | String | Need Attention - Payroll Document | The subject line of the ticket |
| ticket | UUID | c492c620-1f86-4a4d-a3b1-6c69ab2e44ca | The unique Id of the forgiveness request |
| messages | JSON Array |
||
| sent_at | String | 2020-07-10T16:48:37.820Z | The date time of the message in UTC |
| content | String | Missing supporting payroll document, please upload | The message content |
| is_complete | Boolean | true | false: Message has not been replied by the lender. true: Message has been replied by the lender. |
| needs_attention | Boolean | true | false: SLA for response by Lender has not breached. true: Response by Lender is past due. |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
Client may like to call this API to retrieve messages sent by SBA to Lender for a particular forgiveness request.
11. Reply to SBA Message
During review of a Forgiveness request, SBA may require additional information from lender. This API is used by lender to respond back to SBA by attaching requested documents.
**Important:
A. This API requires the data and the document file attachment to be sent as form parameters. The Content-type must be multipart/form-data
B. This API supports multiple documents submission in single API call. For multiple documents reply, use a single content field in the request
C. This API can also be used in conjunction with POST /api/ppp_loan_documents/ in case initial documents were never submitted with decision and status went to Lender Additional Info Needed
D. Other messages (not requiring documents) between Lender and SBA can only be replied back via Portal - Inbox **
Request type: HTTPS
API Endpoint:
PUT /api/ppp_loan_forgiveness_message_reply/{slug}/
Content-type: multipart/form-data
Request (Sample)
/api/ppp_loan_forgiveness_message_reply/3fa85f64-5717-4562-b3fc-2c963f66afa6/
Request Parameters
Not Applicable (No request body)
Request Path Parameters
| Path Parameter | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| slug | UUID | Mandatory | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | The UUID of the forgiveness request |
Request Query Parameters
Not Applicable
Request Form Data Parameters
| Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| document_type | Number | Optional | 1 | The type of document uploaded. Possible Values can be found by calling the GET API: 1. Get Document Types |
| document_name | String | Optional | Payroll.pdf | The name of the document |
| document | File | Optional | Payroll.pdf | Actual file to be uploaded. The file that needs to be part of the multipart/form-data request. Allowed file types include .pdf,.xls,.xlsx,.csv,.doc,.docx,.jpg,.jpeg,.png document_type and document_name are mandatory if document is uploaded. |
| content | String | Mandatory | Supporting payroll document as requested | The message content of the reply to be sent to SBA |
Response (Sample)
{
"success": true,
"msg": "The document was successfully uploaded"
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| success | Boolean | true | Indicates whether the reply was successfully sent to SBA. |
| msg | String | The document was successfully uploaded | Detail message of the 200 response |
HTTP Response Code: 400
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| success | Boolean | true | Indicates whether the request succeeded |
| msg | String | Could not save message. Please verify your data and send again. | Detail message of the 400 response |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
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 addional 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
12. Validate/Lookup Disbursed PPP Loan
This endpoint allows Lender/Vendor to validate/lookup disbursed PPP Loans
Request type: HTTPS
API Endpoint:
GET /api/ppp_loan_validations/
Request (Sample)
/api/ppp_loan_validations/
Request Parameters
Not Applicable (No request body)
Request Path Parameters
Not Applicable
Request Query Parameters
| Query Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| sba_number | String | Optional | 9999114733 | The SBA Number for the etran loan |
Request Form Data Parameters
Not Applicable
Response (Sample)
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"organization_name": "Xyz Bank",
"bank_notional_amount": 900000.0,
"sba_number": "9999114733",
"entity_name": "Abc Inc",
"ein": "997114733",
"funding_date": "2020-07-06",
"disbursement_date": "2020-08-01",
"tin_type": 0,
"ppp_loan_draw": 1,
"forgive_eidl_amount": 100.0,
"eidl_details":"[{\"applicationnmb\":3601351708,\"processdt\":\"08/10/2020\",\"transactionamt\":100}]",
"covid_flag": "pass",
"sba_sample_indicator": true,
"hold_details": "[{\"Code\":1,\"Description\":\"Criminal Record\",\"StartDate\":\"09/19/2020\",\"EndDate\":null,\"LenderDescription\":\"Criminal Record - Criminal
Record identified in public records - Potential eligibility issue (Lender Can Certify)\",\"LenderAction\":\"\"}, {\"Code\":12,\"Description\":\"SBA Franchise
Directory Review\",\"StartDate\":\"09/19/2020\",\"EndDate\":\"01/26/2021\",\"LenderDescription\":\"SBA Franchise Directory Review - Borrower identified as franchise
in Etran but cannot be identified on Franchise Directory - Potential eligibility issue (Lender Can Not Certify - Must Upload Documentation)]"
}
]
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| count | Number | 1 | The count of the records returned in response |
| next | String | null | The URI of the next set of disbursed PPP loans to be fetched |
| previous | String | null | The URI of the previous set of disbursed PPP loans to be fetched |
| results | JSON Array |
||
| organization_name | String | Xyz Bank | The name of organization. |
| bank_notional_amount | Number | 900000.00 | The PPP loan amount |
| sba_number | String | 9999114733 | The SBA loan number |
| entity_name | String | Abc Inc | The entity name of the borrower |
| ein | String | 997114733 | The SSN or Business TIN of the borrower |
| funding_date | String | 2020-07-06 | The funding date of the loan as per etran, in YYYY-MM-DD. This may not be same as lender’s Loan disbursement date |
| disbursement_date | String | 2020-08-01 | The disbursement date of the loan as updated by Lender in etran, in YYYY-MM-DD. |
| tin_type | Number | 0 | Borrower used EIN or SSN for Loan - Borrower/Business - EIN=0, SSN=1 |
| ppp_loan_draw | Number | 1 | Loan is part of First draw (1) or second draw (2) |
| forgive_eidl_amount | Number | 100.00 | The EIDL advance from SBA system of record. |
| eidl_details | String | JSON Array |
The EIDL amount transaction details from SBA system of record. We are storing raw JSON as string. So, this would need to be converted to JSON in order to parse. |
| covid_flag | string | pass | Flag which determines whether revenue reduction document is required from Borrower for 2nd draw Loans of <=150K. Valid values - fail means document is required, pass means document is not required, null means covid score is not applicable |
| sba_sample_indicator | Boolean | true | Whether PPP Loan is in sample for likely review as determined by SBA |
| hold_details | String | “Code":1,"Description":"Criminal Record","StartDate":"09/19/2020","EndDate":null,"LenderDescription":"Criminal Record - Criminal Record identified in public records - Potential eligibility issue (Lender Can Certify) | Details of all SBA authorized holds which are on a Loan |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
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 record.Disbursed Loans will be added/updated once a day.
13. Get All Forgiveness Documents
This endpoint allows Lender/Vendor to get all the documents uploaded for the forgiveness request.These documents include Lender provided and SBA generated notification letters.
Document expiry is valid for 15 seconds based on security guidelines agreement with SBA
Vendors/Lenders may only like to download documents which SBA provided (like payment confirmation or loan review etc.), since they would already have Lender/borrower provided documents in their platform
Documents are sorted by latest documents first which likely will be SBA documents
Request type: HTTPS
API Endpoint:
GET /api/ppp_loan_documents/
Request (Sample)
/api/ppp_loan_documents/
Request Parameters
Not Applicable (No request body)
Request Path Parameters
Not Applicable
Request Query Parameters
| Query Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| sba_number | String | Optional | 9999114733 | The SBA Number for which the documents need to be fetched |
| name | String | Optional | Payroll | The name of the document. This can be used as a search keyword |
Request Form Data Parameters
Not Applicable
Response (Sample)
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"slug": "5ae02dd4-a7f7-4c40-90fc-20cba32e8de0",
"name": "Payroll.pdf",
"created_at": "2020-07-06T17:50:43.369Z",
"updated_at": "2020-07-06T17:50:43.369Z",
"document": "https://lenders-co-operative/../Payroll.pdf",
"url": "https://lenders-co-operative/../Payroll.pdf",
"etran_loan": "df481fbb-c41f-46f3-b96f-94374d747a8d",
"document_type": {
"id": 1,
"name": "Loan Application Supporting Docs (Payroll)",
"description": "Loan Application Supporting Docs (Payroll)"
}
}
]
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| count | Number | 1 | The count of the records returned in response |
| next | String | null | The URI of the next set of documents to be fetched |
| previous | String | null | The URI of the previous set of documents to be fetched |
| results | JSON Array |
||
| slug | UUID | 5ae02dd4-a7f7-4c40-90fc-20cba32e8de0 | The UUID of the document |
| name | String | Payroll.pdf | The name of the document |
| created_at | String | 2020-07-06T17:17:58.218Z | The created date time of the document in UTC |
| updated_at | String | 2020-07-06T17:17:58.218Z | The updated date time of the document in UTC |
| document | String | https://lenders-co-operative/../Payroll.pdf | The short lived URL of the document on the server. This has an expiry of 15 seconds |
| url | String | https://lenders-co-operative/../Payroll.pdf | Permalink for document on server |
| etran_loan | String | df481fbb-c41f-46f3-b96f-94374d747a8d | The UUID(Slug) of the etran loan which came as part of the forgiveness request creation. This ensures the document gets attached to the corresponding forgiveness request |
| document_type | JSON Object |
||
| id | Number | 1 | The id of the document type as defined in SBA System |
| name | String | Loan Application Supporting Docs (Payroll) | The name of the document type |
| description | String | Loan Application Supporting Docs (Payroll) | The description of the document type |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
This API can be used with Optional parameter sba_number and/or name. We can use both the parameters together for narrow down results. 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 500 maximum records
For the payment confirmation letter, document id is 32 and document name is “Payment Confirmation”
For the payment adjustment letter, document id is 37 and document name is “Payment Correction Confirmation”
When a forgiveness decision goes for SBA review(Lender Additional Info Needed), document id is 34 and document name is “SBA Correspondence - All documents”
14. Get Direct Forgiveness details
This endpoint allows Lender/Vendor to get all the direct forgiveness requests and its details which are submitted directly by borrowers. If no status parameter is selected, this API will return pending and failed validation requests only.
Request type: HTTPS
API Endpoint:
GET /api/direct_forgiveness_requests/
Request (Sample)
direct_forgiveness_requests/?page=1
Request Parameters
Not Applicable (No request body)
Request Path Parameters
Not Applicable
Request Query Parameters
| Query Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| page | Number | Optional | 1 | The page number of the records to be fetched (for pagination) |
| status | string | Optional | pending | Borrower’s direct forgiveness status based on lender action. Valid values of approved, rejected, borrower_correction, failed_validation, all |
| page_size | Number | Optional | 1000 | Maximum number of records that can be fetched per page, default is 100 and max allowed is 1000 |
Request Form Data Parameters
Not Applicable
Response (Sample)
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"entity_name": "ABC Business",
"address1": "130 Madison Lane",
"address2": "Newark Delaware 19707",
"dba_name": "ABC",
"ein": "459120043",
"primary_name": "Ben Wallace",
"primary_email": "abc@gmail.com",
"phone_number": "1234567890",
"naics_code": 111140,
"ppp_loan_draw": 1,
"sba_number": "3929132443",
"loan_number": "111111111",
"bank_notional_amount": 150000.0,
"funding_date": "2021-02-01",
"forgive_covered_period_from": "2021-02-01",
"forgive_covered_period_to": "2021-05-10",
"forgive_fte_at_loan_application": 1,
"forgive_fte_at_forgiveness_application": 1,
"forgive_2_million": false,
"forgive_payroll": 105000.0,
"forgive_amount": 150000.0,
"loan_increase": 100.0,
"loan_increase_date": "2021-05-25",
"sba_sample_indicator": true,
"status": "Approved",
"etran_loan_slug": "d9dbd558-7c34-451f-b929-d1828dabe20e",
"demographics": [],
"created_at": "2021-08-04T17:39:45.263064Z",
"updated_at": "2021-08-04T17:39:45.263083Z",
"covid_flag": "",
"decision_by": null
},
{
"entity_name": "CDE Business",
"address1": "120 Madison Lane",
"address2": "Newark Delaware 19707",
"dba_name": "CDE",
"ein": "405519733",
"primary_name": "Tim",
"primary_email": "abc@thesummitgrp.com",
"phone_number": "1234567890",
"naics_code": 111191,
"ppp_loan_draw": 1,
"sba_number": "4187203098",
"loan_number": "111111112",
"bank_notional_amount": 100000.0,
"funding_date": "2020-04-27",
"forgive_covered_period_from": "2020-04-27",
"forgive_covered_period_to": "2020-09-27",
"forgive_fte_at_loan_application": 1,
"forgive_fte_at_forgiveness_application": 1,
"forgive_2_million": false,
"forgive_payroll": 60000.0,
"forgive_amount": 100000.0,
"loan_increase": 32423.0,
"loan_increase_date": "2021-07-13",
"sba_sample_indicator": false,
"status": "Approved",
"etran_loan_slug": "d9dbd558-7c34-451f-b929-d1828dabe20e",
"demographics": [],
"created_at": "2021-08-04T17:39:45.263064Z",
"updated_at": "2021-08-04T17:39:45.263083Z",
"covid_flag": "",
"decision_by": null
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| count | Number | 1 | The count of the records returned in response |
| next | String | null | The URI of the next set of documents to be fetched |
| previous | String | null | The URI of the previous set of documents to be fetched |
| results | JSON Array |
||
| entity_name | String | Abc Inc | The entity name of the borrower |
| address1 | String | 5050 Ritter Road – Suite B | Business Address Line 1 |
| address2 | String | Mechanicsburg, PA | Business Address Line 2 |
| dba_name | String | Abc Inc | The DBA Name or Trade Name of the borrower |
| ein | String | 997114733 | The SSN or Business TIN of the borrower |
| primary_name | String | Jason | The primary contact for the loan |
| primary_email | String | user@example.com | The primary contact persons email |
| phone_number | String | 6102342123 | The Business Phone Number of the borrower |
| naics_code | Number | 722513 | Borrower/Business - Valid 6 digit NAICS code |
| ppp_loan_draw | Number | 1 | Indicates whether it’s a first draw or second draw forgiveness , 1 for first draw & 2 for second draw. |
| sba_number | String | 9999114733 | The SBA loan number |
| loan_number | String | 7777777 | The Lender’s loan number |
| bank_notional_amount | Number | 900000.00 | The PPP loan amount |
| funding_date | String | 2020-07-06 | PPP loan Disbursement date in YYYY-MM-DD |
| forgive_covered_period_from | String | 2020-07-06 | The covered period start date in YYYY-MM-DD |
| forgive_covered_period_to | String | 2020-09-06 | The covered period end date in YYYY-MM-DD |
| forgive_fte_at_loan_application | Number | 10 | The full time employees at the time of loan application, decimal values are not allowed |
| forgive_fte_at_forgiveness_application | Number | 10 | Full time employees at the time of forgiveness application, decimal values are not allowed |
| forgive_2_million | Boolean | false | If Borrower (together with affiliates, if applicable) received PPP loans in excess of $2 million, set to true |
| forgive_payroll | Number | 1000.00 | Payroll Cost |
| forgive_amount | Number | 1666.66 | Forgiveness Amount |
| loan_increase | Number | 1000.00 | If applicable, Any Loan increase done in etran, on the PPP Loan |
| loan_increase_date | string | 2021-07-13 | If applicable, Date on which increased loan amount was disbursed |
| sba_sample_indicator | Boolean | true | Whether PPP Loan is in sample for likely review as determined by SBA |
| demographics | JSON Array |
||
| name | String | Jason | The Principal name |
| position | String | self-employed individual | Identify the Principal’s position; for example, self-employed individual; independent contractor; sole proprietor; general partner; owner; officer; director; member; or key employee. |
| veteran_status | String | 1 | The veteran status of the borrower. Possible Values: [ 1, 2, 3, 4, X ] 1=Non-Veteran; 2=Veteran; 3=Service-Disabled Veteran; 4=Spouse of Veteran; X=Not Disclosed |
| gender | String | M | The gender of the borrower. Possible Values: [M, F, X ] M=Male; F=Female; X=Not Disclosed |
| ethnicity | String | H | The ethnicity of the borrower. Possible Values: [H, N, X ] H=Hispanic or Latino; N=Not Hispanic or Latino; X=Not Disclosed |
| races | JSON Array |
||
| race | String | 1 | The race of the borrower. Possible Values: [1, 2, 3, 4, 5, X ] 1=American Indian or Alaska Native; 2=Asian; 3=Black or African-American; 4=Native Hawaiian or Pacific Islander; 5=White; X=Not Disclosed |
| status | String | approved | This field indicates the status of direct forgiveness application based on Lender action. Valid values include approved, rejected, borrower_correction, failed_validation |
| etran_loan_slug | String | d9dbd558-7c34-451f-b929-d1828dabe20e | This field indicates the slug of the Forgiveness once Lender approves direct forgiveness request. This slug can be used by API users to track status of SBA’s action on Forgiveness and can be used to make Get Forgiveness Request Details using UUID - GET /api/ppp_loan_forgiveness_requests/{slug}/ |
| created_at | String | 2021-08-04T17:39:45.263064Z | Timestamp of direct forgiveness submission to lender |
| updated_at | String | 2021-08-04T17:39:45.263064Z | Timestamp of direct forgiveness last updated |
| decision_by | String | John | Name of the Lender reviewer who decisioned direct forgiveness |
| covid_flag | string | pass | Flag which determines whether revenue reduction document is required from Borrower for 2nd draw Loans of <=150K. Valid values - fail means document is required, pass means document is not required, null means covid score is not applicable |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
This API can be used with Optional parameter of page number and direct forgiveness application status based on Lender action.
15. Get Guarantee purchase details
This endpoint allows Lenders to look at status of all Guaranted purchase requests
Request type: HTTPS
API Endpoint:
GET /api/purchase_guarantee_status/
Request (Sample)
purchase_guarantee_status/?page=1
Request Parameters
Not Applicable (No request body)
Request Path Parameters
Not Applicable (No path parameter)
Request Query Parameters
| Query Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| page | Number | Optional | 1 | The page number of the records to be fetched (for pagination) |
Request Form Data Parameters
Not Applicable
Response (Sample)
{
"count": 38,
"next": null,
"previous": null,
"results": [
{
"sba_number": "3187205591",
"principal_amount": 108300.33,
"interest_amount": 5000.0,
"payment_amount": 113300.33,
"status": "Payment Sent",
"created_at": "2021-07-02T19:08:40.098195Z",
"updated_at": "2021-07-08T17:52:27.852833Z",
"sba_decision": ""
},
{
"sba_number": "3187205605",
"principal_amount": 95000.0,
"interest_amount": 500.0,
"payment_amount": 95500.0,
"status": "Payment Sent",
"created_at": "2021-07-06T07:56:39.048675Z",
"updated_at": "2021-07-08T17:52:27.853173Z",
"sba_decision": "Fully Approved"
}
]
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| count | Number | 1 | The count of the records returned in response |
| next | String | null | The URI of the next set of documents to be fetched |
| previous | String | null | The URI of the previous set of documents to be fetched |
| results | JSON Array |
||
| sba_number | String | 9999114733 | The SBA loan number |
| principal_amount | Number | 50000.0 | Principal amount of adjustment |
| interest_amount | Number | 95.83 | Interest amount of adjustment |
| payment_amount | Number | 100.00 | Adjustment amount |
| status | String | Payment Sent | This value indicates the status of Lender’s Guarantee purchase request |
| created_at | String | 2020-07-06T17:17:58.218Z | The created/submission date time of the Guranteed Purchase in UTC |
| updated_at | String | 2020-07-06T17:17:58.218Z | The updated date time of the Guranteed Purchase in UTC |
| sba_decision | String | Fully Approved | This value will always indicate the status of the SBA Decision only |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |
Design Consideration for Client Application
This API can be used with Optional parameter of page number.
16. Get Guarantee purchase details by SBA number
This endpoint allows Lenders to look at status of Guaranted purchase request by SBA number
Request type: HTTPS
API Endpoint:
GET /api/purchase_guarantee_status/SBA_Number
Request (Sample)
purchase_guarantee_status/sba_number
Request Parameters
Not Applicable (No request body)
Request Path Parameters
| Path Parameter Name | Data Type | Mandatory/Optional | Sample Value | Description |
|---|---|---|---|---|
| sba_number | Number | Mandatory | 3187205605 | SBA number used for Guaranteed purchase |
Request Query Parameters
Not Applicable (No query parameter)
Request Form Data Parameters
Not Applicable
Response (Sample)
{
"sba_number": "3187205605",
"principal_amount": 95000.0,
"interest_amount": 500.0,
"payment_amount": 95500.0,
"status": "Payment Sent",
"created_at": "2021-07-06T07:56:39.048675Z",
"updated_at": "2021-07-08T17:52:27.853173Z",
"sba_decision": "Fully Approved"
}
Response Parameters
HTTP Response Code: 200
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| sba_number | String | 9999114733 | The SBA loan number |
| principal_amount | Number | 50000.0 | Principal amount of adjustment |
| interest_amount | Number | 95.83 | Interest amount of adjustment |
| payment_amount | Number | 100.00 | Adjustment amount |
| status | String | Payment Sent | This value indicates the status of Lender’s Guarantee purchase request |
| created_at | String | 2020-07-06T17:17:58.218Z | The created/submission date time of the Guranteed Purchase in UTC |
| updated_at | String | 2020-07-06T17:17:58.218Z | The updated date time of the Guranteed Purchase in UTC |
| sba_decision | String | Fully Approved | This value will always indicate the status of the SBA Decision only |
HTTP Response Code: 403
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Authentication credentials were not provided. | The detail of the 403 error response |
HTTP Response Code: 429
API Call Rate Limits
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. The exception message states: “Request was throttled. Expected available in 1 second”.
| Parameter Name | Data Type | Sample Value | Description |
|---|---|---|---|
| detail | String | Request was throttled. Expected available in 1 second | The detail of the 429 error response |
| status_code | Number | 429 | The HTTP status code |