SAM Search 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 we are implementing this 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.

Note: Don’t try to construct links yourself based on the patterns you see in the links object. Assume that those patterns could change. We will account for this requirement as we implement our rate-limiting for the API.

Searching SAM using the API

The Quick Search functionality allows a user to enter a single term which is then queried against six fields in the SAM database. The results should return the same entities, grantees, and other registrants in SAM that are found when you do a “Quick Search” on SAM itself.

Example: https://api.data.gov/sam/v1/registrations?qterms=GSA&api_key=DEMO_KEY The Search API will then query the SAM database and display any registrant that matches the user selected search term contained in any of the following fields:

Field
Legal Business Name
Doing-Business-As Name
DUNS
DUNS+4
CAGE Code
DoDAAC

Note that the search will automatically add a wildcard to the end of any term that is three or more charcters passed in quick search. So qterms=Rob will match “Robot Co., Inc.”

The Advanced Search functionality allows a user to enter criteria or a value and a category which is then used to query the database to return all registrations that match that selection criterion. In Advanced Search users are able to string multiple criteria and categories to better refine their search and return a more specific list of registrations.

Advanced Search uses the same qterms construct that we used for quick search, but follows more closely to the Lucene-based syntax for querying by specific terms. It is not exactly the same, but should be familiar for anyone who is used to that syntax.

As a basic example, if you want to make sure you’re searching only Legal Business Name, you can run the following search: https://api.data.gov/sam/v1/registrations?qterms=legalBusinessName:incorporated

The search terms will be in parentheses. You can group AND and OR search terms together by putting the terms AND or OR between terms, separated by + signs. For example a user can search for an entity that has a Legal Business Name that includes the term “incorporated” AND has selected the NAICS Code of 123456 for which they are considered to be a Small Business for. https://api.data.gov/sam/v1/registrations?qterms=(legalBusinessName:incorporated)+AND+(naicsLimitedSB:12345)

Advanced search results fields

The following are the fields you can search for using Advanced Search. Note that, where appropriate, we have used the same field name as the JSON output from the detailed results of the API. Some of them, like minorityOwned are interpreted appropriately.

Functional search fields

Functional Field

Definition

URL Search Field

Possible Search Terms

Legal Business Name

The name that has been registered for the organization at Dun and Bradstreet (D&B).

legalBusinessName

NOTE: This field also searches ‘Doing Business As Name’

Doing Business As Name

Doing Business As (DBA) is the commonly used other name, such as a franchise, licensee name, or an acronym for the entity. The DBA is also part of the registered name at D&B.

doingBusinessAs

NOTE: This field also searches ‘Legal Business Name’

CAGE/NCAGE code

The Contractor and Government Entity (CAGE) Code or NATO Commercial and Government Entity (NCAGE) Code. This number is assigned to the registration if one does not already exist.

cage

DUNS number

Data Universal Numbering System (DUNS) is a unique nine digit number that is administered by Dun and Bradstreet (D&B) and is a required data element for all registrants in SAM.

duns

Physical Address City

The city of the address registered for the entity at Dun and Bradstreet (D&B).

samAddress.city

Physical Address Country

The country of the address registered for the entity at Dun and Bradstreet (D&B).

samAddress.country

State

The state of the address registered for the entity at Dun and Bradstreet (D&B).

samAddress.stateOrProvince

Zip Code

The zip code of the address registered for the entity at Dun and Bradstreet (D&B).

samAddress.zip

Congressional District

An electoral division of a state based on the zip-code in the entity's physical address.

congressionalDistrict

NAICS - Limited SB

The North American Industry Classification System (NAICS) code represents the type of industry in which the entity does business. ‘Limited SB’ will return only entities which are considered small business but only for the NAICS selected by the registrant in their entity registration for the particular NAICS input into search field.

naicsLimitedSB

NAICS - Any Size

The North American Industry Classification System (NAICS) code represents the type of industry in which the entity does business. ‘Any Size’ will return all records (large and small business) for the particular NAICS input into search field.

naicsAnySize

Minority Owned Business

A minority business is defined as a business in which more than 51% of the interest, stock and otherwise, is owned by minority group members. If you select this category, you will need to select a subcategory that best represents the persons who hold primary ownership. Subcategories include Asian-Pacific American Owned, Subcontinent Asian (Asian Indian) Owned, Black American Owned, Hispanic American Owned, Native American Owned, or Other.

minorityOwned

true or false

Woman Owned Business

Woman-Owned Business means a business (1) that is at least 51 percent owned by one or more women; or, in the case of any publicly owned business, at least 51 percent of the stock of which is owned by one or more women; and (2) whose management and daily business operations are controlled by one or more women.

womanOwned

true or false

Veteran Owned Business

Veteran-Owned Business means a business that (1) not less than 51 percent of which is owned by one or more veterans (as defined at 38 U.S.C. 101(2)) or, in the case of any publicly owned business, not less than 51 percent of the stock of which is owned by one or more veterans; and (2) the management and daily business operations of which are controlled by one or more veterans. For more information please see:

http://www.gpo.gov/fdsys/pkg/USCODE-2011-title38/pdf/USCODE-2011-title38.pdf.

veteranOwned

true or false

Service Disabled Veteran Owned

Service Disabled Veteran Owned Business means a business that (i) not less than 51 percent of which is owned by one or more service-disabled veterans or, in the case of any publicly owned business, not less than 51 percent of the stock of which is owned by one or more service-disabled veterans; and (ii) the management and daily business operations of which are controlled by one or more service-disabled veterans or, in the case of a service-disabled veteran with permanent and severe disability, the spouse or permanent caregiver of such veteran. “Service-disabled veteran” means a veteran, as defined in 38 U.S.C. 101(2), with a disability that is service-connected, as defined in 38 U.S.C. 101(16). For more information please see: http://www.gpo.gov/fdsys/pkg/USCODE-2011-title38/pdf/USCODE-2011-title38.pdf

serviceDisabledVeteranOwned

true or false

SBA Certified 8A Program

An SBA program for small concerns owned by socially and economically disadvantaged persons.

Firms admitted to the program can receive Federal contracts designated for 8(a) Business Development Program participants, as well as management and technical assistance.

For more information please see: http://www.sba.gov/content/8a-business-development-0

sba8AProgram

true or false

SBA Certified HUBzone Program

The Historically Underutilized Business Zones (HUBZone) program helps small businesses in urban and rural communities gain preferential access to federal procurement opportunities. These preferences go to small businesses that obtain HUBZone certification in part by employing staff who live in a HUBZone. The company must also maintain a "principal office" in one of these specially designated areas.

For more information please see: http://www.sba.gov/content/hubzone-0

sbaHubzoneProgram

true or false

AbilityOne Certified

The AbilityOne Program is the largest single provider of jobs for people who are blind or have other significant disabilities in the United States. The AbilityOne Program uses the purchasing power of the federal government to buy products and services from participating, community-based nonprofit agencies nationwide dedicated to training and employing individuals with disabilities.

ability1

true or false

Purpose of Registration

The value that indicates what type of business the entity intends to do with the government (Contracts, Grants and Federal Assistance, Intra-Governmental Transactions).

purpose

See codes below

Registration Status

The current status of the registration as it appears in SAM.

registrationStatus

See codes below

Disaster Response Contractor

Those contractors who are willing to provide debris removal, distribution of supplies, reconstruction, and other disaster or emergency relief supplies and/or services.

disasterResponse

true or false

Codes for Purpose of registration
  • Z1 - Federal AssistanceAwards
  • Z2 - All Awards
  • Z4 - AssistanceAwards & IGT
  • Z5 - All Awards & IGT
Codes for registration status
  • A - Active
  • W - Work in Progress
  • S - Submitted
  • I - Inactive

API Search Output:

The search results that match the searched condition will be displayed in JSON format and include the following data elements:

Advanced Search Fields

Field Name:

Definition:

Representation in Output:

Legal Business Name

The name that has been registered for the organization at Dun and Bradstreet (D&B).

"legalBusinessName":

Status

The current status of the registration as it appears in SAM. Options are: Draft, Work In Progress, Submitted, Active, Inactive.

"status":

DUNS

Data Universal Numbering System (DUNS) is a unique nine digit number that is administered by Dun and Bradstreet (D&B) and is a required data element for all

registrants in SAM.

"duns":

DUNS +4

The DUNS+4 is a user generated four digit number created if the registered entity only has one physical location but more than one bank account.

"dunsPlus4”:

Has Active Exclusion

True or False value depending on whether the entity has had Exclusion created against it or not.

"hasKnownExclusion":

Expiration Date

The date that the entity registration will expire if the user does not update his/her registration. Registrations must be updated every 360 days to remain Active.

"expirationDate":

Physical Address

The address registered for the entity at Dun and Bradstreet (D&B).

“samAddress":

CAGE/NCAGE Code

The Contractor and Government Entity (CAGE) Code or NATO Commercial and Government Entity (NCAGE) Code. This number is assigned to the registration if one does not already exist.

"cage":

DODAAC

The Department of Defense Activity Address Code (DoDAAC). This is applicable for the Department of Defense (DoD) entities only.

“dodaac”:

Delinquent Federal Debt Indicator

True or False value based on whether the Department of Treasury has indicated the entity has Delinquent Federal Debt or not.

"hasDelinquentFederalDebt":

The JSON result will return as follows:

{"results":[
  { "hasKnownExclusion":false,
    "samAddress": 
       { "zip": "12345",
         "zip4": "3800",
         "stateOrProvince": "IL",
         "line1": "1234 M St",
         "city": "Chicago","country":"USA"},
    "expirationDate":"2015-03-24 13:56:45.000",
    "status":"Active",
    "hasDelinquentFederalDebt":false,
    "duns":"123456789",
    "links":[
       { "rel":"details",
         "href":"http://api.data.gov/samdata/v1/registrations/1234567890000"}],
    "dunsPlus4":"0000",
    "legalBusinessName":"Sample Company LLC",
    "cage":"12345"}],
    "links":[
       { "rel" : "self",
         "href": "http://api.data.gov/samsearch/v1/registrations?qterms=123456789&start=1&length=10"}]}

Pagination

The results will be defaulted to 10 records per JSON page. An API developer can navigate between pages by using the Self, Previous, First, and Next links (as appropriate depending on the number of records) at the end of each page.

"links":[
  {"rel": "self",
   "href":"http://api.data.gov/sam/v1/registrations?qterms=gsa&start=11&length=10"},
  {"rel": "prev",
   "href": "http://api.data.gov/sam/v1/registrations?qterms=gsa&start=1&length=10"},
  {"rel": "first",
   "href": "http://api.data.gov/sam/v1/registrations?qterms=gsa&start=1&length=10"},
  {"rel": "next",
   "href": "http://api.data.gov/sam/v1/registrations?qterms=gsa&start=21&length=10"}

An API developer can change the first record of the page and the number of records returned on the page by manipulating the start and length parameters at the end of the API search URL like so:

Note: The maximium page size is 500. If more than 500 entities are requested, the API will only return 500 per page without error.

Connecting Search Fields

Plus signs ‘+’ should be used as spaces between terms. ‘+AND+’ and ‘+OR+’ are always used to join two terms like a boolean AND and OR.

Note: If your search term contains the word(s) ‘and’ or ‘or’, you must not capitalize it.

Example:

Grouping Search Terms

Terms can be grouped against the same API advanced search field by using commas between each term.

Examples:

Note: For terms having the first character as alpha, you must insert a + symbol after each comma (exception is samAddress.country).

Examples:

Exception:

TIPS/HINTS

There are certain tips to note in order to construct an API search URL properly. We have listed several below. If you discover others as you work with our API, please add them to the ‘Feedback’ section of this GitHub site.

1) You can now search for a special character without using double quotes.

2) Commas must be omitted from search terms

3) There should only be one space (space = +) between each term and in between “AND” and “OR”

4) Quick Search does not allow grouping however, advanced search allows for grouping

5) When searching on samAddress.country, it can be entered as either a 2- or 3-character ISO-3166 codes however 3-character ISO-3166 codes will be returned.