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

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 >
  
  

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

Back to top

API Description

Extracts Download API Parameters

Entity Management Extract Query String Parameters.

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

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:

• 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
  

Back to top

HTTP Response Codes

The API will return one of the following responses:

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

Back to top