Overview

The Extracts Download API allows users to request Unclassified (“Public”), Controlled Unclassified Information (CUI) “For Official Use Only” (FOUO) or CUI “Sensitive” entity extracts and Unclassified (“Public”) exclusion extract, based on the sensitivity level of the user account and through several optional request parameters.

Public Entity Extracts:

They constitute publicly available entities and their unclassified data available under the Freedom of Information Act (FOIA) for those registered in SAM.gov to do business with the Federal government.

FOUO (CUI) Entity Extracts:

They constitute both the publicly available entities and the entities that have opted out of public display, along with their unclassified data available under the Freedom of Information Act (FOIA) and FOUO CUI data.

Sensitive (CUI) Entity Extracts:

They constitute both the publicly available entities and the entities that have opted out of public display, along with their unclassified data available under the Freedom of Information Act (FOIA), FOUO CUI data and Sensitive CUI data.

Public Exclusions Extracts:

They constitute publicly available list of all parties with a currently active exclusion in SAM.gov.

Extract Calendar

Monthly Public, FOUO (CUI) and Sensitive (CUI) Extracts
  • They are produced on the first Sunday of each month. Kindly check after 7 AM Eastern time.
  • The date on the .ZIP file matches the date when the file was generated.
    E.g.: The April monthly files were generated and dated on 20220403.
  • The date on the .ZIP file matches the date on the .dat file inside.
  • These files contain all active entities and entities expired in the last 6 months.
  • File Naming Convention:
    Monthly ASCII:
    • SAM_PUBLIC_MONTHLY_V2_YYYYMMDD.ZIP
    • SAM_FOUO_MONTHLY_V2_YYYYMMDD.ZIP
    • SAM_SENSITIVE_MONTHLY_V3_YYYYMMDD.ZIP
    Monthly UTF-8:
    • SAM_PUBLIC_UTF-8_MONTHLY_V2_YYYYMMDD.ZIP
    • SAM_FOUO_UTF-8_MONTHLY_V2_YYYYMMDD.ZIP
    • SAM_SENSITIVE_UTF-8_MONTHLY_V3_YYYYMMDD.ZIP
Daily FOUO (CUI) and Sensitive (CUI) Extracts
  • They are produced every Tuesday-Saturday. Kindly check after 7 AM Eastern time.
  • The date on the .ZIP file matches the date when the file was generated.
    E.g.: The file generated on 04/05/2022 will show 20220405.
  • The date on the .ZIP file matches the date on the .dat file inside.
  • These are incremental files that contain new/updated/deactivated/expired entities since the previous day’s file.
  • File Naming Convention:
    Daily ASCII:
    • SAM_FOUO_DAILY_V2_YYYYMMDD.ZIP
    • SAM_SENSITIVE_DAILY_V3_YYYYMMDD.ZIP
    Daily UTF-8:
    • SAM_FOUO_UTF-8_DAILY_V2_YYYYMMDD.ZIP
    • SAM_SENSITIVE_UTF-8_DAILY_V3_YYYYMMDD.ZIP
Daily Exclusion Extracts
  • They are produced every day. Kindly check after 7 AM Eastern time.
  • The date on the .ZIP file matches the date when the file was generated.
    E.g.: The file generated on 04/05/2022 will show 2022095.
  • The date on the .ZIP file matches the date on the .CSV file inside.
  • These files contain all the active exclusions.
  • File Naming Convention:
    Daily ASCII:
    • SAM_Exclusions_Public_Extract_V2_YYDDD.ZIP (YYDDD is the Julian Date)
    E.g.: The file for 04/06/2022 would be SAM_Exclusions_Public_Extract_V2_22096.ZIP.
Daily FASCSA Exclusion Extracts
  • They are produced every day. Kindly check after 7 AM Eastern time.
  • The date on the .CSV file matches the date when the file was generated.
  • The file generated on 10/04/23 will show 23277.
  • These files contains all FASCSA active exclusions.
  • File Naming Convention:
    Daily ASCII:
    • FASCSAOrdersYYDDD.CSV (YYDDD is the Julian Date)
    E.g.: The file for 10/04/2023 would be FASCSAOrders23277.CSV.

Back to top

Getting Started

API endpoints

Production:

  • https://api.sam.gov/data-services/v1/extracts?api_key=
  • https://api.sam.gov/data-services/v1/extracts?

Alpha:

  • https://api-alpha.sam.gov/data-services/v1/extracts?api_key=
  • https://api-alpha.sam.gov/data-services/v1/extracts?

User Requirements

To access Public extracts:

  • Users must have a non-Federal/Federal Individual (Personal) account and the respective API Key, a non-Federal/Federal System Account with the “Read Public” permission and the respective API Key in SAM.gov.
  • Users can make GET calls using any Browser or a Restful API client such as Postman.

To access FOUO (CUI) extracts:

  • Users must have a Federal System Account with the “Read FOUO” permission and the respective API Key in SAM.gov.
  • Users can make GET calls using any Browser, or a Restful API client such as Postman.

To access Sensitive (CUI) extracts:

  • Users must have a Federal System Account with the “Read Sensitive” permission and the respective API Key in SAM.gov.
  • Users must make POST calls using a Restful API client such as Postman.

Individual (Personal) Accounts

  • The SAM.gov Federal or non-Federal registered users must obtain the API Key from the https://sam.gov/profile/details page using the field, “Public API Key”.
    image info
  • Click on the “Eye” icon, enter the “Enter One-time Password” (this value will be sent to your email address that is associated with your registered account), hit “Submit”, for the API Key value to appear in the box.

System Accounts

  • The SAM.gov non-Federal registered users must request for a System Account. If their registration and request criteria are satisfied, then they will be provided with the System Accounts” widget on their SAM.gov “Workspace” page.
  • The SAM.gov Federal registered users must contact their CCB representatives for obtaining the “System Accounts” widget on their SAM.gov “Workspace” page.
  • Users must create their System Account using the “System Accounts” widget and get it approved.
  • Users must then set the password for the System Account.
  • After the above step is successfully completed, users will see a new section for retrieving the API Key. Users must enter the password to retrieve this value.

  • System Accounts must satisfy the following criteria to successfully utilize this API:

    • System Information
      Unique System ID: The System Account ID
    • Permissions
      Entity Information: read public –> Gives access to the Public extracts
      Entity Information: read public, read fouo –> Gives access to the Public and FOUO (CUI) extracts.
      Entity Information: read public, read fouo, read sensitive –> Gives access to the Public, FOUO (CUI) and Sensitive (CUI) extracts.
    • Security Information
      IP Address: List all the IP Addresses that the System invokes the API from.
    • Type of Connection: Data Service Extracts
    • System Account Password
    • System Account API Key

API Key Rate Limits

Type of User Account Type of API Key Default API Daily Rate Limit
Non-federal user with no Role in SAM.gov Personal API key 10 requests/day
Non-federal user with a Role in SAM.gov Personal API key 1,000 requests/day
Federal User Personal API key 1,000 requests/day
Non-federal System user System account API key 1,000 requests/day
Federal System user System account API key 10,000 requests/day
Sensitive API Process:
  • The System Account User ID and Password must be sent as "Basic Auth" under the "Authorization" Header. The combination needs to be base 64 encoded as base64(username:password).
  • The API Key value must be sent as "x-api-key" under "Headers" and not directly in the request URL.
  • The "Accept" parameter must be sent as "application/json" under "Headers".
  • The "Content-Type" parameter must be sent as "application/json" under "Headers".
  • All the optional search filters can be sent in the request URL or in the "Body".
An example of the Sensitive extract download POST call using Postman: Request URL: https://api.sam.gov/data-services/v1/extracts?fileName=< name of the file >
Click to view Sample Authorization Sample Extract Authorization
Click to view Sample Request Header Sample Request Header
An example of the Sensitive extract download POST call using curl: Curl request with basic auth token: curl -X POST "https://api.sam.gov/data-services/v1/extracts?fileName=< fileName >" --header "X-Api-Key: < a valid API Key >" --header "Content-Type: application/json" --header "Accept: application/zip" --header "Authorization: Basic < auth token >" --output C:\sample_file.ZIP

Curl request with username and password: curl -X POST "https://api.sam.gov/data-services/v1/extracts?fileName=< fileName >" --header "X-Api-Key: < a valid API Key >" --header "Content-Type: application/json" --header "Accept: application/zip" --user "< username >:< password >" --output C:\sample_file.ZIP

Back to top

API Description

Query String Parameters:
The Extracts Download API offers several optional search parameters.
Parameter Name Description
api_key This parameter is required to identify and validate API users and their role-based access.
fileName This parameter must be used on its own. It allows users to provide the extract file name.
Examples: fileName=SAM_PUBLIC_MONTHLY_V2_20220406.ZIP;
fileName= SAM_Exclusions_Public_Extract_V2_22096.ZIP;
fileName= FASCSAOrders23277.CSV
fileType This parameter must be used if fileName is not specified. It allows users to specify the type of the extract that they wish to download.
Permitted values: ENTITY, EXCLUSION, SCR, BIO
sensitivity This parameter must not be used in conjunction with the fileName parameter. It allows users to provide the desired sensitivity level of the extract that they wish to download, if they have proper roles.
Default value, if the parameter is not provided: PUBLIC
Permitted values:
  • PUBLIC – Returns the Public extracts.
  • FOUO – Returns the FOUO (CUI) extracts.
  • SENSITIVE – Returns the Sensitive (CUI) extracts.
frequency This parameter allows users to request either a DAILY or MONTHLY extract
Default value, if the parameter is not provided: MONTHLY
Permitted values: DAILY, MONTHLY
charset This parameter allows users to request either the ASCII or UTF-8 extract character-set.
Default value, if the parameter is not provided: ASCII
Permitted values: ASCII, UTF8, UTF-8
Note: This parameter is not applicable for the EXCLUSION file type.
date This parameter allows users to select a specific date of the file that they wish to download.
Format: MM/DD/YYYY for Daily files; MM/YYY for Monthly files.
Default value: Most recent date, depending on fileType
Examples: 04/06/2022; 04/2022
version This parameter allows users to select the file they wish to download by version.
Permitted values: V2 for the Public, FOUO and Exclusion extracts; V3 for the Sensitive extract.
Extract Mapping Document and Layouts:
Please refer to the following:
Sample Extract File Names:
  • Public Entity files:
    • SAM_PUBLIC_UTF-8_MONTHLY_V2_20220403.ZIP
    • SAM_PUBLIC_MONTHLY_V2_20220403.ZIP
  • FOUO (CUI) Entity files:
    • SAM_FOUO_DAILY_V2_20220405.ZIP
    • SAM_FOUO_MONTHLY_V2_20220403.ZIP
    • SAM_FOUO_UTF-8_DAILY_V2_20220405.ZIP
    • SAM_FOUO_UTF-8_MONTHLY_V2_20220403.ZIP
  • Sensitive (CUI) Entity files:
    • SAM_SENSITIVE_DAILY_V3_20220405.ZIP
    • SAM_SENSITIVE_MONTHLY_V3_20220403.ZIP
    • SAM_SENSITIVE_UTF-8_DAILY_V3_20220405.ZIP
    • SAM_SENSITIVE_UTF-8_MONTHLY_V3_20220403.ZIP
  • Public Exclusion files:
    • SAM_Exclusions_Public_Extract_V2_22096.ZIP
    • SAM_Exclusions_Public_Extract_V2_22097.ZIP
  • FASCSA Exclusions files:
    • FASCSAOrders23306.CSV
    • FASCSAOrders23305.CSV
Extract Download API Sample Requests:
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileName=SAM_PUBLIC_MONTHLY_V2_20220403.ZIP
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileType=ENTITY&sensitivity=PUBLIC&frequency=MONTHLY&date=04/2022
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileType=ENTITY&sensitivity=PUBLIC&frequency=MONTHLY&date=04/2022&charset=UTF8
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileName=SAM_FOUO_DAILY_V2_20220407.ZIP
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileName=SAM_FOUO_MONTHLY_V2_20220403.ZIP
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileType=ENTITY&sensitivity=FOUO&frequency=DAILY&date=04/07/2022
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileType=ENTITY&sensitivity=FOUO&frequency=MONTHLY&date=04/2022
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileType=ENTITY&sensitivity=FOUO&frequency=DAILY&date=04/07/2022&charset=UTF8
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileType=ENTITY&sensitivity=FOUO&frequency=MONTHLY&date=04/2022&charset=UTF8
  • https://api.sam.gov/data-services/v1/extracts?fileName=SAM_SENSITIVE_DAILY_V3_20220407.ZIP
  • https://api.sam.gov/data-services/v1/extracts?fileName=SAM_SENSITIVE_MONTHLY_V3_20220403.ZIP
  • https://api.sam.gov/data-services/v1/extracts?fileType=ENTITY&sensitivity=SENSITIVE&frequency=DAILY&date=04/07/2022
  • https://api.sam.gov/data-services/v1/extracts?fileType=ENTITY&sensitivity=SENSITIVE&frequency=MONTHLY&date=04/2022
  • https://api.sam.gov/data-services/v1/extracts?fileType=ENTITY&sensitivity=SENSITIVE&frequency=DAILY&date=04/07/2022&charset=UTF8
  • https://api.sam.gov/data-services/v1/extracts?fileType=ENTITY&sensitivity=SENSITIVE&frequency=MONTHLY&date=04/2022&charset=UTF8
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileName=SAM_Exclusions_Public_Extract_V2_22097.ZIP
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileType=EXCLUSION&date=04/07/2022
  • https://api.sam.gov/data-services/v1/extracts?api_key={API KEY}&fileName=FASCSAOrders23306.CSV

OpenAPI Specification File

You can view the full details of this API’s in the OpenAPI Specification file available here:
Open API specification file for the Entity/Exclusions Extracts Download API

Back to top

Sample Extract Files

Extract files with UEI Information:

Back to top

HTTP Response Codes

The API will return one of the following responses:

HTTP Response Code Description
200 Successful. Data will be returned in JSON format.
400 Application Level Error Messages:
* User does not have permission to download the file.
* Missing required parameters, fileName OR fileType
* The requested extract file not found
* Invalid date format
* This http method is not allowed to download sensitive extracts. Only POST is supported for sensitive extracts.
* This http method is not allowed to download non-sensitive extracts. Only GET is supported for non-sensitive extracts.
* No api_key was supplied in request body. Please submit with a valid API key.
* No system account credentials are provided. Please provide credentials via basic authentication.
* The parameter fileName cannot be used with any other parameters.
* The File does not exist with the provided parameters
* The requested extract file needs FOUO roles to download
* IP Addresses associated with this System Account are different from that sending the request. Please submit your requests from a valid system.
* Insufficient privileges to perform the operation - System account must have Type of Connection as Restful.
406 Invalid Accept Header.
415 Invalid Content-Type Header.

Back to top

Contact Us

  • Reach out to the SAM.gov team at www.fsd.gov for inquiries and help desk support.
    • Before contacting the help desk, conduct your own initial troubleshooting
      • Conduct a recent review of the open.gsa.gov/api specifications
      • Confirm you are using an API tool, not a browser to send the request. (FOUO & Sensitive Calls)
      • Confirm you are using the username/password for the system account that created the API key in the authentication header. (Sensitive Calls)
      • Confirm you used POST and not GET for this request (Sensitive Calls)
      • Confirm that the API key is from a system account (FOUO & Sensitive Calls)
      • Confirm that the API key being used is still active
      • Confirm that the system account you are using has “read fouo” or “read sensitive” permissions as applicable (FOUO & Sensitive Calls)
      • Confirm that the IP addresses registered with your system account are current
    • When submitting help desk tickets for API or system connection issues, provide the following:
      • The exact API requests that you were trying to send
      • The exact error messages that you were receiving
      • The exact dates and times when you received the errors
      • Screenshots (with the actual API request and the error) [Attach to the ticket]
      • The System Account ID/Name that was trying to make API calls
      • Screenshots of the parameters used for API call [Attach to the ticket]
      • Screenshots of the Headers used for the API call [Attach to the ticket]
  • Users requesting access to the test site (alpha.sam.gov) should follow the below steps. These steps ONLY apply to alpha.sam.gov access requests.
    1. Navigate to www.fsd.gov
    2. Sign into the FSD platform using your FSD credentials
    3. Select “Create an Incident”
    4. Create an Incident
      1. System Name: System for Award Management (SAM)
      2. Is this related to the American Rescue Plan Act?: No
      3. Issue Type: Other
      4. Business Type: Other
      5. Subject (select 1):
        1. Option A: I need a role to test in alpha.sam.gov.
        2. Option B: System account approval in alpha.sam.gov
      6. Please describe the issue: (Copy and paste the below information into the ticket, filling in your information within the brackets)
        1. Option A: I have already navigated to alpha.sam.gov and created a user account, following the same steps for creating an account in sam.gov. I would like to conduct testing but do not have the necessary role(s) in alpha.sam.gov. The account that needs role assignment is associated with [EMAIL ADDRESS]. I request a [ROLE] role for the [DOMAIN] domain in alpha.sam.gov.
        2. Option B: I am creating/editing a system account and have submitted my account in alpha.sam.gov for approval. I would like to request alpha.sam.gov system account review and approval for [Name of the alpha.sam.gov system account].

Back to top

Change Log

Date Version Description
06/03/2019 v1.0 Base Version
08/15/2019 v1.1 * Added Beta.SAM.Gov to the page title.

* Clarified the Alpha and Beta endpoints.
12/20/2019 v1.2 * Added Sample FOUO and Sensitive File Names and Revised extract layouts for the upcoming UEI/EVS changes.

* Added “COMING SOON” section for upcoming changes to Alpha and Beta endpoints to meet new API standards.
02/25/2020 v1.3 * Updated Alpha endpoint to meet new API standards.

* Added Sample Extract Files.
02/28/2020 v1.4 * Updated Beta endpoint to meet new API standards.

* Removed “COMING SOON” information in Getting Started section.

* Added FOUO and Sensitive Sample Extract Files for different versions.
04/20/2020 v1.5 Updated Public, FOUO and Sensitive Sample Extract Files that includes UEI information.
06/10/2020 v1.6 Added the endpoint, new process and an example for the Download API .
08/17/2020 v1.7 * The Sensitive Alpha endpoint in “Getting Started” has been corrected and the Sample Extract Authorization screenshot in “Explanation of the API using Examples” has also been updated to reflect the correct endpoint.

* Sensitive data sample calls in the “Explanation of the API using Examples” have also been updated to show that the API key is no longer sent in the request URL.

* The “Sensitive Download API Process” section has been updated with additional steps for sending Sensitive requests (sending “Accept” and “Content-Type” parameters).

* The Sample Request Header screenshot in the “Explanation of the API using Examples” has been updated to reflect the new parameters as well. Two new codes (406, 415) have been added in the “HTTP Response Codes” section.
08/31/2020 v1.8 * Updated the Getting Started section to include the Sensitive Beta endpoint.
02/05/2021 v1.9 * Added V1/V2 Public, V3 Sensitive, and V2 FOUO files available in Alpha S3.

* Added version parameter

* Updated error messages

* Added note to charSet parameter stating exclusions file type is not applicable
03/12/2021 v2.0 * Added additional FOUO sample files.

* Added note that only system account keys can be used for FOUO and sensitive downloads.
04/08/2021 v2.1 * Updated Contact Us information.

* Added Entity Extract Calendar under Overview.
04/29/2021 v2.2 * Added note above list of sample files mentioning that files are for Alpha.

* Added description to 400 http response code describing Type of Connection error.

* Updated openapi spec file.
05/12/2021 v2.3 * Updated instances of beta.sam.gov to SAM.gov.

* Removed non-relevant information for Beta api.
07/16/2021 v2.4 * Updated the instructions on sending “Basic Auth” under the “Authorization” header.

* Added the Type of Connections and Rate Limits table.

* Updated the Contact Us information.

* Added example curl requests.
09/21/2021 v2.5 * Added the “Please refer to the SAM Master Extract Mapping document” subsection under the “Explanation of the API using Examples” section.
10/06/2021 v2.6 * Updated the “Contact Us” section.
10/21/2021 v2.7 * Added Expected Results to Data Package Sample API Calls.

* Updated Extract Mapping Files.
02/01/2022 v2.8 * Updated the Exclusions Extract Layout file.

* Updated the Exclusions Public V2 Extract file.
04/04/2022 v2.9 * Sample Extract Files section: Removed old sample files that had DUNS information and provided new files with UEI information.

* Updated “Effective April 2022: SAM Master Extract Mapping” to remove the DUNS occurrences.

* Updated the “April 2022 release: FOUO Extract Layout” with the correct Sensitivity levels for the Points Of Contact elements.

* Updated the “April 2022 release: Sensitive Extract Layout” to reflect the correct order for “IMMEDIATE PARENT EVS SOURCE”.

* Updated the “April 2022 release: Exclusions Extract Layout” to remove the DUNS occurrences.
04/08/2022 v3.0 * Removed all the references to older files that are no longer valid.

* Provided references to the new files.

* Reorganized the Sensitive Postman and curl examples for a better flow of content.
08/08/2022 v3.1 * Updated to clarify the use of Controlled Unclassified Information (CUI) data.
03/13/2023 v3.2 * Deleted the MPIN row from the “SAM Master Extract Mapping” file.

* Updated row # 288 (which used to track MPIN) in the “Sensitive Extract Layout” file to indicate that the field is deprecated.

* Removed the MPIN value from the sample “Sensitive Monthly V3 Extract File”.
06/27/2023 v3.3 * Updated “Effective April 2022” to “Effective June 2023”.

* Updated the “June 2023 release: SAM Master Extract Mapping” STRING Clarification tab to include the following updates:
 1. NAICS Exception String table updated to reflect January 2023
 changes
 2. SBA Business Types String table updated to include new value:
 “A4- SBA Certified Small Disadvantaged Business”
09/11/2023 v3.4 * Removed “SAM Master Extract Mapping document”.

12/01/2023 v3.5 A new FASCSA Order Exclusions Extract has been created, and the V1 Extracts Download API is now enabled to download this extract. As part of this change, below are the associated changes made to this OpenGSA page:

* Updated the Extract Calendar to include information on the new FASCSA extract.

* Updated the Query String Parameters section to reflect an example FASCSA extract file name.

* Updated the Extract Mapping Document and Layouts section with a new FASCSA Exclusions extract layout document.

* Updated the Sample Extract File Names with sample FASCSA Exclusions File Names.

* Updated the Extract Download API Sample Requests section with a sample request for a FASCSA extract.

* Updated the Sample Extract Files section with a new FASCSA Order Exclusions Public extract file.

Back to top