License Selection

This page describes how to indicate which license to use when communicating with the various Smarty (formerly SmartyStreets) APIs.

Generally speaking, the endpoints being called attempt to properly deduce and infer the license you intend to use when making the call. In most cases, when a given account has only a single active subscription, the endpoint being called will enumerate the list of active subscriptions for the account and then properly select the only active subscription.

A situation can arise wherein an account has multiple active subscriptions of varying licenses. The endpoint being called simply doesn't have enough context to properly target the appropriate subscription. Because of this it becomes necessary for the client to specify the license parameter in the calling request.

As a simple example, let's consider an account that has two active subscriptions:

1. US Standard License, Cloud Access, Yearly Term (1,200,000 lookups)
2. US Rooftop Geocoding License, Cloud Access, Yearly Term (60,000 lookups, Business Starter Plan)

Now suppose a call is made to the US Street Address API:

https://us-street.api.smartystreets.com/street-address
	?auth-id={PUBLIC_VALUE}
	&auth-token={PRIVATE_VALUE}
	&street=1600+Pennsylvania+Avenue+NW+Washington+DC+20500

In the above scenario, which subscription should be utilized to service the request?

If we use subscription #1, the response will never receive results containing rooftop geocoding accuracy. Conversely, if the system were to automatically and blindly select subscription #2 any requests to the system would always receive rooftop-level accuracy even if the caller didn't need or want this, which would cause subscription #2 to be depleted unintentionally.

Because of this, we recommend that each request explicitly specify a license value so the caller can proactively decide what business value they are trying to utilize for the particular request in question, e.g. rooftop geocoding accuracy vs standard accuracy.

Again, the license parameter is strictly optional but at the same time is highly recommended. All official Smarty SDKs fully support providing a license value to accommodate the above scenarios.

Lastly, there are times when it may be necessary to specify more than one license value. For example, if the caller doesn't particularly know or care which license to use and simply wants to be sure to get a result back regardless of which license is being used. In this situation, it is possible to specify a comma-delimited, ordered list of license values. The licenses provided will be evaluated in order until an active subscription is found matching the licenses provided:

?license=example-license-1,example-license-2,example-license-3

The appropriate license values to be used for your subscriptions can be found on the subscription page of the account dashboard.