SAM API documentation

SAM Search API

NOTE: All the documentation on this page refers to the October release of the SAM API

As of November 2014, 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

Quick Search:

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

Advanced Search:

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:

http://api.data.gov/sam/v1/registrations?qterms=gsa&start=1&length=25

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:

https://api.data.gov/sam/v1/registrations?qterms=samAddress.country:(ALB,BLZ,CHL)&api_key=DEMO_KEY

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) Any query terms with special characters must include double quotes: q= “ZY’Z” Note: %26 can be used for ampersand ‘&’

2) Commas must be omitted from search terms

3) Boolean based search fields must be grouped together at the front of a URL:

Note: If your search includes ‘Disaster Response Contractor’, the disasterResponse search field must be the last Boolean search field in the group

Example: qterms=womanOwnedBusiness:true+AND+sba8AProgram: true+AND+disasterResponse:true+AND+legalBusinessName:cats

4) There should only be one space (‘+’) between each term and in between “AND” and “OR”

5) Quick Search does not allow grouping

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

7) When grouping Legal Business Name and Country in an advanced search, the term legalBusinessName must come before samAddress.country.

Example:

https://api.data.gov/sam/v1/registrations?qterms=legalBusinessName:technology+OR+samAddress.country:XYZ&api_key=DEMO_KEY