NAV Navbar
Logo
shell http

Introduction

Welcome to the SmartScreen License API! You can use our API to find US licensing information.

Authentication

API runs in test mode. No Authentication needed for the moment.

States and License types

Get Issuing State names.

This endpoint returns all State names (uppercase two-letter abbreviations) that are valid options for issuing state (iState option) in license data search (See below).

curl "http://apidev.smartscreen.tech/api/licenses/get_issuing_states"
GET http://apidev.smartscreen.tech/api/licenses/get_issuing_states

The above command returns JSON list:

[
  "CA", 
  "FL", 
  "NY", 
  "TX"
]

HTTP Request

GET http://apidev.smartscreen.tech/api/licenses/get_issuing_states

Query Parameters

This endpoint doesn’t accept any parameters

Get License types for single issuing State

curl "http://apidev.smartscreen.tech/api/licenses/get_license_types_for_issuing_state?iState=TX"
GET http://apidev.smartscreen.tech/api/licenses/get_license_types_for_issuing_state?iState=TX

Response is alphabetical JSON list of all present types of licenses issuied in specific state:

[
  "A/C Technician", 
  "Appliance Installer", 
  "Apprentice Electrician",
  "Water Well Driller/Pump Installer CE Provider"
]

HTTP Request

GET http://apidev.smartscreen.tech/api/licenses/get_license_types_for_issuing_state?iState=<ISSUING STATE>

URL Parameters

Parameter Description
ISSUING STATE The uppercase 2-letter abbreviation for state (case sensitive)

In the case when value provided is not listed in issuing states names, you will recieve corresponding info message: json "Value: '<invalid value>' is not one of known iState values"

Search License data

curl "http://apidev.smartscreen.tech/api/licenses/search?firstName=andrew&lastName=robert&company=ROBERT+S+INTERIORS&iState=NY&licenseType=Home+Improvement+Contractor"
GET http://apidev.smartscreen.tech/api/licenses/search?firstName=andrew&lastName=robert&company=ROBERT+S+INTERIORS&iState=NY&licenseType=Home+Improvement+Contractor

Only 25 results will be shown. If there are now suitable result try to make more specific request.

In response you get JSON document with two keys:

{
  "entries count": 2
  "data": [
  {result 1},
  {result 2},
  ], 
}

Each individual result represents fields of single matching entry in alphabetical order:

        {
      "additional_license_types": "", 
      "address_1": "445 BEACH 68TH ST", 
      "address_2": "", 
      "address_3": "", 
      "alternate_license_number": "", 
      "alternative_address_1": "", 
      "alternative_address_2": "", 
      "alternative_address_3": "", 
      "alternative_city": "", 
      "alternative_country": "", 
      "alternative_county": "", 
      "alternative_state": "", 
      "alternative_zip_code": "", 
      "city": "ARVERNE", 
      "company": "ROBERT, ANDREW R", 
      "country": "", 
      "county": "", 
      "date_of_graduation": "", 
      "dba": "ROBERT S INTERIORS", 
      "degree": "", 
      "disciplinary_action": "", 
      "email_1": "", 
      "email_2": "", 
      "expiration_date": "Thu, 28 Feb 2019 00:00:00 GMT", 
      "extra_field_1": "", 
      "extra_field_2": "", 
      "fax": "", 
      "first_name": "", 
      "issuing_body": "NYC Dept. of Consumer Affairs", 
      "issuing_state": "NY", 
      "last_name": "", 
      "last_update": "Thu, 25 May 2017 00:00:00 GMT", 
      "license_number": "1062384-DCA", 
      "license_status": "", 
      "license_subtype": "", 
      "license_type": "Home Improvement Contractor", 
      "middle_name": "", 
      "most_recent_issue_date": "", 
      "name_of_license_holder": "ROBERT, ANDREW R", 
      "notes": "", 
      "original_issue_date": "", 
      "phone_number_1": "", 
      "phone_number_2": "", 
      "profession": "Construction, Contracting & Home Improvement", 
      "responsible_individual": "", 
      "restriction": "", 
      "school": "", 
      "score": 4.666666666666667, 
      "secondary_status": "", 
      "state": "NY", 
      "suffix": "", 
      "zip_code": "116921406"
    }

Note! If you are using search over licensee first name, last name or company you will get an additional field “score”. Value of this field shows how well this entry matches given search criteria (higher is better).

HTTP Request

GET http://apidev.smartscreen.tech/api/licenses/search?iState=<2-LETTER ABBREV>&firstName=<FIRST NAME>&lastName=<LAST NAME>&licenseType=<LICIENSE TYPE>

URL Parameters

Parameter Description Limitations
firstName License holder first name * single word with length up to 12 characters
lastName License holder last name * single word with length up to 12 characters
company Licensee company or buisness name. For best match try to provide only most important words. Like if you have “ROBERT S INTERIORS Inc. Ltd.” - the only really important terms are “ROBERT+INTERIORS” At most 5 terms up to 12 charachters each
iState Exact issuing state (2-letter abbreviation). You can use this method to get list of valid values 2 uppercase letters
licenseType Exact license type name. You can use this method to get list of valid values exact case sensitive formulation; + sign between separate terms

Errors

Notifications

Some endpoints will return plain text response to invalid parameters explaining which term is invalid. For example:

Unrecognizable license type provided ‘some unknown license name’

Value: ‘Alabama’ exceeds maximum of characters per term for iState: 2

Value: ‘andrew john’ exceeds maximum of terms for firstName: 1

API uses the following error codes:

Error Code Meaning
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
418 I’m a teapot
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable