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 be specified only if multiple licenses are associated with the same account and apply 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 infer the license you intend to use when making the call. In most cases, when an account has only a single active subscription, the endpoint will enumerate the account's active subscriptions and then select the only active one.

A situation can arise in which an account has multiple active subscriptions with 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 scenario above, which subscription should be used 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 it, which would unintentionally deplete subscription #2.

In situations like this, we recommend that each request explicitly specify a license value so the caller can proactively decide which business value they’re trying to use for the particular request, e.g., rooftop geocoding accuracy vs. standard accuracy. With consideration of 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 may be times when it’s necessary to specify multiple license values. 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, regardless of which license is 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 for your subscriptions can be found on the Subscription page in the Account Dashboard.