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 (Default): SAM_PUBLIC_MONTHLY_YYYYMMDD.ZIP
      Monthly UTF-8 (Default): SAM_PUBLIC_UTF-8_MONTHLY_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.
    • Daily ASCII (Default): SAM_FOUO_DAILY_YYYYMMDD.ZIP
      Daily UTF-8: SAM_FOUO_UTF-8_DAILY_YYYYMMDD.ZIP
      Monthly ASCII (Default): SAM_FOUO_MONTHLY_YYYYMMDD.ZIP
      Monthly UTF-8 (Default): SAM_FOUO_UTF-8_MONTHLY_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.
    • Daily ASCII (Default): SAM_SENSITIVE_DAILY_V2_YYYYMMDD.ZIP
      Daily UTF-8: SAM_SENSITIVE_UTF-8_DAILY_V2_YYYYMMDD.ZIP
      Monthly ASCII (Default): SAM_SENSITIVE_MONTHLY_V2_YYYYMMDD.ZIP
      Monthly UTF-8 (Default): SAM_SENSITIVE_UTF-8_MONTHLY_V2_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 Name: SAM_Exclusions_Public_Extract_YYDDD.ZIP (Julian Date)
      * April 16, 2019 is the 106th day of 2019. Therefore, the Exclusions extract for April 16, 2019 would be SAM_Exclusions_Public_Extract_19106.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 March monthly files were generated and dated on 20210307.
* The date on the .ZIP file matches the date on the .dat file inside.
* These files contain all active entities + 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 the last Saturday of March will show 20210327.
* 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.

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 no longer available via GET 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?fileName=< name of the file >
  • Alpha: https://api-alpha.sam.gov/data-services/v1/extracts?fileName=< name of the file >

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 Personal 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 Required element to identify API users and validate role-based access
fileName Allows users to provide extract file name
The fileName parameter must be used if the sensitivity parameter is not used.
Example: fileName=SAM_PUBLIC_MONTHLY_20190323.ZIP
fileType Allows users to specify the domain of the extract that they wish to download
The filetype parameter must be used if fileName is not specified.
Permitted values: ENTITY, EXCLUSION, SCR, BIO
sensitivity Allows users to provide the desired sensitivity level of the extract that they wish to download, if they have proper roles
The sensitivity parameter must be used if fileName parameter is not used.
Default value: PUBLIC
Permitted values: PUBLIC, FOUO, SENSITIVE
frequency Allows users to request either a DAILY or MONTHLY extract
Default value: MONTHLY
Permitted values: DAILY, MONTHLY
charset Allows users to request either the ASCII or UTF-8 extract character-set
Default value: ASCII
Permitted values: ASCII, UTF8, UTF-8
Note: This parameter is not applicable for the EXCLUSION file type.
date Allows users to select a specific date of the file that they wish to download.
Format: MM/DD/YYYY for a specific date of MM/YYYY to specify a year and month (for MONTHLY files only)
Default value: Most recent date, depending on fileType
Examples: 04/19/2019; 11/15/2018; 03/2019
version Allows users to select the file they wish to download by version.
Default value: Most recent version, depending on fileType and/or sensitivity
Examples: V1; V2; V3

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”.

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.

Entity Management Public Data Package Sample API calls:

Monthly File, Version 1, April 2019 (fileName):
https://api.sam.gov/data-services/v1/extracts?api_key={API_KEY}&fileName=SAM_PUBLIC_MONTHLY_20190407.ZIP

Monthly File, Version 1, April 2019 (parameter):
https://api.sam.gov/data-services/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=PUBLIC&frequency=MONTHLY&date=04/2019&version=V1

Monthly File (UTF-8), Version 1, April 2019 (parameter):
https://api.sam.gov/data-services/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=PUBLIC&frequency=MONTHLY&date=04/2019&charset=UTF8&version=V1

Expected Result:
Click to view the full details of the data elements: Public Extract Layout
Click to view the full details of the revised extract layout for the upcoming UEI/EVS changes:Public Extract Layout

Entity Management FOUO Data Package Sample API calls:

Daily File, Version 1, April 20, 2019 (fileName):
https://api.sam.gov/data-services/v1/extracts?api_key={API_KEY}&fileName=SAM_FOUO_DAILY_20190420.ZIP

Daily File, Version 1, April 20, 2019 (parameter):
https://api.sam.gov/data-services/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=FOUO&frequency=DAILY&date=04/20/2019&version=V1

Daily File (UTF-8), Version 1, April 20, 2019 (parameter):
https://api.sam.gov/data-services/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=FOUO&frequency=DAILY&date=04/20/2019&charset=UTF8&version=V1

Monthly File, Version 1, April 2019 (fileName):
https://api.sam.gov/data-services/v1/extracts?api_key={API_KEY}&fileName=SAM_PUBLIC_MONTHLY_20190407.ZIP

Monthly File, Version 1, April 2019 (parameter):
https://api.sam.gov/data-services/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=FOUO&frequency=MONTHLY&date=04/2019&version=V1

Monthly File (UTF-8),Version 1, April 2019 (parameter):
https://api.sam.gov/data-services/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=FOUO&frequency=MONTHLY&date=04/2019&charset=UTF8&version=V1

Expected Result
Click to view the full details of the data elements: FOUO Extract Layout
Click to view the full details of the revised extract layout for the upcoming UEI/EVS changes:FOUO Extract Layout

Entity Management Sensitive Data Package Sample API calls:

Daily File, Version 2, April 20, 2019 (fileName):
https://api.sam.gov/data-services/v1/extracts?fileName=SAM_SENSITIVE_DAILY_V2_20190420.ZIP

Daily File, Version 2, April 20, 2019 (parameter):
https://api.sam.gov/data-services/v1/extracts?fileType=ENTITY&sensitivity=SENSITIVE&frequency=DAILY&date=04/20/2019&version=V2

Daily File (UTF-8), Version 2, April 20, 2019 (parameter):
https://api.sam.gov/data-services/v1/extracts?fileType=ENTITY&sensitivity=SENSITIVE&frequency=DAILY&date=04/20/2019&charset=UTF8&version=V2

Monthly File, Version 2, April 2019 (fileName):
https://api.sam.gov/data-services/v1/extracts?fileName=SAM_SENSITIVE_MONTHLY_V2_20190407.ZIP

Monthly File, Version 2, April 2019 (parameter):
https://api.sam.gov/data-services/v1/extracts?fileType=ENTITY&sensitivity=SENSITIVE&frequency=MONTHLY&date=04/2019&version=V2

Monthly File (UTF-8), Version 2, April 2019 (parameter):
https://api.sam.gov/data-services/v1/extracts?fileType=ENTITY&sensitivity=SENSITIVE&frequency=MONTHLY&date=04/2019&charset=UTF8&version=V2

Expected Result
Click to view the full details of the data elements: Sensitive Extract Layout
Click to view the full details of the revised extract layout for the upcoming UEI/EVS changes: Sensitive Extract Layout

Exclusions Public Data Package Sample API calls:

Daily File, Version 1, April 16, 2019 (fileName):
https://api.sam.gov/data-services/v1/extracts?api_key={API_KEY}&fileName=SAM_Exclusions_Public_Extract_19106.ZIP

Daily File, Version 1, April 16, 2019 (parameter):
https://api.sam.gov/data-services/v1/extracts?api_key={API_KEY}&fileType=EXCLUSION&date=04/16/2019&version=V1

Expected Result: Click to view the full details of the data elements: Exclusions Extract Layout
Click to view the full details of the revised extract layout for the upcoming UEI/EVS changes:Exclusions Extract Layout

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

Sample File Names:

The below sample files are for Alpha. Production has files from January 2020 onward.

  • FOUO files:
    SAM_FOUO_DAILY_20190423.ZIP
    SAM_FOUO_DAILY_20190522.ZIP
    SAM_FOUO_DAILY_20190523.ZIP
    SAM_FOUO_DAILY_20190524.ZIP
    SAM_FOUO_DAILY_20190525.ZIP
    SAM_FOUO_DAILY_20190528.ZIP
    SAM_FOUO_DAILY_20190529.ZIP
    SAM_FOUO_DAILY_20190530.ZIP
    SAM_FOUO_DAILY_20190531.ZIP
    SAM_FOUO_MONTHLY_20190430.ZIP
    SAM_FOUO_MONTHLY_20190505.ZIP
    SAM_FOUO_UTF-8_DAILY_20210204.ZIP
    SAM_FOUO_UTF-8_MONTHLY_20210204.ZIP
    SAM_FOUO_DAILY_V2_20200824.ZIP
    SAM_FOUO_MONTHLY_V2_20200826.ZIP
    SAM_FOUO_UTF-8_DAILY_V2_20200824.ZIP
    SAM_FOUO_UTF-8_MONTHLY_V2_20200826.ZIP

  • Sensitive files:
    SAM_SENSITIVE_UTF-8_DAILY_V2_20190530.ZIP
    SAM_SENSITIVE_UTF-8_DAILY_V2_20190531.ZIP
    SAM_SENSITIVE_UTF-8_DAILY_V2_20190601.ZIP
    SAM_SENSITIVE_UTF-8_DAILY_V2_20190523.ZIP
    SAM_SENSITIVE_UTF-8_DAILY_V2_20190524.ZIP
    SAM_SENSITIVE_UTF-8_DAILY_V2_20190525.ZIP
    SAM_SENSITIVE_UTF-8_DAILY_V2_20190528.ZIP
    SAM_SENSITIVE_UTF-8_DAILY_V2_20190529.ZIP
    SAM_SENSITIVE_UTF-8_DAILY_V2_20190522.ZIP
    SAM_SENSITIVE_DAILY_V2_20190606.ZIP
    SAM_SENSITIVE_MONTHLY_V2_20190602.ZIP
    SAM_SENSITIVE_DAILY_V2_20190525.ZIP
    SAM_SENSITIVE_DAILY_V2_20190528.ZIP
    SAM_SENSITIVE_DAILY_V2_20190529.ZIP
    SAM_SENSITIVE_DAILY_V2_20190530.ZIP
    SAM_SENSITIVE_DAILY_V2_20190531.ZIP
    SAM_SENSITIVE_DAILY_V2_20190601.ZIP
    SAM_SENSITIVE_DAILY_V2_20190604.ZIP
    SAM_SENSITIVE_DAILY_V2_20190605.ZIP
    SAM_SENSITIVE_DAILY_V2_20190524.ZIP
    SAM_SENSITIVE_UTF-8_DAILY_V2_20190604.ZIP
    SAM_SENSITIVE_DAILY_V2_20190523.ZIP
    SAM_SENSITIVE_MONTHLY_V2_20200826.ZIP
    SAM_SENSITIVE_DAILY_V2_20200827
    SAM_SENSITIVE_DAILY_V3_20200827.ZIP
    SAM_SENSITIVE_MONTHLY_V3_20200826.ZIP
    SAM_SENSITIVE_UTF-8_DAILY_V3_20200827.ZIP
    SAM_SENSITIVE_UTF-8_MONTHLY_V3_20200826.ZIP

  • Public files:
    SAM_PUBLIC_UTF-8_MONTHLY_V2_20200826.ZIP
    SAM_PUBLIC_MONTHLY_V2_20200826.ZIP
    SAM_PUBLIC_UTF-8_MONTHLY_V2_20210103.ZIP
    SAM_PUBLIC_MONTHLY_V2_20210103.ZIP
    SAM_PUBLIC_MONTHLY_20210103.ZIP
    SAM_PUBLIC_UTF-8_MONTHLY_20210103.ZIP
    SAM_PUBLIC_MONTHLY_20190407.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

  1. Existing Extract files:
  2. Updated Version of 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

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.

Back to top