Restaurant RRF APIs - API Dictionary

Table of Contents

Pre-requisites
Environment
1. Get Document Types
2. Create RRF Request
3. Upload RRF documents
4. Get Details of RRF Request using user name and UUID
5. Get RRF Request Details using user name and confirmation id
6. Get RRF Request Details using TIN and TIN type
7. Delete RRF Request
8. Get All RRF Documents
9. Get ALL Franchise Details
10. Get Franchise Details using Franchise code or name
11. Validate/Lookup Disbursed PPP Loan
12. Get Validated and Standardized Address

This document gives an overview for the API’s that are exposed by the Restaurant Grant Application.

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 grant API’s are exposed in the Sandbox and Production environment

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

1. Get Document Types

The API is used to get the list of available document types in the SBA grant portal. These document types are needed when sharing supporting documents for a Restaurant Grant, with SBA .

Request type: HTTPS

API Endpoint:

GET /api/grant_document_types/

Request (Sample)

/api/grant_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": "2019 Tax Document",
            "description": "2019 IRS Tax Document"
        }
    ]
}

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	2019 Tax Document	The name of the document
description	String	2019 IRS Tax Document	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, grant 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 grant Request

This API is used to submit Grant Application data to SBA system.

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/grants/

Request Path Parameters

Not Applicable

Request Query Parameters

Not Applicable

Request Form Data Parameters

Not Applicable

Request (Sample Body)

{
    "business": {
        "owners": [
{
                  "owner_type": 1,
                  "first_name": "Carol",
                  "last_name": "carolson",
                  "title": "president",
                  "address_line_1": "1600 Pennsylvania Ave",
                  "city":"Washington",
                  "state":"DC",
                  "zip_code": "20500",
                  "zip_code_plus4": "1234",
                  "tin": "564565458",
                  "tin_type": 1,
                  "ownership_percentage": "100",
                  "position": "positiontest",
                  "veteran_status": "X",
                  "gender": "X",
                  "ethnicity": "X",
                  "race": ["X"]
            }],
               "business_type": 4,
               "legal_name": "Test Legal",
               "address_line_1": "1600 Pennsylvania Ave",
               "address_line_2": null,
               "city": "Washington",
               "state": "DC",
               "zip_code": "20500",
               "zip_code_plus4": "1234",
               "tin": "267828827",
               "tin_type": 0,
               "phone_number": "2055551111",
               "restaurant_type": [1,2],
               "is_franchise": true,
               "is_sba_listed_franchise": true,
               "franchise_code": "S0910"
            },
                "applicant_owned_by_gov_entity": false,
                "applicant_operates_over_20_locations": false,
                "applicant_received_shuttered_venues_grant": false,
                "applicant_publicly_traded": false,
                "applicant_business_permanently_closed": false,
                "applicant_filed_bankruptcy": 1,
                "applicant_suspended_or_debarred": false,
                "applicant_has_affiliated_businesses": false,
                "additional_ppp": [
                {
                    "loan_number": 3928101802,
                    "loan_amount": "1300"
                }
                ],
                "date_of_first_sale": "2018-01-01",
                "grant_calculation_method": 1,
                "gross_receipts_validated": true,
                "number_of_locations": 1,
                "gross_receipts_2019": 10000,
                "gross_receipts_2020": 5000,
                "grant_purpose_payroll": true,
                "grant_purpose_rent": false,
                "grant_purpose_utility": false,
                "grant_purpose_debt": false,
                "grant_purpose_construction_outdoor_seating": false,
                "grant_purpose_maintenance": false,
                "grant_purpose_supplies": false,
                "grant_purpose_food": false,
                "grant_purpose_operations": false,
                "grant_purpose_covered_supplier": false,
                "grant_amount": 5000,
                "priority_group_women_owned": false,
                "priority_group_veteran": false,
                "priority_group_socio_economic": false,
                "signer_tin": "123456789",
                "signer_first_name": "carol",
                "signer_last_name": "carolson",
                "signer_phone_number": 2055551111,
                "signer_address_line_1": "1600 Pennsylvania Ave",
                "signer_address_line_2": null,
                "signer_city": "Washington",
                "signer_state": "DC",
                "signer_zip_code": "20052",
                "signer_title": 9,
                "signer_date_of_birth": "2000-01-01",
                "signer_email": "signemail@test.com",
                "bank_account": {
                   "routing_number": "123456789",
                   "account_number": "987654321",
                   "account_type": "checking"
            }
            }

Request Parameters

Parameter Name	Data Type	Mandatory/Optional	Sample Value	Description
business	`JSON Object`	Mandatory
owners	`JSON Array`	Mandatory
owner_type	Number	Mandatory	2	Owner - Whether owner is an individual or business. PERSON = 1 BUSINESS = 2
business_name	String	Conditional	ABC Corp	Owner - Business name (if owner is a business). Include only if owner_type is 2. Max 80 characters allowed
first_name	String	Conditional	James	Owner - first name, Include only if owner_type is 1. Max 40 characters allowed
last_name	String	Conditional	Marshall	Owner - last name, Include only if owner_type is 1. Max 40 characters allowed
title	String	Conditional	director	Title of the owner
business_type	number	Conditional	2	Owner - Business type if owner is a Business i.e. Conditional for Owners with owner_type=2, possible values: PARTNERSHIP = 2, C_CORP = 3, LLC = 4, S_CORP = 10, TRIBAL = 24, LLC_AS_S_CORP = 90, LLC_AS_C_CORP = 91
address_line_1	String	Mandatory	123 Second St	Owner - Street Address of owner. If owner resides outside US, use thier US or Business address. Max 80 characters allowed
address_line_2	String	Optional		Owner - Optional Address Info of owner. If owner resides outside US, use thier US or Business address. Max 80 characters allowed
city	String	Mandatory	Manhattan	Owner - city of Owner’s address.City should validate with ZIP using USPS standard. If owner resides outside US, use thier US or Business address city. Max 40 characters allowed
state	String	Mandatory	NY	Owner - 2 Letter State Code of Owner’s address. If owner resides outside US, use thier US or Business state
zip_code	String	Mandatory	10004	Owner - 5 Digit Valid Zip. If owner resides outside US, use thier US or Business zip
zip_code_plus4	String	Optional	1234	Owner - 4 Digit Zip+4. If owner resides outside US, use thier US or Business zip+4
tin	String	Mandatory	252751625	Owner - Owner’s EIN or SNN or ITIN with no spaces or dashes. See FAQ for the REG EX used in validation
tin_type	Number	Mandatory	0	Owner - EIN = 0 , SSN = 1, ITIN = 4 Owner’s TIN Type. It is conditional on Business Type. See Business Owner Matrix
ownership_percentage	Number	Mandatory	25	Owner - % ownership of owner. Valid Values from 1 to 100 and no more than 3 digits, The SBA requires that the Owners percent is at least 1%. In some scenerios where there is no owner with 1%, you will still need to submit a princpal with 1%. There is no current workaround.The SBA has finalized the ownership/principal requirement to enforce an aggregate 20% submission level for all principals combined. The system will still honor the current value of 1% (for each individual principal) – but the aggregate of those entered – must be 20%. Said differently – a single 1% principal will not be allowed via the UI or API – you must submit an achieved total of 20%.
position	String	Optional	Director	Owner - Postion as defined for demographics
veteran_status	String	Optional	1	Owner - 1=Non-Veteran; 2=Veteran; 3=Service-Disabled Veteran; 4=Spouse of Veteran; X=Not Disclosed
gender	String	Optional	M	Owner - M=Male; F=Female; X=Not Disclosed
ethnicity	String	Optional	N	Owner - H=Hispanic or Latino; N=Not Hispanic or Latino; X=Not Disclosed
race	Array with Strings allowed	Optional	1,2,3	Owner - 1=American Indian or Alaska Native; 2=Asian; 3=Black or African-American; 4=Native Hawaiian or Pacific Islander; 5=White; X=Not Disclosed
business_type	number	Mandatory	2	Borrower/Business - Borrowwer’s Business type, mandatory: SOLE_PROPRIETOR = 1, PARTNERSHIP = 2, CORPORATION = 3, LLC = 4, S_CORP = 10, ELIG_SELF_EMPLOYED = 16, INDEPENDENT_CONTRACTOR = 17, TRIBAL = 24, Single member LLC = 26, LLC_AS_S_CORP = 90, LLC_AS_C_CORP = 91
dba_tradename	String	Optional	ABC Corp	Borrower/Business - DBA name if known. Max 80 characters allowed
legal_name	String	Conditional	ABC Corp	Borrower/Business - Business name - Do not include for Business types 1,16,17. Max 80 characters allowed
first_name	String	Conditional	John	Borrower/Business - first name - include for Business types 1,16,17. Max 40 characters allowed
last_name	String	Conditional	Mich	Borrower/Business - last name - include for Business types 1,16,17. Max 40 characters allowed
address_line_1	String	Mandatory	123 Fake Street	Borrower/Business - Street Address, po box & Foreign address not allowed. Max 80 characters allowed
address_line_2	String	Optional	Suite B	Borrower/Business - Additonal street info. Max 80 characters allowed
city	String	Mandatory	Mechanicsburg	Borrower/Business - City should validate with ZIP using USPS standard. Max 40 characters allowed
state	String	Mandatory	PA	Borrower/Busienss - 2 Letter State Code
zip_code	String	Mandatory	17055	Borrower/Business - Five Digit Zip
zip_code_plus4	String	Optional	1234	Borrower/Business - 4 Digit Zip+4
tin	String	Mandatory	435881068	Borrower/Business - EIN or SSN or ITIN
tin_type	number	Mandatory	0	Borrower/Business - EIN=0, SSN=1, ITIN=4
phone_number	String	Mandatory	5482562187	Borrower/Business - Phone Number without dashes or spaces
restaurant_type	Array	Mandatory	1,2	Refer to design consideration for details - RESTAURANT = 1, LICENSED_ALCOHOL_PRODUCER = 2, BAR = 3, BREWERY = 4, WINERY = 5, DISTILLERY = 6, INN = 7, Brewpub, Tasting Room, Taproom = 8, CATERER = 9, SNACK_NON_ALCOHOLIC_BAR = 11, MOBILE_FOOD = 12, BAKERY = 13, OTHER = 14
is_franchise	boolean	Mandatory	true	Business is a Franchise - true or false
is_sba_listed_franchise	boolean	conditional	true	Whether Franchise is listed with SBA
franchise_code	String	Conditional	A12345	Borrower/Business - Valid SBA Franchise Code if if_franchise = true or is_sba_listed_franchise = true.For Grant approval, SBA expects Franchise to be listed with them
applicant_owned_by_gov_entity	boolean	mandatory	true	Whether the Applicant’s business, is a state or local government-operated business. If true, the Applicant is not eligible
applicant_operates_over_20_locations	boolean	mandatory	true	As of March 13, 2020, owns or operates (together with any affiliated business) more than 20 locations, regardless of whether those locations do business under the same or multiple names.
applicant_received_shuttered_venues_grant	boolean	mandatory	true	Has a pending application for or has received a Shuttered Venue Operators Grant
applicant_publicly_traded	boolean	mandatory	true	Is a publicly-traded company (defined as an entity that is majority owned or controlled by an entity that is an issuer, the securities of which are listed on a national securities exchange)
applicant_business_permanently_closed	boolean	mandatory	true	Is the Applicant’s business permanently closed
applicant_filed_bankruptcy	number	mandatory	1	No = 1, Yes, approved plan = 4, Yes, no plan = 3, Yes, chapter 7/perm closed = 2
applicant_suspended_or_debarred	Boolean	false	Is the Applicant or any owner of the Applicant presently suspended, debarred, proposed for debarment, declared ineligible, voluntarily excluded from participation in this transaction by any Federal department or agency
ppp_first_draw_sba_loan_number	number	optional	123456789	Did the Applicant receive a Paycheck Protection Plan (PPP) loan (First Draw PPP Loan) at any time in 2020 or 2021, if yes, what’s the sba number
ppp_first_draw_loan_amount	number	optional	50000.00	First draw sba loan amount
ppp_second_draw_sba_loan_number	number	optional	123456789	Did the Applicant receive a second-round Paycheck Protection Plan (PPP) loan (Second Draw PPP Loan) in 2021? If yes, what’s the sba number
ppp_second_draw_loan_amount	number	optional	1000.00	Second draw loan amount
additional_ppp	`JSON Object`	Optional
loan_number	number	optional	123456789	Other PPP Loan numbers
loan_amount	number	optional	1000.00	Other PPP Loan amount
applicant_has_affiliated_businesses	boolean	mandatory	true	Does the Applicant have affiliates?
number_of_affiliated_businesses	number	conditional	2	If yes, how many affiliates does the Applicant have
affiliated_businesses_details	string	conditional	abc, def	Please list each affiliate’s legal business name
date_of_first_sale	string	optional	2018-01-01	What date did you begin making sales? YYYY-MM-DD or null
months_in_operation	number	conditional	2.5	For Applicants that began operations partially through 2019, needed for table 2
number_of_locations	number	Mandatory	1	Enter the number of locations operated by the Applicant, needed for all tables
gross_receipts_2019	number	conditional	70000.00	Enter 2019 gross receipts as reported on your 2019 Federal tax return. line item 1 in table 1 or Line item 1a in table 2
gross_receipts_2020	number	conditional	50000.00	Enter 2020 gross receipts as reported or to be reported on your 2020 Federal tax return. line item 2 in table 1 and table 2
gross_receipts_signature_date	number	conditional	50000.00	Enter all gross receipts as of application signature date. Line item 2 in table 3
eligible_expenses	number	conditional	100000.00	Enter the amount you spent on eligible expenses. Eligible expenses have the same definition as eligible uses of funds. Line item 1 in table 3
grant_purpose_payroll	boolean	mandatory	true	Business Payroll Costs, including paid sick leave
grant_purpose_rent	boolean	mandatory	true	Business Rent / Business Mortgage
grant_purpose_utility	boolean	mandatory	true	Business Utilities
grant_purpose_debt	boolean	mandatory	true	Business Debt Service
grant_purpose_maintenance	boolean	mandatory	true	Business Maintenance Expenses
grant_purpose_supplies	boolean	mandatory	true	Business Supplies
grant_purpose_food	boolean	mandatory	true	Business Food and beverage expenses, including raw materials
grant_purpose_operations	boolean	mandatory	true	Business Operating Expenses
grant_purpose_covered_supplier	boolean	mandatory	true	Covered Supplier Costs
grant_purpose_construction_outdoor_seating	boolean	mandatory	true	Covered Outdoor seating
grant_amount	number	mandatory	700000.00	Calculated grant amount
priority_group_women_owned	boolean	optional	true	Applicant is a small business concern at least 51 percent owned and controlled by One or more women
priority_group_veteran	boolean	optional	true	Applicant is a small business concern at least 51 percent owned and controlled by Veteran(s)
priority_group_socio_economic	boolean	optional	true	Applicant is a small business concern at least 51 percent owned and controlled by Socially and economically disadvantaged individual(s)
signer_first_name	string	mandatory	first	First name of signer
signer_last_name	string	mandatory	last	Last name of signer
signer_phone_number	string	mandatory	3010001100	Phone number of signer
signer_address_line_1	string	mandatory	1305 ABC Lane	Address Line 1 of signer
signer_address_line_2	string	optional	XYZ	Address Line 2 of signer
signer_city	string	mandatory	Washington	City of signer
signer_state	string	mandatory	DC	state code of signer
signer_zip_code	string	mandatory	20052	zip code of signer
signer_title	number	mandatory	1	Please refer to mapping in design consideration for mapping of title to Business. Here are valid values: PRESIDENT = 1, SECRETARY = 2, TREASURER = 3, VICE_PRESIDENT = 4, ASSISTANT_TREASURER = 5, CHIEF_ACCOUNTING_OFFICER = 6, CONTROLLER = 7, HAREHOLDER = 8, PARTNER = 9, LIMITED_PARTNER = 10, OWNER = 11, SOLE_PROPRIETOR_TITLE = 12, MANAGING_MEMBER = 13
signer_email	string	mandatory	test@test.com	email address of signer
signer_date_of_birth	string	mandatory	1976-12-22	date of birth of signer
signer_tin	string	mandatory	280110010	tin of signer
gross_receipts_validated	boolean	mandatory	true	Whether gross receipts are validated by ecosystem partner or not (true or false)
grant_calculation_method	number	mandatory	1	Grant calculation method used, (1, ‘Calculation Method 1 - Began Operations on or prior to Jan 1, 2019’),(2, ‘Calculation Method 2 - Began Operations partially through 2019’),(3, ‘Calculation Method 3 - Began Operations on or after Jan 1, 2020’),(4, ‘Advanced - Combination of Methods 1-3’)
bank_account	array	mandatory	true
routing_number	string	mandatory	123456789	Routing number of funding account
account_number	string	mandatory	987654321	Account number of funding account
account_type	string	mandatory	checking	account type of funding account (checking or savings)

Response (Sample)

{
    "business": {
        "owners": [
            {
                "owner_type": 1,
                "business_name": null,
                "first_name": "Carol",
                "last_name": "carolson",
                "title": "president",
                "business_type": null,
                "ownership_percentage": "100.00",
                "tin": "564565458",
                "tin_type": 1,
                "address_line_1": "1600 Pennsylvania Ave",
                "address_line_2": null,
                "city": "Washington",
                "state": "DC",
                "zip_code": "20500",
                "zip_code_plus4": "1234",
                "position": "positiontest",
                "veteran_status": "X",
                "gender": "X",
                "ethnicity": "X",
                "race": [
                    "X"
                ]
            }
        ],
        "franchise_code": "S0910",
        "tin_type": 0,
        "tin": "267828827",
        "business_type": 4,
        "tax_form_used": 2,
        "restaurant_type": [
            1,
            2
        ],
        "dba_tradename": "",
        "legal_name": "Test Legal",
        "first_name": null,
        "last_name": null,
        "address_line_1": "1600 Pennsylvania Ave",
        "address_line_2": null,
        "city": "Washington",
        "state": "DC",
        "zip_code": "20500",
        "zip_code_plus4": "1234",
        "phone_number": "2055551111",
        "is_franchise": true
    },
    "user": {
        "username": "signemail544"
    },
    "status": "E-Signature Pending",
    "gross_receipts_2019": "10000.00",
    "gross_receipts_2020": "5000.00",
    "applicant_publicly_traded": false,
    "date_of_first_sale": "2018-01-01",
    "grant_purpose_maintenance": false,
    "gross_receipts_validated": true,
    "grant_calculation_method": 1,
    "additional_ppp": [
        {
            "loan_number": 3928101802,
            "loan_amount": "1300.00"
        }
    ],
    "slug": "078d944d-4e78-4a5c-a8f8-9f8ef867ac68",
    "submission_confirmation_id": "4e7800096939",
    "applicant_received_shuttered_venues_grant": false,
    "applicant_operates_over_20_locations": false,
    "applicant_suspended_or_debarred": false,
    "applicant_filed_bankruptcy": 1,
    "applicant_owned_by_gov_entity": false,
    "applicant_business_permanently_closed": false,
    "applicant_has_affiliated_businesses": false,
    "number_of_affiliated_businesses": null,
    "affiliated_businesses_details": null,
    "priority_group_women_owned": false,
    "priority_group_veteran": false,
    "priority_group_socio_economic": false,
    "gross_receipts_signature_date": null,
    "grant_purpose_payroll": true,
    "grant_purpose_rent": false,
    "grant_purpose_utility": false,
    "grant_purpose_debt": false,
    "grant_purpose_construction_outdoor_seating": false,
    "grant_purpose_supplies": false,
    "grant_purpose_food": false,
    "grant_purpose_operations": false,
    "grant_purpose_covered_supplier": false,
    "calc_method": 1,
    "months_in_operation": null,
    "number_of_locations": 1,
    "calc_4_grant_amount": null,
    "grant_amount": "3700.00",
    "eligible_expenses": null,
    "ppp_first_draw_sba_loan_number": null,
    "ppp_first_draw_loan_amount": null,
    "ppp_second_draw_sba_loan_number": null,
    "ppp_second_draw_loan_amount": null,
    "signer_first_name": "carol",
    "signer_last_name": "carolson",
    "signer_phone_number": "2055551111",
    "signer_title": 9,
    "signer_email": "signemail@test.com",
    "signer_tin": "123456789",
    "signer_address_line_1": "1600 Pennsylvania Ave",
    "signer_address_line_2": null,
    "signer_city": "Washington",
    "signer_state": "DC",
    "signer_zip_code": "20052",
    "signer_date_of_birth": "2000-01-01",
    "sba_number": null,
    "validation_errors": null,
    "created_at": "2021-04-22T20:33:12.125385Z",
    "submission_date": null,
    "sba_decision": null,
    "sba_decision_date": null,
    "final_payment_date": null,
    "final_payment_confirmed_date": null
}

HTTP Response Code: 200

Parameter Name	Data Type	Sample Value	Description
business	`JSON Object`
owners	`JSON Array`
business_type	number	2	Business type of owner
tin_type	number	0	Depicts whether TIN of the owner is SSN or EIN or ITIN. EIN=0, SSN=1, ITIN=4
tin	String	252751625	TIN of the owner (EIN or SSN)
owner_type	Number	1	Owner type for the Business. Valid values are 1 or 2 (1 for PERSON and 2 for BUSINESS)
business_name	String	Null	Business Owner name. It will be null if owner is a Person
first_name	String	James	Owner’s first name
last_name	String	Marshall	Owner’s last name
ownership_percentage	String	25.00	% Ownership of the owner.
address_line_1	String	123 Second St	Address Line 1 of the owner
address_line_2	String		Address Line 2 of owner
city	String	Manhattan	City of owner’s address
state	String	NY	State code of owner’s address
zip_code	String	10004	Zip code of owner’s address
zip_code_plus4	String	1234	Zip + 4 of owner’s address
position	String	Director	Position of owner based on demographic information provided as part of grant application
veteran_status	String	1	Veteran status of owner based on information provided as part of grant application (1=Non-Veteran; 2=Veteran; 3=Service-Disabled Veteran;4=Spouse of Veteran; X=Not Disclosed)
gender	String	M	Gender of the owner based on information provided as part of grant application (M=Male; F=Female; X=Not Disclosed)
ethnicity	String	N	Ethnicity of the owner based on information provided as part of grant application (H=Hispanic or Latino; N=Not Hispanic or Latino; X=Not Disclosed)
race	Array	1	Race of the owner based on information provided as part of grant application, multiple values allowed (1=American Indian or Alaska Native; 2=Asian; 3=Black or African-American; 4=Native Hawaiian or Pacific Islander; 5=White; X=Not Disclosed)
business_type	number	1	Business type
dba_tradename	String	ABC Corp	Doing Business As/Trade name for Business
legal_name	String	ABC Corp	Borrower Name
first_name	String	James	first name - Borrower
last_name	String	Marshall	last name - Borrower
address_line_1	String	5050 Ritter Rd	Address Line 1 of Borrower
address_line_2	String	Suite B	Address Line 2 of Borrower
city	String	Mechanicsburg	City of Borrower
state	String	PA	State code of Borrower
zip_code	String	17055	Zip code of Borrower
zip_code_plus4	String	1234	Zip + 4 of the Borrower
tin	String	435-88-1068	TIN of the Borrower (EIN/SSN/ITIN)
tin_type	number	1	TIN Type of the Borrower (EIN=0, SSN=1, ITIN=4)
phone_number	Number	5482562187	Business phone number
username	String	test312	Username of the SBA portal.
is_franchise	Boolean	true	Is Busienss a Franchise listed ?
is_sba_listed_franchise	boolean	true	Whether Franchise is listed with SBA
franchise_code	String	S2956	SBA Franchise Identifier Code
tax_form_used	number	null	FORM_1040 = 1, FORM_1065 = 2, FORM_1120S = 3, FORM_1120 = 4
status	String	Application in Progress	Status of Grant Request. Valid values are Esignature Pending , Esignature Processing, Submitted, Under Review, IRS Review, Not Approved, Approved, Applicant Additional Info Needed, Payment Sent, Payment Confirmed, Payment exception, Applicant correction
created_at	string	2021-01-18T18:39:49.768882Z	Timestamp with timezone (in UTC) at which grant request was created in SBA system
slug	String	9c00737c-7aa5-4741-93bb-7e4f3e5213de	Slug/Unique ID of grant application. This slug id should be used for grant status or withdrawal
submission_confirmation_id	string	57e000079120	unique submission confirmation id of the grant request submitted
applicant_owned_by_gov_entity	boolean	true	Whether the Applicant’s business, is a state or local government-operated business. If true, the Applicant is not eligible
applicant_operates_over_20_locations	boolean	true	As of March 13, 2020, owns or operates (together with any affiliated business) more than 20 locations, regardless of whether those locations do business under the same or multiple names.
applicant_received_shuttered_venues_grant	boolean	true	Has a pending application for or has received a Shuttered Venue Operators Grant
applicant_publicly_traded	boolean	true	Is a publicly-traded company (defined as an entity that is majority owned or controlled by an entity that is an issuer, the securities of which are listed on a national securities exchange)
applicant_business_permanently_closed	boolean	true	Is the Applicant’s business permanently closed
applicant_filed_bankruptcy	number	1	No = 1, Yes, approved plan = 4, Yes, no plan = 3, Yes, chapter 7/perm closed = 2
applicant_suspended_or_debarred	boolean	false	Is the Applicant or any owner of the Applicant presently suspended, debarred, proposed for debarment, declared ineligible, voluntarily excluded from participation in this transaction by any Federal department or agency
ppp_first_draw_sba_loan_number	number	123456789	Did the Applicant receive a Paycheck Protection Plan (PPP) loan (First Draw PPP Loan) at any time in 2020 or 2021, if yes, what’s the sba number
ppp_first_draw_loan_amount	number	50000.00	First draw sba loan amount
ppp_second_draw_sba_loan_number	number	123456789	Did the Applicant receive a second-round Paycheck Protection Plan (PPP) loan (Second Draw PPP Loan) in 2021? If yes, what’s the sba number
ppp_second_draw_loan_amount	number	1000.00	Second draw loan amount
applicant_has_affiliated_businesses	boolean	true	Does the Applicant have affiliates?
number_of_affiliated_businesses	number	2	If yes, how many affiliates does the Applicant have
affiliated_businesses_details	string	abc, def	Please list each affiliate’s legal business name
date_of_first_sale	string	2018-01-01	What date did you begin making sales? YYYY-MM-DD
months_in_operation	number	2.5	For Applicants that began operations partially through 2019
number_of_locations	number	1	Enter the number of locations operated by the Applicant
gross_receipts_2019	number	70000.00	Enter 2019 gross receipts as reported on your 2019 Federal tax return. line item 1 in table 1 or Line item 1a in table 2
gross_receipts_2020	number	50000.00	Enter 2020 gross receipts as reported or to be reported on your 2020 Federal tax return. line item 2 in table 1 and table 2
gross_receipts_signature_date	number	50000.00	Enter all gross receipts as of application signature date. Line item 2 in table 3
eligible_expenses	string	100000.00	Enter the amount you spent on eligible expenses. Eligible expenses have the same definition as eligible uses of funds. Line item 1 in table 3
grant_purpose_payroll	boolean	true	Business Payroll Costs, including paid sick leave
grant_purpose_rent	boolean	true	Business Rent / Business Mortgage
grant_purpose_utility	boolean	true	Business Utilities
grant_purpose_debt	boolean	true	Business Debt Service
grant_purpose_maintenance	boolean	true
grant_purpose_supplies	boolean	true	Business Supplies
grant_purpose_food	boolean	true	Business Food and beverage expenses, including raw materials
grant_purpose_operations	boolean	true	Business Operating Expenses
grant_purpose_covered_supplier	boolean	true	Covered Supplier Costs
grant_purpose_construction_outdoor_seating	boolean	true	Covered Outdoor seating
grant_amount	string	700000.00	Calculated grant amount
priority_group_women_owned	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by One or more women
priority_group_veteran	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by Veteran(s)
priority_group_socio_economic	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by Socially and economically disadvantaged individual(s)
signer_first_name	string	first	First name of signer
signer_last_name	boolean	last	Last name of signer
signer_phone_number	boolean	3010001100	Phone number of signer
signer_address_line_1	string	1305 ABC Lane	Address Line 1 of signer
signer_address_line_2	string	XYZ	Address Line 2 of signer
signer_city	string	Washington	City of signer
signer_state	string	DC	state code of signer
signer_zip_code	string	20052	zip code of signer
signer_title	number	1	Please refer to mapping in design consideration for mapping of title to Business. Here are valid values: PRESIDENT = 1, SECRETARY = 2, TREASURER = 3, VICE_PRESIDENT = 4, ASSISTANT_TREASURER = 5, CHIEF_ACCOUNTING_OFFICER = 6, CONTROLLER = 7, HAREHOLDER = 8, PARTNER = 9, LIMITED_PARTNER = 10, OWNER = 11, SOLE_PROPRIETOR_TITLE = 12, MANAGING_MEMBER = 13
signer_email	string	test@test.com	email address of signer
signer_date_of_birth	string	2000-01-01	Date of birth of signer
signer_tin	string		280110010	TIN of the signer
bank_account	array	true	Bank account details
routing_number	string	123456789	Routing number of funding account
account_number	string	987654321	Account number of funding account
account_type	string	checking	account type of funding account
submission_date	string	2000-01-01	Submission date of application
sba_decision	string	approved	Decision of application (approved or not approved)
sba_decision_date	string	null	Decision date of application
final_payment_date	string	null	Date on which payment was initiated
final_payment_confirmed_date	string	null	Date on which payment was confirmed
gross_receipts_validated	boolean	true	Whether gross receipts are validated by ecosystem partner or not (true or false)
grant_calculation_method	number	1	Grant calculation method used, (1, ‘Calculation Method 1 - Began Operations on or prior to Jan 1, 2019’),(2, ‘Calculation Method 2 - Began Operations partially through 2019’),(3, ‘Calculation Method 3 - Began Operations on or after Jan 1, 2020’),(4, ‘Advanced - Combination of Methods 1-3’)
validation_error	string	null	Validation errors from etran or asynch address validation
sba_number	number	null	sba number assigned once Grant is approved
additional_ppp	`JSON Object`
loan_number	number	123456789	Other PPP Loan numbers
loan_amount	number	1000.00	Other PPP Loan amount

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, PPP 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

Lenders can use this API to submit grant request. Grant number may not get assigned immediately.

3. Upload grant documents

This API is used to provide supporting documents for a particular grant 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/user//grants//documents/
Content-type: multipart/form-data

Request (Sample)

api/user/nbhatia/grants/8492325e-3825-425c-8666-c9f8b28a01d2/

Request Parameters

Not Applicable (No request body)

Request Path Parameters

Request Query Parameters

Not Applicable

Request Form Data Parameters

Form Data Name	Data Type	Mandatory/Optional	Sample Value	Description
name	String	Mandatory	2019-Revenue.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
grant	UUID	Mandatory	df481fbb-c41f-46f3-b96f-94374d747a8d	The UUID(Slug) of the grant which came as part of the grant request creation. This ensures the document gets attached to the corresponding grant 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": "2019-Revenue.pdf",
    "created_at": "2020-07-06T17:17:58.218Z",
    "updated_at": "2020-07-06T17:17:58.218Z",
    "document": "https://lenders-co-operative/../2019-Revenue.pdf",
    "document_type": 1,
    "url": "https://lenders-co-operative/../2019-Revenue.pdf",
    "grant": "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	2019-Revenue.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/../2019-Revenue.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/../2020-Revenue.pdf	The permalink URL of the document on the server
grant	UUID	df481fbb-c41f-46f3-b96f-94374d747a8d	The UUID(Slug) of the grant which came as part of the grant request creation. This ensures the document gets attached to the corresponding grant 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, grant 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 grant request API, as applicable. 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 grant request. If client is submitting multiple documents for a grant request, they would have to call this API multiple times.

4. Get grant Request Details using user name and Grant UUID

This API is used for getting details of existing grant requests using user name and grant slug id

Request type: HTTPS

API Endpoint:

GET /api/user/username/grants/slug/

Request (Sample)

/api/user/nbhatia/grants/8492325e-3825-425c-8666-c9f8b28a01d2/

Request Parameters

Not Applicable (No request body)

Request Path Parameters

Path Parameter Name	Data Type	Mandatory/Optional	Sample Value	Description
username	string	Mandatory	nbhatia	user name of the restaurant owner, this comes in response of create Grant API request
slug	UUID	Mandatory	3fa85f64-5717-4562-b3fc-2c963f66afa6	The UUID of the grant request

Request Query Parameters

Not Applicable

Request Form Data Parameters

Not Applicable

Response (Sample)

{
    "business": {
        "owners": [
            {
                "owner_type": 1,
                "business_name": null,
                "first_name": "Carol",
                "last_name": "carolson",
                "business_type": 1,
                "ownership_percentage": "100.00",
                "tin": "564565457",
                "tin_type": 1,
                "address_line_1": "1600 Pennsylvania Ave NW",
                "address_line_2": "",
                "city": "Washington",
                "state": "DC",
                "zip_code": "20500",
                "zip_code_plus4": "0005",
                "position": "positiontest",
                "veteran_status": "X",
                "gender": "X",
                "ethnicity": "X",
                "race": [
                    "X"
                ]
            }
        ],
        "franchise_code": "S0910",
        "business_type": 4,
        "tax_form_used": 2,
        "restaurant_type": [
            14
        ],
        "dba_tradename": "",
        "legal_name": null,
        "first_name": "Carol",
        "last_name": "CarolSon",
        "address_line_1": "1600 Pennsylvania Ave NW",
        "address_line_2": "Null",
        "city": "Washington",
        "state": "DC",
        "zip_code": "20500",
        "zip_code_plus4": "0005",
        "tin": "261999204",
        "tin_type": 1,
        "phone_number": "2055551111",
        "is_franchise": true
    },
    "user": {
        "username": "test172314"
    },
    "status": "E-Signature Pending",
    "gross_receipts_validated": true,
    "grant_calculation_method": 2,
	"additional_ppp": [
        {
            "loan_number": 3928101802,
            "loan_amount": "1300.00"
        }
    ],
    "slug": "46080f11-a4ca-44ec-b96f-ed61d35d8829",
    "submission_confirmation_id": "a4ca00087290",
    "applicant_received_shuttered_venues_grant": false,
    "applicant_operates_over_20_locations": false,
    "applicant_filed_bankruptcy": 1,
    "applicant_owned_by_gov_entity": false,
    "applicant_business_permanently_closed": false,
    "applicant_has_affiliated_businesses": false,
    "number_of_affiliated_businesses": null,
    "affiliated_businesses_details": null,
    "priority_group_women_owned": false,
    "priority_group_veteran": false,
    "priority_group_socio_economic": false,
    "gross_receipts_signature_date": "100.00",
    "grant_purpose_payroll": true,
    "grant_purpose_rent": false,
    "grant_purpose_utility": false,
    "grant_purpose_debt": false,
    "grant_purpose_construction_outdoor_seating": false,
    "grant_purpose_supplies": false,
    "grant_purpose_food": false,
    "grant_purpose_operations": false,
    "grant_purpose_covered_supplier": false,
    "calc_method": 2,
    "months_in_operation": "11.0",
    "number_of_locations": 1,
    "grant_amount": "5909.09",
    "eligible_expenses": "2000.00",
    "ppp_first_draw_sba_loan_number": null,
    "ppp_first_draw_loan_amount": null,
    "ppp_second_draw_sba_loan_number": null,
    "ppp_second_draw_loan_amount": null,
    "signer_first_name": "carol",
    "signer_last_name": "carolson",
    "signer_phone_number": "2055551111",
    "signer_title": 1,
    "signer_email": "test@test.com",
    "signer_tin": "123456789",
    "signer_address_line_1": "1600 Pennsylvania Ave",
    "signer_address_line_2": "null",
    "signer_city": "Washington",
    "signer_state": "DC",
    "signer_zip_code": "20052",
    "signer_date_of_birth": "2000-01-01",
    "sba_number": null,
    "validation_errors": null,
    "created_at": "2021-04-13T13:35:25.358257Z",
    "submission_date": null,
    "sba_decision": null,
    "sba_decision_date": null,
    "final_payment_date": null,
    "final_payment_confirmed_date": null
}

Response Parameters

HTTP Response Code: 200

Parameter Name	Data Type	Sample Value	Description
business	`JSON Object`
owners	`JSON Array`
business_type	number	2	Business type of owner
tin_type	number	0	Depicts whether TIN of the owner is SSN or EIN or ITIN. EIN=0, SSN=1, ITIN=4
tin	String	252751625	TIN of the owner (EIN or SSN)
owner_type	Number	1	Owner type for the Business. Valid values are 1 or 2 (1 for PERSON and 2 for BUSINESS)
business_name	String	Null	Business Owner name. It will be null if owner is a Person
first_name	String	James	Owner’s first name
last_name	String	Marshall	Owner’s last name
ownership_percentage	String	25.00	% Ownership of the owner.
address_line_1	String	123 Second St	Address Line 1 of the owner
address_line_2	String		Address Line 2 of owner
city	String	Manhattan	City of owner’s address
state	String	NY	State code of owner’s address
zip_code	String	10004	Zip code of owner’s address
zip_code_plus4	String	1234	Zip + 4 of owner’s address
position	String	Director	Position of owner based on demographic information provided as part of grant application
veteran_status	String	1	Veteran status of owner based on information provided as part of grant application (1=Non-Veteran; 2=Veteran; 3=Service-Disabled Veteran;4=Spouse of Veteran; X=Not Disclosed)
gender	String	M	Gender of the owner based on information provided as part of grant application (M=Male; F=Female; X=Not Disclosed)
ethnicity	String	N	Ethnicity of the owner based on information provided as part of grant application (H=Hispanic or Latino; N=Not Hispanic or Latino; X=Not Disclosed)
race	Array	1	Race of the owner based on information provided as part of grant application, multiple values allowed (1=American Indian or Alaska Native; 2=Asian; 3=Black or African-American; 4=Native Hawaiian or Pacific Islander; 5=White; X=Not Disclosed)
business_type	number	1	Business type
dba_tradename	String	ABC Corp	Doing Business As/Trade name for Business
legal_name	String	ABC Corp	Borrower Name
first_name	String	James	first name - Borrower
last_name	String	Marshall	last name - Borrower
address_line_1	String	5050 Ritter Rd	Address Line 1 of Borrower
address_line_2	String	Suite B	Address Line 2 of Borrower
city	String	Mechanicsburg	City of Borrower
state	String	PA	State code of Borrower
zip_code	String	17055	Zip code of Borrower
zip_code_plus4	String	1234	Zip + 4 of the Borrower
tin	String	435-88-1068	TIN of the Borrower (EIN/SSN/ITIN)
tin_type	number	1	TIN Type of the Borrower (EIN=0, SSN=1, ITIN=4)
phone_number	Number	5482562187	Business phone number
username	String	test312	Username of the SBA portal.
is_franchise	Boolean	true	Is Busienss a Franchise listed ?
is_sba_listed_franchise	boolean	true	Whether Franchise is listed with SBA
franchise_code	String	S2956	SBA Franchise Identifier Code
status	String	Application in Progress	Status of Grant Request. Valid values are Status of Grant Request. Valid values are Application in Progress, Esignature Pending , Submitted, Under Review, IRS Review, Not Approved, Approved, Applicant Additional Info Needed, Payment Sent, Payment Confirmed, Payment exception, Applicant correction
created_at	string	2021-01-18T18:39:49.768882Z	Timestamp with timezone (in UTC) at which grant request was created in SBA system
slug	String	9c00737c-7aa5-4741-93bb-7e4f3e5213de	Slug/Unique ID of grant application. This slug id should be used for grant status or withdrawal
submission_confirmation_id	string	57e000079120	unique submission confirmation id of the grant request submitted
applicant_owned_by_gov_entity	boolean	true	Whether the Applicant’s business, is a state or local government-operated business. If true, the Applicant is not eligible
applicant_operates_over_20_locations	boolean	true	As of March 13, 2020, owns or operates (together with any affiliated business) more than 20 locations, regardless of whether those locations do business under the same or multiple names.
applicant_received_shuttered_venues_grant	boolean	true	Has a pending application for or has received a Shuttered Venue Operators Grant
applicant_publicly_traded	boolean	true	Is a publicly-traded company (defined as an entity that is majority owned or controlled by an entity that is an issuer, the securities of which are listed on a national securities exchange)
applicant_business_permanently_closed	boolean	true	Is the Applicant’s business permanently closed
applicant_filed_bankruptcy	number	1	No = 1, Yes, approved plan = 4, Yes, no plan = 3, Yes, chapter 7/perm closed = 2
applicant_suspended_or_debarred	boolean	false	Is the Applicant or any owner of the Applicant presently suspended, debarred, proposed for debarment, declared ineligible, voluntarily excluded from participation in this transaction by any Federal department or agency
ppp_first_draw_sba_loan_number	number	123456789	Did the Applicant receive a Paycheck Protection Plan (PPP) loan (First Draw PPP Loan) at any time in 2020 or 2021, if yes, what’s the sba number
ppp_first_draw_loan_amount	number	50000.00	First draw sba loan amount
ppp_second_draw_sba_loan_number	number	123456789	Did the Applicant receive a second-round Paycheck Protection Plan (PPP) loan (Second Draw PPP Loan) in 2021? If yes, what’s the sba number
ppp_second_draw_loan_amount	number	1000.00	Second draw loan amount
applicant_has_affiliated_businesses	boolean	true	Does the Applicant have affiliates?
number_of_affiliated_businesses	number	2	If yes, how many affiliates does the Applicant have
affiliated_businesses_details	string	abc, def	Please list each affiliate’s legal business name
date_of_first_sale	string	2018-01-01	What date did you begin making sales? YYYY-MM-DD
months_in_operation	number	2.5	For Applicants that began operations partially through 2019
number_of_locations	number	1	Enter the number of locations operated by the Applicant
gross_receipts_2019	number	70000.00	Enter 2019 gross receipts as reported on your 2019 Federal tax return. line item 1 in table 1 or Line item 1a in table 2
gross_receipts_2020	number	50000.00	Enter 2020 gross receipts as reported or to be reported on your 2020 Federal tax return. line item 2 in table 1 and table 2
gross_receipts_signature_date	number	50000.00	Enter all gross receipts as of application signature date. Line item 2 in table 3
eligible_expenses	string	100000.00	Enter the amount you spent on eligible expenses. Eligible expenses have the same definition as eligible uses of funds. Line item 1 in table 3
grant_purpose_payroll	boolean	true	Business Payroll Costs, including paid sick leave
grant_purpose_rent	boolean	true	Business Rent / Business Mortgage
grant_purpose_utility	boolean	true	Business Utilities
grant_purpose_debt	boolean	true	Business Debt Service
grant_purpose_maintenance	boolean	true
grant_purpose_supplies	boolean	true	Business Supplies
grant_purpose_food	boolean	true	Business Food and beverage expenses, including raw materials
grant_purpose_operations	boolean	true	Business Operating Expenses
grant_purpose_covered_supplier	boolean	true	Covered Supplier Costs
grant_purpose_construction_outdoor_seating	boolean	true	Covered Outdoor seating
grant_amount	string	700000.00	Calculated grant amount
priority_group_women_owned	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by One or more women
priority_group_veteran	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by Veteran(s)
priority_group_socio_economic	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by Socially and economically disadvantaged individual(s)
signer_first_name	string	first	First name of signer
signer_last_name	boolean	last	Last name of signer
signer_phone_number	boolean	3010001100	Phone number of signer
signer_address_line_1	string	1305 ABC Lane	Address Line 1 of signer
signer_address_line_2	string	XYZ	Address Line 2 of signer
signer_city	string	Washington	City of signer
signer_state	string	DC	state code of signer
signer_zip_code	string	20052	zip code of signer
signer_title	number	1	Please refer to mapping in design consideration for mapping of title to Business. Here are valid values: PRESIDENT = 1, SECRETARY = 2, TREASURER = 3, VICE_PRESIDENT = 4, ASSISTANT_TREASURER = 5, CHIEF_ACCOUNTING_OFFICER = 6, CONTROLLER = 7, HAREHOLDER = 8, PARTNER = 9, LIMITED_PARTNER = 10, OWNER = 11, SOLE_PROPRIETOR_TITLE = 12, MANAGING_MEMBER = 13
signer_email	string	test@test.com	email address of signer
signer_date_of_birth	string	2000-01-01	Date of birth of signer
signer_tin	string		280110010	TIN of the signer
bank_account	array	true	Bank account details
routing_number	string	123456789	Routing number of funding account
account_number	string	987654321	Account number of funding account
account_type	string	checking	account type of funding account
submission_date	string	2000-01-01	Submission date of application
sba_decision	string	approved	Decision of application (approved or not approved)
sba_decision_date	string	null	Decision date of application
final_payment_date	string	null	Date on which payment was initiated
final_payment_confirmed_date	string	null	Date on which payment was confirmed
gross_receipts_validated	boolean	true	Whether gross receipts are validated by ecosystem partner or not (true or false)
grant_calculation_method	number	1	Grant calculation method used, (1, ‘Calculation Method 1 - Began Operations on or prior to Jan 1, 2019’),(2, ‘Calculation Method 2 - Began Operations partially through 2019’),(3, ‘Calculation Method 3 - Began Operations on or after Jan 1, 2020’),(4, ‘Advanced - Combination of Methods 1-3’)
additional_ppp	`JSON Object`	Optional
loan_number	number	optional	123456789	Other PPP Loan numbers
loan_amount	number	optional	1000.00	Other PPP Loan amount
validation_error	string	null	Validation errors from etran or asynch address validation

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 grant request is not found

HTTP Response Code: 429

API Call Rate Limits
To maintain reliability and stability within our environments, grant 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 grant request. Client may choose to use this API in case they would like to get the latest details of a particular grant request.

5. Get grant Request Details using username and submission confirmation id

This API is used for getting details of existing grant requests using username and submission confirmation id

Request type: HTTPS

API Endpoint:

GET api/user//grants/?submission_confirmation_id=NNNNNNNNNN

Request (Sample)

/api/user/test/grants/?submission_confirmation_id=382500074651

Request Parameters

Not Applicable (No request body)

Request Path Parameters

Path Parameter Name	Data Type	Mandatory/Optional	Sample Value	Description
username	string	Mandatory	nbhatia	user name of the restaurant owner, this comes in response of create Grant API request

Request Query Parameters

Query Parameter Name	Data Type	Mandatory/Optional	Sample Value	Description
submission_confirmation_id	string	Mandatory	876tghu876	Submission confirmation id assigned to Grant

Request Form Data Parameters

Not Applicable

Response (Sample)

{
    "business": {
        "owners": [
            {
                "owner_type": 1,
                "business_name": null,
                "first_name": "Carol",
                "last_name": "carolson",
                "business_type": 1,
                "ownership_percentage": "100.00",
                "tin": "564565457",
                "tin_type": 1,
                "address_line_1": "1600 Pennsylvania Ave NW",
                "address_line_2": "",
                "city": "Washington",
                "state": "DC",
                "zip_code": "20500",
                "zip_code_plus4": "0005",
                "position": "positiontest",
                "veteran_status": "X",
                "gender": "X",
                "ethnicity": "X",
                "race": [
                    "X"
                ]
            }
        ],
        "franchise_code": "S0910",
        "business_type": 4,
        "tax_form_used": 2,
        "restaurant_type": [
            14
        ],
        "dba_tradename": "",
        "legal_name": null,
        "first_name": "Carol",
        "last_name": "CarolSon",
        "address_line_1": "1600 Pennsylvania Ave NW",
        "address_line_2": "Null",
        "city": "Washington",
        "state": "DC",
        "zip_code": "20500",
        "zip_code_plus4": "0005",
        "tin": "261999204",
        "tin_type": 1,
        "phone_number": "2055551111",
        "is_franchise": true
    },
    "user": {
        "username": "test172314"
    },
    "status": "E-Signature Pending",
    "gross_receipts_validated": true,
    "grant_calculation_method": 2,
	"additional_ppp": [
        {
            "loan_number": 3928101802,
            "loan_amount": "1300.00"
        }
    ],
    "slug": "46080f11-a4ca-44ec-b96f-ed61d35d8829",
    "submission_confirmation_id": "a4ca00087290",
    "applicant_received_shuttered_venues_grant": false,
    "applicant_operates_over_20_locations": false,
    "applicant_filed_bankruptcy": 1,
    "applicant_owned_by_gov_entity": false,
    "applicant_business_permanently_closed": false,
    "applicant_has_affiliated_businesses": false,
    "number_of_affiliated_businesses": null,
    "affiliated_businesses_details": null,
    "priority_group_women_owned": false,
    "priority_group_veteran": false,
    "priority_group_socio_economic": false,
    "gross_receipts_signature_date": "100.00",
    "grant_purpose_payroll": true,
    "grant_purpose_rent": false,
    "grant_purpose_utility": false,
    "grant_purpose_debt": false,
    "grant_purpose_construction_outdoor_seating": false,
    "grant_purpose_supplies": false,
    "grant_purpose_food": false,
    "grant_purpose_operations": false,
    "grant_purpose_covered_supplier": false,
    "calc_method": 2,
    "months_in_operation": "11.0",
    "number_of_locations": 1,
    "grant_amount": "5909.09",
    "eligible_expenses": "2000.00",
    "ppp_first_draw_sba_loan_number": null,
    "ppp_first_draw_loan_amount": null,
    "ppp_second_draw_sba_loan_number": null,
    "ppp_second_draw_loan_amount": null,
    "signer_first_name": "carol",
    "signer_last_name": "carolson",
    "signer_phone_number": "2055551111",
    "signer_title": 1,
    "signer_email": "test@test.com",
    "signer_tin": "123456789",
    "signer_address_line_1": "1600 Pennsylvania Ave",
    "signer_address_line_2": "null",
    "signer_city": "Washington",
    "signer_state": "DC",
    "signer_zip_code": "20052",
    "signer_date_of_birth": "2000-01-01",
    "sba_number": null,
    "validation_errors": null,
    "created_at": "2021-04-13T13:35:25.358257Z",
    "submission_date": null,
    "sba_decision": null,
    "sba_decision_date": null,
    "final_payment_date": null,
    "final_payment_confirmed_date": null
}

Response Parameters

HTTP Response Code: 200

Parameter Name	Data Type	Sample Value	Description
business	`JSON Object`
owners	`JSON Array`
business_type	number	2	Business type of owner
tin_type	number	0	Depicts whether TIN of the owner is SSN or EIN or ITIN. EIN=0, SSN=1, ITIN=4
tin	String	252-75-1625	TIN of the owner (EIN or SSN)
owner_type	Number	1	Owner type for the Business. Valid values are 1 or 2 (1 for PERSON and 2 for BUSINESS)
business_name	String	Null	Business Owner name. It will be null if owner is a Person
first_name	String	James	Owner’s first name
last_name	String	Marshall	Owner’s last name
ownership_percentage	Number	25.0	% Ownership of the owner.
address_line_1	String	123 Second St	Address Line 1 of the owner
address_line_2	String		Address Line 2 of owner
city	String	Manhattan	City of owner’s address
state	String	NY	State code of owner’s address
zip_code	String	10004	Zip code of owner’s address
zip_code_plus4	String	1234	Zip + 4 of owner’s address
position	String	Director	Position of owner based on demographic information provided as part of grant application
veteran_status	String	1	Veteran status of owner based on information provided as part of grant application (1=Non-Veteran; 2=Veteran; 3=Service-Disabled Veteran;4=Spouse of Veteran; X=Not Disclosed)
gender	String	M	Gender of the owner based on information provided as part of grant application (M=Male; F=Female; X=Not Disclosed)
ethnicity	String	N	Ethnicity of the owner based on information provided as part of grant application (H=Hispanic or Latino; N=Not Hispanic or Latino; X=Not Disclosed)
race	Array	1	Race of the owner based on information provided as part of grant application, multiple values allowed (1=American Indian or Alaska Native; 2=Asian; 3=Black or African-American; 4=Native Hawaiian or Pacific Islander; 5=White; X=Not Disclosed)
business_type	number	1	Business type.
dba_tradename	String	ABC Corp	Doing Business As/Trade name for Business
legal_name	String	ABC Corp	Borrower Name
first_name	String	James	first name - Borrower
last_name	String	Marshall	last name - Borrower
address_line_1	String	5050 Ritter Rd	Address Line 1 of Borrower
address_line_2	String	Suite B	Address Line 2 of Borrower
city	String	Mechanicsburg	City of Borrower
state	String	PA	State code of Borrower
zip_code	String	17055	Zip code of Borrower
zip_code_plus4	String	1234	Zip + 4 of the Borrower
tin	String	435-88-1068	TIN of the Borrower (EIN/SSN/ITIN)
tin_type	number	1	TIN Type of the Borrower (EIN=0, SSN=1, ITIN=4)
phone_number	Number	5482562187	Business phone number
username	String	test312	Username of the SBA portal.
is_franchise	Boolean	true	Is Busienss a Franchise listed ?
is_sba_listed_franchise	boolean	true	Whether Franchise is listed with SBA
franchise_code	String	S2956	SBA Franchise Identifier Code
status	String	Application in Progress	Status of PPP grant Request. Valid values are Status of Grant Request. Valid values are Application in Progress, Esignature Pending , Submitted, Under Review, IRS Review, Not Approved, Approved, Applicant Additional Info Needed, Payment Sent, Payment Confirmed, Payment exception, Applicant correction
created_at	string	2021-01-18T18:39:49.768882Z	Timestamp with timezone (in UTC) at which grant request was created in SBA system
slug	String	9c00737c-7aa5-4741-93bb-7e4f3e5213de	Slug/Unique ID of grant application. This slug id should be used for grant status or withdrawal
applicant_owned_by_gov_entity	boolean	true	Whether the Applicant’s business, is a state or local government-operated business. If true, the Applicant is not eligible
applicant_operates_over_20_locations	boolean	true	As of March 13, 2020, owns or operates (together with any affiliated business) more than 20 locations, regardless of whether those locations do business under the same or multiple names.
applicant_received_shuttered_venues_grant	boolean	true	Has a pending application for or has received a Shuttered Venue Operators Grant
applicant_publicly_traded	boolean	true	Is a publicly-traded company (defined as an entity that is majority owned or controlled by an entity that is an issuer, the securities of which are listed on a national securities exchange)
applicant_business_permanently_closed	boolean	true	Is the Applicant’s business permanently closed
applicant_filed_bankruptcy	number	1	No = 1, Yes, approved plan = 4, Yes, no plan = 3, Yes, chapter 7/perm closed = 2
applicant_suspended_or_debarred	boolean	false	Is the Applicant or any owner of the Applicant presently suspended, debarred, proposed for debarment, declared ineligible, voluntarily excluded from participation in this transaction by any Federal department or agency
ppp_first_draw_sba_loan_number	number	123456789	Did the Applicant receive a Paycheck Protection Plan (PPP) loan (First Draw PPP Loan) at any time in 2020 or 2021, if yes, what’s the sba number
ppp_first_draw_loan_amount	number	50000.00	First draw sba loan amount
ppp_second_draw_sba_loan_number	number	123456789	Did the Applicant receive a second-round Paycheck Protection Plan (PPP) loan (Second Draw PPP Loan) in 2021? If yes, what’s the sba number
ppp_second_draw_loan_amount	number	1000.00	Second draw loan amount
applicant_has_affiliated_businesses	boolean	true	Does the Applicant have affiliates?
number_of_affiliated_businesses	number	2	If yes, how many affiliates does the Applicant have
affiliated_businesses_details	string	abc, def	Please list each affiliate’s legal business name
date_of_first_sale	date	2018-01-01	What date did you begin making sales? (Month, Day, Year or null
months_in_operation	number	2.5	For Applicants that began operations partially through 2019
number_of_locations	number	1	Enter the number of locations operated by the Applicant
gross_receipts_2019	number	70000.00	Enter 2019 gross receipts as reported on your 2019 Federal tax return. line item 1 in table 1 or Line item 1a in table 2
gross_receipts_2020	number	50000.00	Enter 2020 gross receipts as reported or to be reported on your 2020 Federal tax return. line item 2 in table 1 and table 2
gross_receipts_signature_date	number	50000.00	Enter all gross receipts as of application signature date. Line item 2 in table 3
eligible_expenses	number	100000.00	Enter the amount you spent on eligible expenses. Eligible expenses have the same definition as eligible uses of funds. Line item 1 in table 3
grant_purpose_payroll	boolean	true	Business Payroll Costs, including paid sick leave
grant_purpose_rent	boolean	true	Business Rent / Business Mortgage
grant_purpose_utility	boolean	true	Business Utilities
grant_purpose_debt	boolean	true	Business Debt Service
grant_purpose_maintenance	boolean	true
grant_purpose_supplies	boolean	true	Business Supplies
grant_purpose_food	boolean	true	Business Food and beverage expenses, including raw materials
grant_purpose_operations	boolean	true	Business Operating Expenses
grant_purpose_covered_supplier	boolean	true	Covered Supplier Costs
grant_purpose_construction_outdoor_seating	boolean	true	Covered Outdoor seating
grant_amount	number	700000.00	Calculated grant amount
priority_group_women_owned	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by One or more women
priority_group_veteran	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by Veteran(s)
priority_group_socio_economic	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by Socially and economically disadvantaged individual(s)
signer_first_name	string	first	First name of signer
signer_last_name	boolean	last	Last name of signer
signer_phone_number	boolean	3010001100	Phone number of signer
signer_address_line_1	string	1305 ABC Lane	Address Line 1 of signer
signer_address_line_2	string	XYZ	Address Line 2 of signer
signer_city	string	Washington	City of signer
signer_state	string	DC	state code of signer
signer_zip_code	string	20052	zip code of signer
signer_title	number	1	Please refer to mapping in design consideration for mapping of title to Business. Here are valid values: PRESIDENT = 1, SECRETARY = 2, TREASURER = 3, VICE_PRESIDENT = 4, ASSISTANT_TREASURER = 5, CHIEF_ACCOUNTING_OFFICER = 6, CONTROLLER = 7, HAREHOLDER = 8, PARTNER = 9, LIMITED_PARTNER = 10, OWNER = 11, SOLE_PROPRIETOR_TITLE = 12, MANAGING_MEMBER = 13
signer_email	string	test@test.com	email address of signer
signer_date_of_birth	date	“2000-01-01”	Date of birth of signer
bank_account	array	true	Bank account details
routing_number	string	123456789	Routing number of funding account
account_number	string	987654321	Account number of funding account
account_type	string	checking	account type of funding account
submission_date	date	“2000-01-01”	Submission date of application
sba_decision	string	approved	Decision of application
sba_decision_date	date	“2000-01-01”	Decision date of application
final_payment_date	date	“2021-06-01”	Date on which payment was initiated
final_payment_confirmed_date	date	“2021-06-04”	Date on which payment was confirmed
additional_ppp	`JSON Object`	Optional
loan_number	number	optional	123456789	Other PPP Loan numbers
loan_amount	number	optional	1000.00	Other PPP Loan amount
validation_error	string	null	Validation errors from etran or asynch address validation

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 grant request is not found

HTTP Response Code: 429

API Call Rate Limits
To maintain reliability and stability within our environments, grant 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 grant request. Client may choose to use this API in case they would like to get the latest details of a particular grant request.

6. Get grant Request Details using tin and tin type

This API is used for getting details of existing grant requests using username and submission confirmation id

Request type: HTTPS

API Endpoint:

GET /api/grants/?tin=NNNNNNNNNNN&tin_type=N

Request (Sample)

/api/grants/?tin=123333322&tin_type=0

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
tin	number	Mandatory	123456789	TIN number of the Business which submitted Grant application
tin_type	number	Mandatory	0	tin type of business, 0 is EIN, 1 is SSN and 4 is TIN

Request Form Data Parameters

Not Applicable

Response (Sample)

{
    "business": {
        "owners": [
            {
                "owner_type": 1,
                "business_name": null,
                "first_name": "Carol",
                "last_name": "carolson",
                "business_type": 1,
                "ownership_percentage": "100.00",
                "tin": "564565457",
                "tin_type": 1,
                "address_line_1": "1600 Pennsylvania Ave NW",
                "address_line_2": "",
                "city": "Washington",
                "state": "DC",
                "zip_code": "20500",
                "zip_code_plus4": "0005",
                "position": "positiontest",
                "veteran_status": "X",
                "gender": "X",
                "ethnicity": "X",
                "race": [
                    "X"
                ]
            }
        ],
        "franchise_code": "S0910",
        "business_type": 4,
        "tax_form_used": 2,
        "restaurant_type": [
            14
        ],
        "dba_tradename": "",
        "legal_name": null,
        "first_name": "Carol",
        "last_name": "CarolSon",
        "address_line_1": "1600 Pennsylvania Ave NW",
        "address_line_2": "Null",
        "city": "Washington",
        "state": "DC",
        "zip_code": "20500",
        "zip_code_plus4": "0005",
        "tin": "261999204",
        "tin_type": 1,
        "phone_number": "2055551111",
        "is_franchise": true
    },
    "user": {
        "username": "test172314"
    },
    "status": "E-Signature Pending",
    "gross_receipts_validated": true,
    "grant_calculation_method": 2,
	"additional_ppp": [
        {
            "loan_number": 3928101802,
            "loan_amount": "1300.00"
        }
    ],
    "slug": "46080f11-a4ca-44ec-b96f-ed61d35d8829",
    "submission_confirmation_id": "a4ca00087290",
    "applicant_received_shuttered_venues_grant": false,
    "applicant_operates_over_20_locations": false,
    "applicant_filed_bankruptcy": 1,
    "applicant_owned_by_gov_entity": false,
    "applicant_business_permanently_closed": false,
    "applicant_has_affiliated_businesses": false,
    "number_of_affiliated_businesses": null,
    "affiliated_businesses_details": null,
    "priority_group_women_owned": false,
    "priority_group_veteran": false,
    "priority_group_socio_economic": false,
    "gross_receipts_signature_date": "100.00",
    "grant_purpose_payroll": true,
    "grant_purpose_rent": false,
    "grant_purpose_utility": false,
    "grant_purpose_debt": false,
    "grant_purpose_construction_outdoor_seating": false,
    "grant_purpose_supplies": false,
    "grant_purpose_food": false,
    "grant_purpose_operations": false,
    "grant_purpose_covered_supplier": false,
    "calc_method": 2,
    "months_in_operation": "11.0",
    "number_of_locations": 1,
    "grant_amount": "5909.09",
    "eligible_expenses": "2000.00",
    "ppp_first_draw_sba_loan_number": null,
    "ppp_first_draw_loan_amount": null,
    "ppp_second_draw_sba_loan_number": null,
    "ppp_second_draw_loan_amount": null,
    "signer_first_name": "carol",
    "signer_last_name": "carolson",
    "signer_phone_number": "2055551111",
    "signer_title": 1,
    "signer_email": "test@test.com",
    "signer_tin": "123456789",
    "signer_address_line_1": "1600 Pennsylvania Ave",
    "signer_address_line_2": "null",
    "signer_city": "Washington",
    "signer_state": "DC",
    "signer_zip_code": "20052",
    "signer_date_of_birth": "2000-01-01",
    "sba_number": null,
    "validation_errors": null,
    "created_at": "2021-04-13T13:35:25.358257Z",
    "submission_date": null,
    "sba_decision": null,
    "sba_decision_date": null,
    "final_payment_date": null,
    "final_payment_confirmed_date": null
}

Response Parameters

HTTP Response Code: 200

Parameter Name	Data Type	Sample Value	Description
business	`JSON Object`
owners	`JSON Array`
business_type	number	2	Business type of owner
tin_type	number	0	Depicts whether TIN of the owner is SSN or EIN or ITIN. EIN=0, SSN=1, ITIN=4
tin	String	252-75-1625	TIN of the owner (EIN or SSN)
owner_type	Number	1	Owner type for the Business. Valid values are 1 or 2 (1 for PERSON and 2 for BUSINESS)
business_name	String	Null	Business Owner name. It will be null if owner is a Person
first_name	String	James	Owner’s first name
last_name	String	Marshall	Owner’s last name
ownership_percentage	Number	25.0	% Ownership of the owner.
address_line_1	String	123 Second St	Address Line 1 of the owner
address_line_2	String		Address Line 2 of owner
city	String	Manhattan	City of owner’s address
state	String	NY	State code of owner’s address
zip_code	String	10004	Zip code of owner’s address
zip_code_plus4	String	1234	Zip + 4 of owner’s address
position	String	Director	Position of owner based on demographic information provided as part of grant application
veteran_status	String	1	Veteran status of owner based on information provided as part of grant application (1=Non-Veteran; 2=Veteran; 3=Service-Disabled Veteran;4=Spouse of Veteran; X=Not Disclosed)
gender	String	M	Gender of the owner based on information provided as part of grant application (M=Male; F=Female; X=Not Disclosed)
ethnicity	String	N	Ethnicity of the owner based on information provided as part of grant application (H=Hispanic or Latino; N=Not Hispanic or Latino; X=Not Disclosed)
race	Array	1	Race of the owner based on information provided as part of grant application, multiple values allowed (1=American Indian or Alaska Native; 2=Asian; 3=Black or African-American; 4=Native Hawaiian or Pacific Islander; 5=White; X=Not Disclosed)
business_type	number	1	Business type.
dba_tradename	String	ABC Corp	Doing Business As/Trade name for Business
legal_name	String	ABC Corp	Borrower Name
first_name	String	James	first name - Borrower
last_name	String	Marshall	last name - Borrower
address_line_1	String	5050 Ritter Rd	Address Line 1 of Borrower
address_line_2	String	Suite B	Address Line 2 of Borrower
city	String	Mechanicsburg	City of Borrower
state	String	PA	State code of Borrower
zip_code	String	17055	Zip code of Borrower
zip_code_plus4	String	1234	Zip + 4 of the Borrower
tin	String	435-88-1068	TIN of the Borrower (EIN/SSN/ITIN)
tin_type	number	1	TIN Type of the Borrower (EIN=0, SSN=1, ITIN=4)
phone_number	Number	5482562187	Business phone number
username	String	test312	Username of the SBA portal.
is_franchise	Boolean	true	Is Busienss a Franchise listed ?
is_sba_listed_franchise	boolean	true	Whether Franchise is listed with SBA
franchise_code	String	S2956	SBA Franchise Identifier Code
status	String	Application in Progress	Status of PPP grant Request. Valid values are Status of Grant Request. Valid values are Application in Progress, Esignature Pending , Submitted, Under Review, IRS Review, Not Approved, Approved, Applicant Additional Info Needed, Payment Sent, Payment Confirmed, Payment exception, Applicant correction
created_at	string	2021-01-18T18:39:49.768882Z	Timestamp with timezone (in UTC) at which grant request was created in SBA system
slug	String	9c00737c-7aa5-4741-93bb-7e4f3e5213de	Slug/Unique ID of grant application. This slug id should be used for grant status or withdrawal
applicant_owned_by_gov_entity	boolean	true	Whether the Applicant’s business, is a state or local government-operated business. If true, the Applicant is not eligible
applicant_operates_over_20_locations	boolean	true	As of March 13, 2020, owns or operates (together with any affiliated business) more than 20 locations, regardless of whether those locations do business under the same or multiple names.
applicant_received_shuttered_venues_grant	boolean	true	Has a pending application for or has received a Shuttered Venue Operators Grant
applicant_publicly_traded	boolean	true	Is a publicly-traded company (defined as an entity that is majority owned or controlled by an entity that is an issuer, the securities of which are listed on a national securities exchange)
applicant_business_permanently_closed	boolean	true	Is the Applicant’s business permanently closed
applicant_filed_bankruptcy	number	1	No = 1, Yes, approved plan = 4, Yes, no plan = 3, Yes, chapter 7/perm closed = 2
applicant_suspended_or_debarred	boolean	false	Is the Applicant or any owner of the Applicant presently suspended, debarred, proposed for debarment, declared ineligible, voluntarily excluded from participation in this transaction by any Federal department or agency
ppp_first_draw_sba_loan_number	number	123456789	Did the Applicant receive a Paycheck Protection Plan (PPP) loan (First Draw PPP Loan) at any time in 2020 or 2021, if yes, what’s the sba number
ppp_first_draw_loan_amount	number	50000.00	First draw sba loan amount
ppp_second_draw_sba_loan_number	number	123456789	Did the Applicant receive a second-round Paycheck Protection Plan (PPP) loan (Second Draw PPP Loan) in 2021? If yes, what’s the sba number
ppp_second_draw_loan_amount	number	1000.00	Second draw loan amount
applicant_has_affiliated_businesses	boolean	true	Does the Applicant have affiliates?
number_of_affiliated_businesses	number	2	If yes, how many affiliates does the Applicant have
affiliated_businesses_details	string	abc, def	Please list each affiliate’s legal business name
date_of_first_sale	date	2018-01-01	What date did you begin making sales? (Month, Day, Year or null
months_in_operation	number	2.5	For Applicants that began operations partially through 2019
number_of_locations	number	1	Enter the number of locations operated by the Applicant
gross_receipts_2019	number	70000.00	Enter 2019 gross receipts as reported on your 2019 Federal tax return. line item 1 in table 1 or Line item 1a in table 2
gross_receipts_2020	number	50000.00	Enter 2020 gross receipts as reported or to be reported on your 2020 Federal tax return. line item 2 in table 1 and table 2
gross_receipts_signature_date	number	50000.00	Enter all gross receipts as of application signature date. Line item 2 in table 3
eligible_expenses	number	100000.00	Enter the amount you spent on eligible expenses. Eligible expenses have the same definition as eligible uses of funds. Line item 1 in table 3
grant_purpose_payroll	boolean	true	Business Payroll Costs, including paid sick leave
grant_purpose_rent	boolean	true	Business Rent / Business Mortgage
grant_purpose_utility	boolean	true	Business Utilities
grant_purpose_debt	boolean	true	Business Debt Service
grant_purpose_maintenance	boolean	true
grant_purpose_supplies	boolean	true	Business Supplies
grant_purpose_food	boolean	true	Business Food and beverage expenses, including raw materials
grant_purpose_operations	boolean	true	Business Operating Expenses
grant_purpose_covered_supplier	boolean	true	Covered Supplier Costs
grant_purpose_construction_outdoor_seating	boolean	true	Covered Outdoor seating
grant_amount	number	700000.00	Calculated grant amount
priority_group_women_owned	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by One or more women
priority_group_veteran	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by Veteran(s)
priority_group_socio_economic	boolean	true	Applicant is a small business concern at least 51 percent owned and controlled by Socially and economically disadvantaged individual(s)
signer_first_name	string	first	First name of signer
signer_last_name	boolean	last	Last name of signer
signer_phone_number	boolean	3010001100	Phone number of signer
signer_address_line_1	string	1305 ABC Lane	Address Line 1 of signer
signer_address_line_2	string	XYZ	Address Line 2 of signer
signer_city	string	Washington	City of signer
signer_state	string	DC	state code of signer
signer_zip_code	string	20052	zip code of signer
signer_title	number	1	Please refer to mapping in design consideration for mapping of title to Business. Here are valid values: PRESIDENT = 1, SECRETARY = 2, TREASURER = 3, VICE_PRESIDENT = 4, ASSISTANT_TREASURER = 5, CHIEF_ACCOUNTING_OFFICER = 6, CONTROLLER = 7, HAREHOLDER = 8, PARTNER = 9, LIMITED_PARTNER = 10, OWNER = 11, SOLE_PROPRIETOR_TITLE = 12, MANAGING_MEMBER = 13
signer_email	string	test@test.com	email address of signer
signer_date_of_birth	date	“2000-01-01”	Date of birth of signer
bank_account	array	true	Bank account details
routing_number	string	123456789	Routing number of funding account
account_number	string	987654321	Account number of funding account
account_type	string	checking	account type of funding account
submission_date	date	“2000-01-01”	Submission date of application
sba_decision	string	approved	Decision of application
sba_decision_date	date	“2000-01-01”	Decision date of application
final_payment_date	date	“2021-06-01”	Date on which payment was initiated
final_payment_confirmed_date	date	“2021-06-04”	Date on which payment was confirmed
additional_ppp	`JSON Object`	Optional
loan_number	number	optional	123456789	Other PPP Loan numbers
loan_amount	number	optional	1000.00	Other PPP Loan amount
validation_error	string	null	Validation errors from etran or asynch address validation

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 grant request is not found

HTTP Response Code: 429

API Call Rate Limits
To maintain reliability and stability within our environments, grant 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 grant request. Client may choose to use this API in case they would like to get the latest details of a particular grant request.

7. Delete grant Request

This API is used for deleting/withdrawing the Grant request

Please note:

Restaurant owners may withdraw Grant Application, if Application has not been approved by SBA and if status of the application permits it be deleted

Request type: HTTPS

API Endpoint:

DELETE /api/user/username/grants/slug/

Request (Sample)

/api/grants/user/test/grants/8492325e-3825-425c-8666-c9f8b28a01d2/

Request Parameters

Not Applicable (No request body)

Request Path Parameters

Path Parameter Name	Data Type	Mandatory/Optional	Sample Value	Description
user	string	Mandatory	user id of the request	The user id provided as part of grant request
slug	UUID	Mandatory	3c00737c-7aa5-4741-93bb-7e4f3e5213de	The UUID/slug id of the grant 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, Grant 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 Grant application. For any reason, if user would like to delete Grant request, try to call this API as soon as possible

7. Validate/Lookup Disbursed PPP Loan

This API provides fully disbursed PPP Loan info (first draw or second draw) based on SBA number as input. API users may use this end point to validate PPP Loan details before submitting grant application.

Request type: HTTPS

API Endpoint:

GET /api/etran_ppp_validation/?sba_number=NNNNNNNNNN

Request (Sample)

/api/etran_ppp_validation/?sba_number=5279100030

Request Parameters

Not Applicable (No request body)

Request Path Parameters

Not Applicable (Mo Request Path Parameters)

Request Query Parameters

sba_number=SBA_Number

Request Form Data Parameters

Not Applicable

Response (Sample)

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "sba_number": 5279100030,
            "etran_notional_amount": 900000.0,
            "etran_busnm": null,
            "address1": "",
            "address2": ""
	    "tin_type": 0
	    "etran_hold_flag_indicator": true
        }
    ]
}

Response Parameters

HTTP Response Code: 200

Parameter Name	Data Type	Sample Value	Description
count	Number	1	The total count of first draw PPP Loan for SBA number.
next	String	null	The URI of the next set of list of PPP Loans to be fetched. It will be null
previous	String	null	The URI of the previous set of PPP Loan to be fetched. It will be null
results	`JSON Array`
sba_number	number	5279100030	Unique ID within SBA system for loan
etran_notional_amount	Number	900000.0	Loan Amount
etran_busnm	String	null	eTran Busniness Name
address1	String	””	Address Line 1 of the Borrower
address2	String	””	Address Line 2 of the Borrower
tin_type	Number	0	TIN Type of Borrower/Business used during First draw - EIN=0, SSN=1, ITIN=4
etran_hold_flag_indicator	boolean	true	Whether first draw loan is on hold by SBA

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 sba number is not found

HTTP Response Code: 429

API Call Rate Limits
To maintain reliability and stability within our environments, PPP 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 the ability to validate the PPP Loan before submitting grant application.

8. Get All grant Documents

This endpoint allows ecosystem partners to get all the documents uploaded for the grant request.These documents include ecosystem partner provided and SBA generated notification letters (if any).

Request type: HTTPS

API Endpoint:

GET /api/grant_documents/

Request (Sample)

/api/grant_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
grant	String	Mandatory	5ae02dd4-a7f7-4c40-90fc-20cba32e8de0	Grant slug id

Request Form Data Parameters

Not Applicable

Response (Sample)

{
	"count": 1,
	"next": null,
	"previous": null,
	"results": [
		{
			"slug": "5ae02dd4-a7f7-4c40-90fc-20cba32e8de0",
			"name": "Revenue.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_grant": "df481fbb-c41f-46f3-b96f-94374d747a8d",
			"document_type": {
				"id": 1,
				"name": "grant Application Supporting Docs (Revenue)",
				"description": "grant Application Supporting Docs (Revenue)"
			}
		}
	]
}

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_grant	String	df481fbb-c41f-46f3-b96f-94374d747a8d	The UUID(Slug) of the grant which came as part of the grant request creation. This ensures the document gets attached to the corresponding grant request
document_type	`JSON Object`
id	Number	1	The id of the document type as defined in SBA System
name	String	grant Application Supporting Docs (Revenue)	The name of the document type
description	String	grant Application Supporting Docs (Revenue)	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, grant 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” When a grant decision goes for SBA review(Lender Additional Info Needed), document id is 34 and document name is “SBA Correspondence - All documents”

9. Get ALL Franchise Details

This API fetches the list of ALL Franchises listed in the SBA’s Franchise Directory

Request type: HTTPS

API Endpoint:

GET /api/franchise/

Request (Sample)

/api/franchise/

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": 1057,
    "next": "https://forgiveness.sba.gov/api/franchise/?page=3",
    "previous": "https://forgiveness.sba.gov/api/franchise/?page=1",
    "results": [
        {
            "id": 4,
            "code": "S0011",
            "description": "123 FIT"
        }
    ]
}

Response Parameters

HTTP Response Code: 200

Parameter Name	Data Type	Sample Value	Description
count	Number	1000	The total count of the Franchise list
next	String	null	The URI of the next set of Franchise list to be fetched. It will be null for last page
previous	String	null	The URI of the previous set of Franchise details to be fetched. It will be null for first page
results	`JSON Array`
id	Number	4	Unique id of Franchise in SBA system
code	String	S0011	Franchise code
description	String	123 FIT	Franchise description

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, PPP 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 list of all Franchises regsitered with SBA. 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

10. Get Franchise Details using Franchise code or name

This API is used for getting details of specific Franchise listed in the SBA’s Franchise Directory

Request type: HTTPS

API Endpoint:

GET /api/franchise/?code=xxxxx
GET /api/franchise/?description=xxxxx

Request (Sample)

/api/franchise/?code=S0011
/api/franchise/?description=subway

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
code	String	Optional	S0011	Franchise code
description	String	Optional	subway	Franchise name

Request Form Data Parameters

Not Applicable

Response (Sample)

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "code": "S3493",
            "description": "abc"
        }
    ]
}

Response Parameters

HTTP Response Code: 200

Parameter Name	Data Type	Sample Value	Description
count	Number	1	The total count of the Franchise list
next	String	null	The URI of the next set of Franchise list to be fetched. It will be null for search by id
previous	String	null	The URI of the previous set of Franchise details to be fetched. It will be null for search by id
id	Number	4	Unique id of Franchise code in SBA system of records
code	String	S0011	Franchise code
description	String	123 FIIT	Franchise description

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 franchise is not found

HTTP Response Code: 429

API Call Rate Limits
To maintain reliability and stability within our environments, PPP 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 Details of a specific Franchise code or name. Client may choose to use this API in case they would like to get the details of a particular Franchise.

11. Get eTran PPP Loan Validation

This API provides fully approved PPP Loan (first draw or second draw and disbursed or not disbursed) based on SBA number as input.

Request type: HTTPS

API Endpoint:

GET /api/etran_ppp_validation/?sba_number=NNNNNNNNNN

Request (Sample)

/api/etran_ppp_validation/?sba_number=5279100030

Request Parameters

Not Applicable (No request body)

Request Path Parameters

Not Applicable (Mo Request Path Parameters)

Request Query Parameters

sba_number=SBA_Number

Request Form Data Parameters

Not Applicable

Response (Sample)

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "sba_number": 5279100030,
            "etran_notional_amount": 900000.0,
            "etran_busnm": null,
            "address1": "",
            "address2": ""
	    "tin_type": 0
	    "etran_hold_flag_indicator": true
        }
    ]
}

Response Parameters

HTTP Response Code: 200

Parameter Name	Data Type	Sample Value	Description
count	Number	1	The count of PPP Loan for SBA number. Its value will be 0 if PPP Loan number provided is not found
next	String	null	The URI of the next set of list of PPP Loans to be fetched. It will be null
previous	String	null	The URI of the previous set of PPP Loan to be fetched. It will be null
results	`JSON Array`
sba_number	number	5279100030	Unique ID within SBA system for loan
etran_notional_amount	Number	900000.0	Loan Amount
etran_busnm	String	null	eTran Busniness Name
address1	String	””	Address Line 1 of the Borrower
address2	String	””	Address Line 2 of the Borrower
tin_type	Number	0	TIN Type of Borrower/Business used for PPP Loan - EIN=0, SSN=1, ITIN=4
etran_hold_flag_indicator	boolean	true	Whether PPP Loan is on hold by SBA

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, PPP 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 the ability to validate the PPP Loan.

12. Get Validated and Standardized Address

This API is used to validate and get standardized addresses along with Zip+4. API users may use it to ensure addresses are valid before submitting Grant request to SBA and normalize street address formats (Rd, St, Alley etc). We recommend all address be valided before submission. In case address fails validation, the City and Zip will be validated during submission to ETRAN. US territories may also fail validation via this API but can be submitted with valid two letter state and zip code.

Request type: HTTPS

API Endpoint:

GET /api/address_validation?address_1=XXXXX&address_2=yyyyy&city=zzzz&state=sssss&zip_code=NNNNN

Request (Sample)

/api/address_validation?address_1=101 ABC Lane&address_2&city=Newark&state=delaware&zip_code=19701

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
address_1	String	Mandatory	1001 ABC Lane	Address Line 1
address_2	String	Optional	Suite A	Address Line 2
city	String	Mandatory	Newark	City
state	String	Mandatory	Delaware	State
zip_code	Number	Mandatory	19701	Zip code

Request Form Data Parameters

Not Applicable

Response (Sample)

    {
        "input_id": null,
        "input_index": 0,
        "candidate_index": 0,
        "addressee": null,
        "delivery_line_1": "1001 ABC Ln",
        "delivery_line_2": null,
        "last_line": "Newark DE 19701-9420",
        "delivery_point_barcode": "197019420056",
        "components": {
            "urbanization": null,
            "primary_number": "1305",
            "street_name": "Madison",
            "street_predirection": null,
            "street_postdirection": null,
            "street_suffix": "Ln",
            "secondary_number": null,
            "secondary_designator": null,
            "extra_secondary_number": null,
            "extra_secondary_designator": null,
            "pmb_designator": null,
            "pmb_number": null,
            "city_name": "Newark",
            "default_city_name": "Newark",
            "state_abbreviation": "DE",
            "zipcode": "19701",
            "plus4_code": "9420",
            "delivery_point": "05",
            "delivery_point_check_digit": "6"
        },
        "metadata": {
            "record_type": "S",
            "zip_type": "Standard",
            "county_fips": "10003",
            "county_name": "New Castle",
            "carrier_route": "R013",
            "congressional_district": "AL",
            "building_default_indicator": null,
            "rdi": "Residential",
            "elot_sequence": "0115",
            "elot_sort": "D",
            "latitude": 30.77354,
            "longitude": -70.70868,
            "precision": "Zip7",
            "time_zone": "Eastern",
            "utc_offset": -5,
            "obeys_dst": true,
            "is_ews_match": null
        },
        "analysis": {
            "dpv_match_code": "Y",
            "dpv_footnotes": "AABB",
            "cmra": "N",
            "vacant": "N",
            "active": "Y",
            "footnotes": "N#",
            "lacs_link_code": null,
            "lacs_link_indicator": null,
            "is_suite_link_match": null
        }
    }
]

Response Parameters

HTTP Response Code: 200

Parameter Name	Data Type	Sample Value	Description
input_id	String	null	Any unique identifier that you use to reference the input address; the output will be identical to the input.
input_index	Number	0	The order in which this address was submitted with the others
candidate_index	Number	0	An input address can match multiple valid addresses. This ties the candidates to the input index.(e.g., “1 Rosedale Street Baltimore Maryland” will return multiple candidates.)
addressee	String	null	The name of the person or company at this address. This value is taken directly from the addressee input field. Very rarely, this field might be filled automatically based on the USPS address record.
delivery_line_1	String	1305 ABC Lane	Contains the first delivery line (usually the street address). This can include any of the following:urbanization (Puerto Rico only), primary number, street predirection, street name, street suffix, street postdirection, secondary designator, secondary number, extra secondary designator, extra secondary number, PMB designator, PMB number
delivery_line_2	String	Null	The second delivery line (if needed). It is common for this field to remain empty, but it may contain a private mailbox number.
last_line	String	Null	City, state, and ZIP Code combined
delivery_point_barcode	String	Null	12-digit POSTNET™ barcode; consists of 5-digit ZIP Code, 4-digit add-on code, 2-digit delivery point, and 1-digit check digit.
components	object		standardized address fields, see sample
metadata	object		metadata of address fields, see sample
analysis	object		analysis of address fields, see sample.

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 address is not found

HTTP Response Code: 429

API Call Rate Limits
To maintain reliability and stability within our environments, PPP 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 is used to validate and get standerdized address along with Zip+4. API users may use it to ensure address is valid before submitting grant request to SBA. Please note - This API is optional and is not expected to replace your existing address validation & standardization routines. Please donot use this API for type ahead functionaility within your application.