UEI Technical Specifications and API Information
Many systems outside of the GSA interface with award data and information, includingdata. To help our partners across the federal government and the public, we have published all of the updated UEI/EVS technical specifications for interfacing systems. Technical teams can finalize plans to accommodate these interface changes and continue the development required to test with IAE.
A unique number for businesses and required in order to do business with the federal government. By April of 2022, GSA is expected to automatically assign entities registered in SAM a unique entity identifier.
Group 1 includes:
- The beta.SAM.gov Entity Management API has updated schemas for what will be a second version of the API. This API allows interfacing systems to pull information about the entity via an automated process. Field differences between versions are marked as v1 (current version) or v2 (future version). Go to the Entity Management API page to find the specifications.
- The SAM Entity Management Web Services will not be updated to incorporate UEI or new EVS changes. All users of this web service will need to migrate to the beta.SAM.gov Entity Management API to retrieve UEI and new EVS information.
- The SAM public RESTful API will not be updated to incorporate UEI or new EVS changes. All users of this RESTful API will need to migrate to the beta.SAM.gov Entity Management API to retrieve UEI and new EVS information
Group 2 includes:
- The beta.SAM.gov Exclusions API has updated schemas for what will be a version 2 of the API. This API allows interfacing systems to pull information about the exclusions via an automated process. Field differences between versions are marked as v1 (current version) or v2 (future version). Go to the Exclusions API page to find the specifications.
- The SAM Exclusions Search Web Services will not be updated to incorporate UEI or new EVS changes. All users of this web service will need to migrate to the beta.SAM.gov Exclusions API to retrieve UEI and new EVS information regarding exclusions via interface.
Group 3 includes:
- Legacy SAM has updated schemas for what will be version 3 of the Sensitive Entity Extract and versions 2 of the Public Entity, FOUO Entity, and Exclusions Extracts. These extracts allow interfacing systems and users to pull information about registered entities and exclusions in bulk. Go to SAM News and Announcement page to obtain the specifications in the SAM announcements section.
- FPDS has updated information for UEI in the web services and specifications for v1.1 of the FAADC services. Contract award data web services will utilize four of the generic string tags that were built into v1.5 as follows:
- genericString02 - Awardee UEI
- genericString03 - Immediate Parent UEI
- genericString04 - Domestic Parent UEI
- genericString05 - Global Parent UEI
- Interfacing systems will submit genericString02 on CAR submissions. Generic Strings 03,04, and 05 would be populated within FPDS and available for pulling data via the atom feeds and web services (as appropriate for system access).
- FPDS web service specifications are available at the FPDS worksite here.
- FAADC web service specifications are available at the FPDS worksite as follows:
- Atom feed specifications are available at:
Group 4 includes:
- Legacy SAM has updated schemas for new versions of the Exclusions XML Uploader which allows bulk upload of exclusions. The updated schemas are in the deployment pipeline to be posted on SAM.gov's Announcement page. Go to SAM.gov's Announcement page to obtain the specifications in the SAM announcements section.
- Beta.SAM Opportunities Management APIs
Beta.SAM Opportunities Management APIs updates are in the deployment pipeline for publication on Open GSA with updated information on UEI-related fields used in Opportunities API operations.
- Beta.SAM Opportunities SOAP Services (outdated link removed)
Beta.SAM Opportunities SOAP Services will not be updated to incorporate UEI or new EVS changes. All users of these SOAP services will need to migrate to the beta.SAM Opportunities REST APIs to submit and retrieve UEI information via interface.
- Updated information about UEI in the Opportunities Publics API is currently available on Open GSA.
Please view the IAE’s EntityID Webinar which contains the history of this effort. Questions received at the public meeting held on July 25, 2019 have answers provided here [PDF - 141 KB]. Watch this page as questions and answers about the transition will be posted here. User questions specific to the testing of these interfaces should be directed to email@example.com. Users who have specific questions regarding the SAM-generated UEI or entity validation services should reach out to firstname.lastname@example.org.
The standard for the new unique Entity ID has been published in the Federal Register.
The new UEI is stored as a 12-character, alpha-numeric value within databases and passed as such within interfaces and extracts. This 12-character value will adhere to the following rules:
- The letters “O” and “I” will not be used to avoid confusion with zero and one.
- The first character will not be zero to avoid cutting off digits that can occur during data imports, for example, when importing data into spreadsheet programs.
- Nine-digit sequences will not be used in the identifier to avoid collision with the nine-digit DUNS number or Taxpayer Identification Number (TIN).
- The first five characters will be structured to avoid collision with the Commercial and Government Entity code formatting or CAGE code.
- The UEI will not be case sensitive.
- The final character will be a checksum of the first 11 characters. Checksums are used to detect errors within data.
- The UEI will not contain the entity’s Electronic Funds Transfer (EFT) Indicator. The EFT Indicator will remain a separate field in SAM.gov.
- Today the “EFT Indicator” in SAM.gov is labeled “DUNS+4”.
- The DUNS+4 field in SAM.gov is used to identify additional bank accounts associated with a single SAM.gov registration. The DUNS+4 is a separate field from the DUNS field in SAM.gov.
- The DUNS+4 is not provided by D&B but is determined by the entity during registration.
- Soon, the DUNS+4 field name in SAM.gov will be re-labeled to “EFT Indicator” to align with regulations. The DUNS+4 data provided by entities in that field will not change with the re-labeling.
- Additionally, when a new UEI is assigned to an entity registration in SAM.gov, the existing EFT Indicator data will not change.
Samples of the new extract versions including the UEI and examples of the new API versions are available as reference material for interfacing systems and consumers of registration data. The samples are available as follows:
- Entity/exclusion extracts (Public v2, FOUO v2, Sensitive v2)
- Entity Management API v2
- Exclusions API v2
- Opportunities Management API v2
The testing timeframes for the new UEI-based APIs and extracts are in the chart below. Specifications and sample test data have been provided to facilitate interfacing system development for the new UEI.
|Interface||Testing Time Frame|
|Beta.SAM Entity Management API v2||Mid-May to June 2020|
|Beta.SAM Exclusions API v2||Mid-May to June 2020|
|Beta.SAM Opportunities APIs v2||June 2020|
|SAM Extracts Public v2, FOUO v2, Sensitive v3||July to August 2020|
|SAM Exclusions Extract v2||July to August 2020|