License Selection

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

When utilizing any of our APIs, the license parameter is optional. It should only be specified if multiple licenses are associated with the same account and are applicable to the same API call. For example, you should provide the license value if you have both a US Address Verification, Core Edition, Cloud License and a US Rooftop Geocoding, Cloud License.

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 Address Verification, Core Edition, Cloud License, Yearly Term (120,000 lookups)
2. US Rooftop Geocoding, Cloud License, Yearly Term (180,000 lookups)

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

https://us-street.api.smarty.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.

In situations like 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. With consideration to the example given earlier, the license values you would choose would be either us-core-cloud or us-rooftop-geocoding-cloud. License values associated with your subscription can be found on your Account Dashboard Subscriptions page.

If you want to use your us-rooftop-geocoding-cloud license, then your API request would look like this:

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

Again, the license parameter is optional, but be aware of when the license parameter is necessary and use it accordingly. 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.