SAM.gov Assistance Subaward Reporting Public API

Overview

The Assistance Subaward Reporting Public API provides published and deleted federal subaward data. The production Assistance Subaward Reporting Public API has a target launch date of Spring 2025.

Tips and Key Features of the Assistance Subaward Outbound API

This API:

Provides synchronous responses.
Provides optional search parameters, filtering by sections AND (&) condition to obtain the desired data.
Requires pagination: Use page number and page size parameters to get data in manageable quantities rather than all records at once. The default pagination is 100 records per page.
- Configure the page size by passing it as a query string in the URL. Set the page size to 1,000 to improve search performance for large data requests - for example, https://api.sam.gov/assistance/v1/subawards/search?pageNumber=0&pageSize=1000.
Has status options of Published and Deleted. If no status is passed as a parameter, Published is the default value.
Does not allow the characters & | { } ^ \ in parameter values.

Getting Started

Access the Assistance Subaward Reporting Public API from the following Production or Alpha environments:

API Endpoints

Production

Target Availability in Spring 2025

Alpha

https://api-alpha.sam.gov/prodlike/assistance/v1/subawards/search
https://api-alpha.sam.gov/prodlike/assistance/v1/subawards/search?status=Deleted

Authentication and API Keys

We require an API key to use this API. Request a public API key from your SAM.gov user account on the Account Details page. If using the Alpha environment API, get your API key from your alpha.SAM.gov user account. Get a Production environment API key from your SAM.gov user account.

API Key Rate Limits

We limit call rates by day and account type.

Type of Account	Type of API Key	API Daily Rate Limit
Non-federal users with no role to an entity in SAM.gov	Personal API Key	10 requests/day
Non-federal users with a role to an entity in SAM.gov	Personal API Key	1,000 requests/day
Federal Users	Personal API Key	1,000 requests/day
Non-federal System Account users	System Account API Key	1,000 requests/day
Federal System Account users	System Account API key	10,000 requests/day

GET Request Parameters

Parameters

Use these parameters to limit results.

Field Name	Description	Required	Data Type	Applicable Versions
api_key	Public key of users.	Yes	String	v1
pageSize	Total number of records to be retrieved per page. This field must be a number Max Value = 1000. Default page size is 100.	No	Int	v1
pageNumber	Indicates the page index. Default offset starts with 0.	No	Int	v1
status	Allows users to request submitted records that were deleted. If the user does not pass any value, the system will default status = Published	No	string	v1

Search Filters

Use filters to get specific results.

Filter	Description	Required	Data Type	Applicable Versions
uniqueAwardKey	Business key to identify subawards under each prime. Unique for a contract and gives complete subaward information pertaining to that contract	No	Alphanumeric	v1
fain	Unique Identifier for grant awards.	No	Alphanumeric	v1
agencyCode	Allows user to pull prime information to identify the contract family.	No	Numeric	v1
fromDate	Allows users to filter by From Date. By specifying From and To Dates, records can be retreived spanning multiple years with no yearly limit. If both From Date and To Date are provided, user will retrieve records that fall within that inclusive date range.	No	string	v1
toDate	Allows users to filter by To Date. If only the From Date is provided, the query will automatically set the To Date as current date.	No	string	v1

Status Values

Status Name	Value
Published	Returns all published subaward information for a contract. If no status is passed as a parameter, Published is the default value.
Deleted	Returns deleted records submitted for a contract. Delete must be passed as a status to return deleted records.

GET Assistance Response Parameters

The Assistance Subaward Reporting Public API offers respone parameters described in this section. The API response returns a JSON summarized view of the subawards based on your request filters.

Field Name	Description	Data Type	Applicable Versions
totalPages	Total Pages	int	v1
totalRecords	Total Records	int	v1
pageNumber	Page Number. If the user does not pass any value, the system will default pageNumber = 0	int	v1
nextPageLink	Next Page Link	string	v1
previousPageLink	Previous Page Link	string	v1
uniqueAwardKey	Unique Award Key	string	v1
PIID	PIID	string	v1
agencyId	Agency ID	string	v1
referencedIDVPIID	Reference IDV PIID	string	v1
referencedIDVAgencyId	Reference IDV Agency PIID	string	v1
subawardReportId	Subaward Report ID	string	v1
subawardReportNumber	Subaward Report Number	string	v1
submittedDate	Submitted Date	string	v1
subAwardNumber	Subaward Number	string	v1
subAwardAmount	Subaward Amount	string	v1
subAwardDate	Subaward Date	string	v1
subEntityUei	Sub Entity UEI	string	v1
subTopPayEmployee	Sub Top Pay Employee	string	v1
subEntityLegalBusinessName	Sub Entity Legal Business Name	string	v1
subEntityDoingBusinessAsName	Sub Entity Doing Business As	string	v1
primeAwardType	Award Type	string	v1
totalContractValue	Total Contract Value	string	v1
primeEntityUei	Prime Awardee UEI	string	v1
primeEntityName	Prime Awardee Legal Business Name	string	v1
baseAwardDateSigned	Base Award Date Signed	string	v1
descriptionOfRequirement	Description of Requirement	string	v1
primeNaics	NAICS Code	string	v1
primeOrganizationInfo	Contracting Subtier Name	string	v1
subEntityPhysicalAddress	Sub Entity Physical Address	string	v1
subBusinessType	Sub Business Type	string	v1
subEntityParentLegalBusinessName	Sub Entity Parent Legal Business Name	string	v1
subParentUei	Sub Parent UEI	string	v1
subEntityTopPayEmployee	Sub Entity Top Pay Employee	string	v1

Open API Specification File

You can view the full details of this API in the OpenAPI Specification file available here: OpenAPI File

Assistance Subaward Outbound v1

 /{type}/v1/{subType}/search:
    get:
      tags:
      - Subaward Search Module API
      - OpenSearch APIs
      summary: Search entries
      description: Search entries
      operationId: search
      parameters:
      - name: pageNumber
        in: query
        required: false
        schema:
          type: string
          default: "0"
      - name: pageSize
        in: query
        required: false
        schema:
          type: string
          default: "100"
      - name: status
        in: query
        required: false
        schema:
          type: string
          default: Published
      - name: uniqueAwardKey
        in: query
        required: false
        schema:
          type: string
      - name: PIID
        in: query
        required: false
        schema:
          type: string
      - name: agencyId
        in: query
        required: false
        schema:
          type: string
      - name: referencedIDVAgencyId
        in: query
        required: false
        schema:
          type: string
      - name: primeAwardType
        in: query
        required: false
        schema:
          type: string
      - name: referencedIDVPIID
        in: query
        required: false
        schema:
          type: string
      - name: fain
        in: query
        required: false
        schema:
          type: string
      - name: agencyCode
        in: query
        required: false
        schema:
          type: string
      - name: fromDate
        in: query
        required: false
        schema:
          type: string
      - name: toDate
        in: query
        required: false
        schema:
          type: string
      - name: type
        in: path
        required: true
        schema:
          type: string
      - name: subType
        in: path
        required: true
        schema:
          type: string
      responses:
        "500":
          description: Internal Server Error
          content:
            '*/*':
              schema:
                type: object
        "200":
          description: successful operation
          content:
            '*/*':
              schema:
                type: object
        "404":
          description: Not Found
          content:
            '*/*':
              schema:
                type: object
        "403":
          description: Forbidden
          content:
            '*/*':
              schema:
                type: object
        "400":
          description: Bad Request
          content:
            '*/*':
              schema:
                type: object
        "501":
          description: Not Implemented
          content:
            '*/*':
              schema:
                type: object
        "405":
          description: Validation exception
          content:
            '*/*':
              schema:
                type: object

HTTP Response Codes

HTTP Response Code	Description
200	Successful
400	Bad Request
401	Unauthorized Error
403	Forbidden
405	Method Not Allowed
500	Internal Server Error

Error Messages

Scenario	Error Messages
For page size, user provides page size <=0 or >1000.	PageSize valid range is 1-1,000. Please provide valid input.
For page number, user provides page number < 0.	PageNumber must be a positive number.
For limit, user provides range beyond 1000.	Limit valid range is 0-1000. Please provide valid input.
For limit or offset, user inputs characters/special characters.	Limit/Offset must be a positive integer.
From Date has invalid date format.	Invalid FromDate. Date must be in format ‘yyyy-MM-dd’.
To Date has invalid date format.	Invalid To Date. Date must be in format ‘yyyy-MM-dd’.
From Date value is after To Date value.	From Date cannot be after To date. Please provide valid input.
To Date value is after Current Date value.	To Date cannot be after the current date. Please provide valid input.
Content in Description link is not available.	Description Not Found.
Status Value is invalid.	Valid status values are: Deleted, Published.
UniqueAwardKey is invalid.	UniqueAwardKey must consist of alphanumeric characters only, with the underscore ‘_’ being the only allowed special character.
PIID value is invalid.	PIID value must be alphanumeric.
ReferencedIDVPIID value is invalid.	Referenced IDV PIID value must be alphanumeric.
AgencyID value is invalid.	Agency ID value must be a four-digit number.
ReferencedIDV value is invalid.	ReferencedIDV agency ID value must be a four-digit number.
PrimeAwardType value is invalid.	Prime award type value must be alphanumeric.
API Key is invalid.	An invalid API key was supplied.
No API Key is provided.	No API key was supplied. Please submit with a valid API key.

Examples

Example 1: Search Published Records by UniqueAwardKey

Request URL

Production URL: https://api.sam.gov/assistance/v1/subawards/search?pageSize=25&pageNumber=0&uniqueAwardKey=ASST_NON_27MN12002L97E1_6925&api_key=

Alpha URL: https://api-alpha.sam.gov/prodlike/assistance/v1/subawards/search?pageSize=25&pageNumber=0&uniqueAwardKey=ASST_NON_27MN12002L97E1_6925&api_key=

Response (JSON Output) v1

{
  "totalPages": 1,
  "totalRecords": 1,
  "pageNumber": 0,
  "nextPageLink": "https://api-alpha.sam.gov/prodlike/assistance/v1/subawards/search?pageNumber=0&pageSize=25",
  "previousPageLink": "https://api-alpha.sam.gov/prodlike/assistance/v1/subawards/search?pageNumber=0&pageSize=25",
  "data": [
    {
      "status": "Published",
      "submittedDate": "2012-10-31",
      "subVendorName": "CROW WING COUNTY (INC)",
      "subVendorUei": "KRPSCRWNEPM3",
      "subAwardNumber": "018-630-005",
      "subAwardAmount": "30307",
      "subAwardDate": "2012-09-19",
      "reportUpdatedDate": "2012-10-31",
      "subawardReportId": "84924255",
      "subawardReportNumber": "67e15942-6353-11ef-a436-4bf2d183e71f",
      "placeOfPerformance": {
        "streetAddress": null,
        "streetAddress2": null,
        "city": "Crow Wing County",
        "congressionalDistrict": "08",
        "state": {
          "code": "MN",
          "name": "Minnesota"
        },
        "country": {
          "code": "USA",
          "name": "United States"
        },
        "zip": "564421200"
      },
      "organizationInfo": null,
      "asistanceListingNumber": "20.205 Highway Planning and Construction",
      "subawardDescription": "County State Aid Highway 3: Emergency Relief Work, Aggregate BASE, Bituminous Pavement REPLacement, AGGregate SHouLder, Culvert Replacement, Erosion Repair",
      "fain": "27MN12002L97E1",
      "actionDate": "2012-09-04",
      "totalFedFundingAmount": "37600.0",
      "baseObligationDate": "2012-09-04",
      "projectDescription": "ALONG TH 11: DEVELOP A CORRIDOR MGMT PLAN FOR THE WATERS OF THE DANCING SKY SCENIC BYWAYS",
      "baseAssistanceTypeCode": "03",
      "baseAssistanceTypeDesc": null,
      "agencyCode": "6925",
      "assistanceType": null,
      "primeEntityUei": "JL4EX4R4A647",
      "primeEntityName": "Minnesota Department Of Transportation",
      "uniqueAwardKey": "ASST_NON_27MN12002L97E1_6925",
      "vendorPhysicalAddress": {
        "streetAddress": null,
        "streetAddress2": null,
        "city": null,
        "congressionalDistrict": null,
        "state": {
          "code": null,
          "name": null
        },
        "country": {
          "code": null,
          "name": null
        },
        "zip": null
      },
      "subDbaName": null,
      "subParentName": null,
      "subParentUei": null,
      "subBusinessType": null,
      "subTopPayEmployee": null
    }
  ]
}

Example 2: Search Published Records by FAIN and Agency Code

Request URL

Production URL: https://api.sam.gov/assistance/v1/subawards/search?pageSize=25&pageNumber=0&fain=27MN12002L97E1&agencyCode=6925&fromDate=2012-01-01&toDate=2013-12-31&api_key=

Alpha URL: https://api-alpha.sam.gov/prodlike/assistance/v1/subawards/search?pageSize=25&pageNumber=0&fain=27MN12002L97E1&agencyCode=6925&fromDate=2012-01-01&toDate=2013-12-31&api_key=