Overview

The Extracts Download API permits beta.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 beta.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.
    • 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.
    • 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 beta.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.

Back to top

Getting Started

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

  • Beta: https://api.sam.gov/prod/dataservices/v1/extracts?api_key= < value >
  • Alpha: https://api-alpha.sam.gov/prodlike/dataservices/v1/extracts?api_key= < value >

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

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

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, April 2019 (fileName):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileName=SAM_PUBLIC_MONTHLY_20190407.ZIP

Monthly File, April 2019 (parameter):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=PUBLIC&frequency=MONTHLY&date=04/2019

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

Expected Result:
Click to view the full details of the data elements: Public Extract Layout

Entity Management FOUO Data Package Sample API calls:

Daily File, April 20, 2019 (fileName):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileName=SAM_FOUO_DAILY_20190420.ZIP

Daily File, April 20, 2019 (parameter):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=FOUO&frequency=DAILY&date=04/20/2019

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

Monthly File, April 2019 (fileName):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileName=SAM_PUBLIC_MONTHLY_20190407.ZIP

Monthly File, April 2019 (parameter):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=FOUO&frequency=MONTHLY&date=04/2019

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

Expected Result
Click to view the full details of the data elements: FOUO Extract Layout

Entity Management Sensitive Data Package Sample API calls:

Daily File, April 20, 2019 (fileName):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileName=SAM_SENSITIVE_DAILY_V2_20190420.ZIP

Daily File, April 20, 2019 (parameter):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=SENSITIVE&frequency=DAILY&date=04/20/2019

Daily File (UTF-8), April 20, 2019 (parameter):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=SENSITIVE&frequency=DAILY&date=04/20/2019&charset=UTF8

Monthly File, April 2019 (fileName):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileName=SAM_SENSITIVE_MONTHLY_V2_20190407.ZIP

Monthly File, April 2019 (parameter):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=SENSITIVE&frequency=MONTHLY&date=04/2019

Monthly File (UTF-8), April 2019 (parameter):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileType=ENTITY&sensitivity=SENSITIVE&frequency=MONTHLY&date=04/2019&charset=UTF8

Expected Result
Click to view the full details of the data elements: Sensitive Extract Layout

Exclusions Public Data Package Sample API calls:

Daily File, April 16, 2019 (fileName):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileName=SAM_Exclusions_Public_Extract_19106.ZIP

Daily File, April 16, 2019 (parameter):
https://api.sam.gov/prod/dataservices/v1/extracts?api_key={API_KEY}&fileType=EXCLUSION&date=04/16/2019

Expected Result: The layout of the Exclusions extract is available here: [TBD]

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

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
403 API key is not correct or was not provided.

Back to top

Contact Us

Back to top

Change Log

Date Version Description
06/03/2019 v 1.0 Base Version
08/15/2019 v 1.1 * Added Beta.SAM.Gov to the page title.

* Clarified the Alpha and Beta endpoints.

Back to top