Overview

The Extracts Download API permits SAM.gov users with valid roles to download entity and exclusions data extracts.

The Entity Management extracts contain entities (businesses and government agencies) data from SAM.gov. The Exclusions extract contains a list of all parties with a currently active exclusion in SAM.

  1. Entity Management Public Data Package:
    • This extract contains entity registration data publicly available under the Freedom of Information Act (FOIA) for those registered in SAM.gov to do business with the Federal government.
    • All entities and data elements are classified as public.
    • End user needs to create an account in SAM.gov and procure an API_KEY to access these extracts.
    • File naming convention:
      Monthly ASCII : SAM_PUBLIC_MONTHLY_V2_YYYYMMDD.ZIP
      Monthly UTF-8 : SAM_PUBLIC_UTF-8_MONTHLY_V2_YYYYMMDD.ZIP
  2. Entity Management Extracts FOUO (For Official Use Only) Data Package:
    • This extract contains the same information as the Entity Management Public Data Package, plus data elements which are classified as For Official Use Only (FOUO).
    • The monthly extract is published on the first Sunday of the month and contains all active registrations plus registrations with an expiration date within the past 6 months.
    • The daily extract is an incremental file which is published 5 days a week (Tuesday – Saturday) and contains all new, updated, and deactivated registrations since the previous daily file.
    • End user needs to create a system account with FOUO access roles and procure an API_KEY to access these extracts.
    • Only system account keys can be used to access FOUO data.
    • File naming convention:
      Daily ASCII : SAM_FOUO_DAILY_V2_YYYYMMDD.ZIP
      Daily UTF-8: SAM_FOUO_UTF-8_DAILY_V2_YYYYMMDD.ZIP
      Monthly ASCII : SAM_FOUO_MONTHLY_V2_YYYYMMDD.ZIP
      Monthly UTF-8 : SAM_FOUO_UTF-8_MONTHLY_V2_YYYYMMDD.ZIP
  3. Entity Management Extract Sensitive Data Package:
    • This extract contains the same information as the Entity Management FOUO Data package with the addition of data elements which are classified as Sensitive.
    • The monthly extract is published on the first Sunday of the month and contains all active registrations plus registrations with an expiration date within the past 6 months.
    • The daily extract is an incremental file which is published 5 days a week (Tuesday – Saturday) and contains all new, updated, and deactivated registrations since the previous daily file.
    • End user needs to create a system account with sensitive access roles and procure an API_KEY to access these extracts.
    • Only system account keys can be used to access Sensitive data.
    • File naming convention:
      Daily ASCII : SAM_SENSITIVE_DAILY_V3_YYYYMMDD.ZIP
      Daily UTF-8: SAM_SENSITIVE_UTF-8_DAILY_V3_YYYYMMDD.ZIP
      Monthly ASCII : SAM_SENSITIVE_MONTHLY_V3_YYYYMMDD.ZIP
      Monthly UTF-8 : SAM_SENSITIVE_UTF-8_MONTHLY_V3_YYYYMMDD.ZIP
    • This extract requires IP address whitelisting to download your file. You will need to keep an up-to-date list of your IP addresses in your System Account.
  4. Exclusions Public Data Package:
    • This extract all active exclusions in SAM as a comma-separated value (CSV) file.
    • The Exclusions extract is a daily file, published 7 days per week.
    • End user needs to create an account in SAM.gov and procure an API_KEY to access these extracts.
    • File naming convention:
      SAM_Exclusions_Public_Extract_V2_YYDDD.ZIP (YYDDD is the Julian Date)
      Example: The file for 04/06/2022 would be SAM_Exclusions_Public_Extract_V2_22096.ZIP.

Entity Extract Calendar

Monthly Files for Public, FOUO and Sensitive Extracts * They are produced on the first Sunday of each month. Kindly check after 7 AM.
* 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.
Daily Files for FOUO and Sensitive Extracts * They are produced every Tuesday-Saturday. Kindly check after 7 AM.
* The date on the .ZIP 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.
Daily Files for Exclusion Extracts * They are produced every day. Kindly check after 7 AM.
* The date on the .ZIP 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 exclusions.

Back to top

Getting Started

The Public and FOUO Entity extracts and Exclusion extracts are available using the following endpoints:

  • Production: https://api.sam.gov/data-services/v1/extracts?api_key= < value >
  • Alpha: https://api-alpha.sam.gov/data-services/v1/extracts?api_key= < value >

The Sensitive version of the extracts are available via POST requests. Please refer to the “Sensitive Download API Process” to learn more about the Sensitive extract retrieval process.
  • Production: https://api.sam.gov/data-services/v1/extracts?
  • Alpha: https://api-alpha.sam.gov/data-services/v1/extracts?

Generating a personal API Key:

  • Registered users can request for a public API on ‘Account Details’ page. This page can be accessed here: Account Details page on SAM.gov
  • Users must enter their password on ‘Account Details’ page to view the API Key information. If an incorrect password is entered, an error will be returned.
  • After the API Key is generated on ‘Account Details’ page, the API Key can be viewed on the Account Details page immediately. The API Key is visible until users navigate to a different page.
  • If an error is encountered during the API Key generation/retrieval, then users will receive an error message and they can try again.

Generating a System Account API Key:

  • Users registered with a non-government email address and associated with an entity OR users registered with a government email address may request a system account for public data access.
  • If a user satisfies the above registration criteria they will be able to access the System Accounts widget from their Workspace page after logging in.
  • The user can then select ‘Go to System Accounts’ from the widget and fill out the required sections.
  • The requested system account will then need to be approved. After approval the user will be notified via email and they can also see the updated status in the System Account widget.
  • The user can select ‘Go to System Accounts’ again in the widget from their workspace and enter a new system account password.
  • After setting up the password the user will see a new section for retrieving a system account API Key.
  • The user must enter their password again to retrieve the key.
  • The user must maintain accurate IP addresses in their System Accounts, particularly if they are downloading the Entity Management Sensitive Data Package.

Type of Connections and Rate Limits

Connecting Source Type of Connection Default Rate Limit
Non-federal user with no role Personal API key 10 requests/day
Non-federal user with a role Personal API key 1,000 requests/day
Federal User Personal API key 1,000 requests/day
Non-federal system System account API key 1,000 requests/day
Federal system System account API key 10,000 requests/day

Back to top

API Description

Extracts Download API Parameters

Entity Management Extract Query String 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
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, FOUO, SENSITIVE
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.

Sensitive Download API Process

  • All requests must be sent as POST calls using clients like Postman. These requests cannot be sent through browsers.
  • 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 Sensitive api_key parameter with its value must be sent in the “Headers” as “x-api-key” and not directly in the request URL.
  • “Accept” parameter must be passed in “Headers” with value, “application/zip”.
  • “Content-Type” parameter must be passed in “Headers” with value, “application/json”.
  • 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

Explanation of the API using Examples

The api_key parameter is required for identification and role-based access control. After the api_key, there are query paths to download the correct file:

Option 1: Using the fileName only. The fileName is an exact match parameter which can be used for any type of file. If you use the fileName parameter, no other parameters are required and will be ignored if included.

Option 2: Using fileType and other parameters. If you choose not to use the fileName, you may specify the fileType along with other parameters to identify which extract you wish to download.

Please refer to the SAM Master Extract Mapping document:
Before April 2022: SAM Master Extract Mapping
Effective April 2022: SAM Master Extract Mapping

Entity Management Public Data Package Sample API calls:

  • 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

Expected Result:
Click to view the full details of the extract layout with the UEI data: Public Extract Layout

Entity Management FOUO Data Package Sample API calls:

  • 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

Expected Result
Click to view the full details of the extract layout with the UEI data: FOUO Extract Layout

Entity Management Sensitive Data Package Sample API calls:

  • 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

Expected Result
Click to view the full details of the extract layout with the UEI data: Sensitive Extract Layout

Exclusions Public Data Package Sample API calls:

  • 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

Expected Result: Click to view the full details of the extract layout with the UEI data: Exclusions Extract Layout

Sample File Names:

  • FOUO 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 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 files:
    SAM_PUBLIC_UTF-8_MONTHLY_V2_20220403.ZIP
    SAM_PUBLIC_MONTHLY_V2_20220403.ZIP

  • Exclusion files:
    SAM_Exclusions_Public_Extract_V2_22096.ZIP
    SAM_Exclusions_Public_Extract_V2_22097.ZIP

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.

Back to top