####Updated on October 30, 2015 The SAM team is happy to introduce v4 of the standard API and some updates to the v2 of the Search API. The updated field references for v4 can be found here. We are also announcing that support for v1 and v2 will cease as of this release. We will continue to support only the latest 2 current versions of the API (v3 and V4). That being said, v1 and v2 will still be available for use, but we cannot provide resources for ongoing support as we would like to enhance the system for everyone’s availablilty and not dwell on outdated versions. If there are any questions or issues, please visit the Support and Feedback to open a ticket.

####Updated on June 26, 2015 The SAM API has a release of v3 of the standard API and release of v2 of the search API. The updated field references can be found here. Another new page which contains a better overview of the changes can be found in our Versioning document.

The latest version of our Data Dictionary is available for download which will give a deeper look into the SAM system and how it functions.

Background

The SAM API is a RESTful method of retrieving public information about the businesses or individuals (referred to as “entities”) within the SAM data set. The entities publicly available data set can currently be retrieved on an entity-by-entity basis. The initial SAM API release was introduced in June 2014 and allowed users of the API to retrieve publicly available entity data. The next iteration of the API, released in fall 2014, provided the ability to search SAM to find an entity based on the search criteria submitted.
In addition to the entity information, we also provide status and progress information. This information is also included as part of the front end feature for the SAM Status Tracker. The status refers to the status of the entity’s registration - whether they are working on their registration, waiting for a validation from the IRS or the DoD (CAGE), or are active, as an example. The progress is most relevant for those who are working on their registration; it indicates whether a user has finished filling out different sections of their registrations, as well as the progress of their validations with external organizations such as the IRS or DoD. This should indicate how far along in the process a user is in completing the work they need to do in order to successful be registered in SAM.
Access to the SAM API is administered through the API.Data.Gov which is an API management service federal agencies.  Consumers of the SAM data must first register and obtain a key from the site.  The key will allow users to access the SAM APIs.

SAM getData API

The SAM getData API has one operation. The operation will retrieve an entity’s public information. Its endpoint is https://api.data.gov/sam/v1/registrations/
Please note: the rate limits for the API are currently 5,000 calls per 24 hours and 5 calls per 5 seconds. As we go forward and understand the impact of usage of the API on SAM, we will adjust the limits accordingly as well as allow for individual users with specific needs to have customized rate limits appropriate to their use.

Version 1 (v1)

The getData v1 SAM API includes:

  • Added Core Data, Assertions, and Points of Contact information.  Please note that optional fields that have not been completed by the registrant are not returned in the API response.
    • Fields from Core Data include:
      • activationDate, businessStartDate, businessTypes, cage, cageRejectionReason, companyDivision, congressionalDistrict, corporateStructureCode, corporateStructureDescription, corporateUrl, correspondenceFlag, countryOfIncorporation, creditCardUsage, divisionNumber, dodaac, doingBusinessAsName, duns, dunsPlus4, expirationDate, fiscalYearEndCloseDate, hasDelinquentFederalDebt, hasKnownExclusion, lastUpdateDate, legalBusinessName, mailingAddress, publicDisplay, purposeOfRegistration, qualifications, registrationDate, samAddress, stateOfIncorporation, status, statusMessage, submissionDate
    • Fields from Assertions include:
      • disasterRelief, type, geographicalAreas, metropolitanStatisticalArea, county, naics, isPrimary, naicsCode, naicsName, pscCodes, pscName, pscCode,
    • Fields from Points of Contact include:
      • altElectronicBusinessPoc, altGovtBusinessPoc, altPastPerformancePoc, electronicBusinessPoc, govtBusinessPoc, pastPerformancePoc

Version 2 (v2)

The following updates have been applied:

  • Added Reps and Certs data; identified as “certifications” object
    • Fields include from Reps and Certs include:
      • farResponses, dfarResponses, id, answers, answerText, answerId, section

Version 3 (v3)

The following updates have been applied:

  • Added FAR 52.204-17, which deals with CAGE Ownership of Offeror Information
    • Includes the addition of Immediate Owner and Highest Level Owner
  • Added 2 digit state code in conjunction with Congressional District code for clarity
    • E.g. congressionalDistrict: “DC 98”
  • Removed answerId that were sporadically appearing in the certifications object
    • Identified answerId as an optional string and cleared for removal
  • Revised field name for country within the address string to  be tagged consistently as “countryCode”
  • Resolved instances where an http (error code 500) error is thrown when a batch is ran with a single one duns being included multiple times within the batch
    • No error is being thrown
  • Resolved instances where an http (error code 500) error is thrown for historical registrations that are missing a value for congressional district
    • The congressional district string appears as null
  • Resolved instances where an http (error code 500) error is thrown when a DUNS is missing mandatory data elements
    • The mandatory data elements appear as null
  • Resolved an issue that if the Doing Business As name has a “[“ or “]” it returns as an array
    • doingBusinessAs now returns as a string, not an array
  • Resolved an issue where Small Business indicator were returning a null for farResponses
    • Now displays a “Y” or “N” to indicate Small Business status

Version 4 (v4)

The following updates have been applied:

  • Enhanced API getData return by adding 2 modular options to return either all values (inclusive of “null” values) or responded elements
    • Full - https://api.data.gov/samdata/v4/registrations/XXXXXXXXX0000?return_values=full
    • Responded - https://api.data.gov/samdata/v4/registrations/XXXXXXXXX0000?return_values=responded
  • Added Architect-Engineer Response (SF 330 Part II)
    • Nested under “qualifications” and “acass”
  • Added Bonding Information from Disaster Response page. Contains four bonding levels
    • Nested under “bondingInformation”
  • Added Address Line 2 for every address object
    • Address Line 2 is found under the field element “line2”
  • Revised 52.203-2 data return of the POC. On the front end, there is one text field to input a first and last name. In the API, there are 2 fields: firstName and lastName
    • firstName populates the first word while the lastName populates the last word
  • Revised a few fields for DFAR 252.209-7002 to provide more clarity to a user
    • “name” was changed to “controlledEntityName”
    • “mi” was changed to “middleInitial”
  • Revised all address objects to include fields that were not being returned. Also revised formatting for consistency throughout the API
    • Fields being returned are now “line1”, “line2”, “city”, “countryCode”, “zip”, “zipPlus4”
  • Resolved an issue for 52.214-14 where the ownerAddress and FacilityAddress was only returning/copying the last entered facility and addresses.
    • Now returns each distinct facility if the entity has multiple facility addresses
  • Resolved instances where the notes section of a Point of Contact was not being displayed

SAM searchData API

The SAM Search API has been developed to mimic the Search functionality that is currently available from the SAM website. The Search API provides the opportunity to perform a search transaction in the following two options. Quick Search takes a single search term provided by the user and compares it to a set of predefined database fields. Advanced Search allows the user to search by entering a value that is then used to search a user selected predefined search category.
Notice that the searchData is through a JSON-based “hypermedia as the engine of application state” (HATEOAS with the appropriate links object within the result set). The intent going forward will be to use this model to allow for a scalable architecture of IAE’s APIs to be built.

Version 1 (v1)

The following updates have been applied:

  • Added Advanced Search features which allows users to search by specific fields
    • Fields added to the Advanced Search include:
      • legalBusinessName, status, duns, dunsPlus4, hasKnownExclusion, expirationDate, samAddress, cage, dodaac, hasDelinquentFederalDebt

Version 2 (v2)

The following updates have been applied:

    • Added ability to check companies that were added/updated /expired between 2 dates
      • Will use the following format
        • expirationDate:[2015-01-01,2015-05-05]
        • updateDate:[2015-01-01,2015-05-05]
        • createDate:[2015-01-01,2015-05-05]
        ##### Get started We organized this site into four major areas. - [API basics](basics.html) introduces you to the operations offered by the API. - [API calls](console/) gives you a hands-on experience of those operations with an interactive console. - [Field reference for v4](fields4.html) lists and describes the type of information provided by the API. - [Feedback](https://github.com/GSA/GSA-APIs/issues) provides a forum for developers to share feedback and report problems.