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.
- 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
- 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
- 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.
- 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. |
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 >
- 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 |
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
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
Sample Extract Files
Extract files with UEI Information:
- Click to view Public Monthly V2 Extract File
- Click to view FOUO Monthly V2 Extract File
- Click to view Sensitive Monthly V3 Extract File
- Click to view Exclusions Public V2 Extract File
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. |
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]
- Before contacting the help desk, conduct your own initial troubleshooting
- 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.
- Navigate to www.fsd.gov
- Sign into the FSD platform using your FSD credentials
- Select “Create an Incident”
- Create an Incident
- System Name: System for Award Management (SAM)
- Is this related to the American Rescue Plan Act?: No
- Issue Type: Other
- Business Type: Other
- Subject (select 1):
- Option A: I need a role to test in alpha.sam.gov.
- Option B: System account approval in alpha.sam.gov
- Please describe the issue: (Copy and paste the below information into the ticket, filling in your information within the brackets)
- 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.
- 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].
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. |