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

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

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:
SAM Master Extract Mapping

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

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:
   • Click to view Public Monthly V1 Extract File
   • Click to view FOUO Monthly V1 Extract File
   • Click to view Sensitive Monthly V2 Extract File
     
     
2. Updated Version of 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