In these slides, you'll learn about some of the most common mistakes we've seen when building API calls. If you're using an API to set up address autocomplete on your forms, this is the presentation for you. You can learn more about Smarty's APIs by visiting: https://www.smarty.com/docs/cloud You can view the webinar that these slides are from at: https://youtu.be/5EhPelXsv-U

1. Common Mistakes When
Calling Smarty APIs
Status Codes 401 and 402

2. In today’s webinar, we’ll cover two types of mistakes:
“Authentication Required” errors — status code 401
“Payment Required” errors — status code 402

3. “Authentication Required” Errors — Status Code 401
In this section:
● How to authenticate API requests the right way
● Common mistakes in client-side requests
● Common mistakes in server-side requests

4. How to Authenticate API Requests the Right Way
1. Get familiar with your account's API Keys page.

6. How to Authenticate API Requests the Right Way
1. Get familiar with your account's API Keys page.
2. Understand the difference between client-side requests (in a web browser) and server-side
requests. Since browsers send a Referer header automatically, our system treats any request that
includes a Referer header as a client-side request. In contrast, if the request does NOT have a
Referer header, our system treats it is a server-side request.

8. How to Authenticate API Requests the Right Way
1. Get familiar with your account's API Keys page.
2. Understand the difference between client-side requests (in a web browser) and server-side
requests. Since browsers send a Referer header automatically, our system treats any request that
includes a Referer header as a client-side request. In contrast, if the request does NOT have that
header, our system treats it is a server-side request.
3. For client-side calls:
● Include an embedded key in the request URL: key=31050191824945
● Make sure that the Referer value sent by the browser is listed as a host for the embedded key
being used.

9. How to Authenticate API Requests the Right Way
1. Get familiar with your account's API Keys page.
2. Understand the difference between client-side requests (in a web browser) and server-side
requests. Since browsers send a Referer header automatically, our system treats any request that
includes a Referer header as a client-side request. In contrast, if the request does NOT have that
header, our system treats it is a server-side request.
3. For client-side calls:
● Include an embedded key in the request URL: key=31050191824945
● Make sure that the Referer value sent by the browser is listed as a host for the embedded key
being used.
1. For server-side calls:
● Include the secret keys (auth-id and auth-token) in the request URL: auth-
id=a1Gf2rC&auth-token=HH3tnV

10. Common Mistakes in Client-Side Requests
● Don't submit secret keys in a client-side request.

11. Common Mistakes in Client-Side Requests
● Don't submit secret keys in a client-side request.
● Don't list the wrong referer/host value with the embedded key. (Look between the slashes of
the referer value.)

12. Common Mistakes in Client-Side Requests
● Don't submit secret keys in a client-side request.
● Don't list the wrong referer/host value with the embedded key. (Look between the slashes of
the referer value.)
○ For localhost, just list "localhost" without the port number.
○ For calls from the jsfiddle website, the correct host is fiddle.jshell.net

13. Common Mistakes in Client-Side Requests
● Don't submit secret keys in a client-side request.
● Don't list the wrong referer/host value with the embedded key. (Look between the slashes of
the referer value.)
○ For localhost, just list "localhost" without the port number.
○ For calls from the jsfiddle website, the correct host is fiddle.jshell.net
● When using a wildcard in a hostname, don't use the * for more than one level of subdomain.
For example:
complete referer value: www.accounts.smarty.com
correct: *.accounts.smarty.com
incorrect: *.smarty.com

14. Common Mistakes in Client-Side Requests
● Don't submit secret keys in a client-side request.
● Don't list the wrong referer/host value with the embedded key. (Look between the slashes of
the referer value.)
○ For localhost, just list "localhost" without the port number.
○ For calls from the jsfiddle website, the correct host is fiddle.jshell.net
● When using a wildcard in a hostname, don't use the * for more than one level of subdomain.
● Don't forget to explicitly set up a Referer header when calling from a mobile app or when using
an embedded key in Postman. (Mobile apps and Postman don't send a Referer header by
default, so you will need to set one up manually.)

15. Common Mistakes in Client-Side Requests
● Don't submit secret keys in a client-side request.
● Don't list the wrong referer/host value with the embedded key. (Look between the slashes of
the referer value.)
○ For localhost, just list "localhost" without the port number.
○ For calls from the jsfiddle website, the correct host is fiddle.jshell.net
● When using a wildcard in a hostname, don't use the * for more than one level of subdomain.
● Don't forget to explicitly set up a Referer header when calling from a mobile app or when using
an embedded key in Postman. (Mobile apps and Postman don't send a Referer header by
default, so you will need to set one up manually.)
● Don't forget to URL-encode the request URL. For example, a # symbol that is not URL-
encoded will break up the request URL, and our system will not recognize any part of the URL
after the # symbol.

16. Common Mistakes in Server-Side Requests
● Don't send an embedded key in a server-side request.

17. Common Mistakes in Server-Side Requests
● Don't send an embedded key in a server-side request.
● Don't type the auth-id or auth-token by hand; you might mistype a 1 for a lower-case l or a 0
for a capital O.

18. Common Mistakes in Server-Side Requests
● Don't send an embedded key in a server-side request.
● Don't type the auth-id or auth-token by hand; you might mistype a 1 for a lower-case l or a 0
for a capital O.
● Don't forget to URL-encode the request URL.

19. “Payment Required” Errors — Status Code 402
In this section:
● Understanding your Smarty account and your licenses
● Common mistakes that result in a "Payment Required" error

20. Understanding Your Smarty Account and Your Licenses
● If you are a developer trying to work with the Smarty APIs, we recommend that you be able to
log in to the Smarty account you are trying to use. Currently, each Smarty account has only a
single login email and password, so you would need to obtain those login details from
whomever has them.

21. Understanding Your Smarty Account and Your Licenses
● If you are a developer trying to work with the Smarty APIs, we recommend that you be able to
log in to the Smarty account you are trying to use. Currently, each Smarty account has only a
single login email and password, so you would need to obtain those login details from
whomever has them.
● Be familiar with the different pages available in your account, especially the Subscriptions and
API Keys pages.

22. Understanding Your Smarty Account and Your Licenses
● If you are a developer trying to work with the Smarty APIs, we recommend that you be able to
log in to the Smarty account you are trying to use. Currently, each Smarty account has only a
single login email and password, so you would need to obtain those login details from
whomever has them.
● Be familiar with the different pages available in your account, especially the Subscriptions and
API Keys pages.
● Make sure you understand your licenses. Know which APIs they allow you to call and what
specific abilities are included. Because we offer so many different licenses, distinguishing
them can be tricky. Feel free to ask the Support team or your sales rep about the abilities of
any particular license.

23. Common Mistakes That Result in a Payment Required Error
● Don't use API keys from the wrong account. Many companies have multiple Smarty accounts
— for example, a production account and several accounts used by individual developers.
Make sure the auth credentials you are submitting in the request URL pertain to the account
that actually has the right subscription in it.

24. Common Mistakes That Result in a Payment Required Error
● Don't use API keys from the wrong account.
● Don't try to call an API that is not supported by one of your licenses. Example: You try to call
the US Autocomplete Pro API, but you only have a US Address Verification subscription, with
a US Core Edition license. (Our US Autocomplete service requires its own license.)

25. Common Mistakes That Result in a Payment Required Error
● Don't use API keys from the wrong account.
● Don't try to call an API that is not supported by one of your licenses.
● If using one of our SDKs, don't assume that the license value listed in the Github example
code is the right one. Example: The default license listed in the Github example code is us-
rooftop-geocoding-cloud, but you don't actually have a Rooftop Geocoding license. You
may need to change the license value to us-core-cloud or us-standard-cloud. This
line is from the JavaScript SDK:
let clientBuilder = new SmartyCore.ClientBuilder(credentials)
.withBaseUrl("YOUR URL").withLicenses(["us-rooftop-geocoding-cloud"]);

26. Common Mistakes That Result in a Payment Required Error
● Don't use API keys from the wrong account.
● Don't try to call an API that is not supported by one of your licenses.
● If using one of our SDKs, don't assume that the license value listed in the Github example
code is the right one.
● Don't try to use an ability that doesn't pertain to your specific license. Examples:
○ When calling our US Street Address API, you include match=enhanced, but you don't have a US
Core Edition license. You only have the older US Standard Edition license (which doesn’t include
enhanced matching).

27. Common Mistakes That Result in a Payment Required Error
● Don't use API keys from the wrong account.
● Don't try to call an API that is not supported by one of your licenses.
● If using one of our SDKs, don't assume that the license value listed in the Github example
code is the right one.
● Don't try to use an ability that doesn't pertain to your specific license. Examples:
○ When calling our US Street Address API, you include match=enhanced, but you don't have a US
Core Edition license. You only have the older US Standard Edition license (which doesn’t include
enhanced matching).
○ When calling our International Street API, you include geocode=true, but your license is an
International Global Basic license that doesn't include geocodes.

28. Common Mistakes That Result in a Payment Required Error
● Don't use API keys from the wrong account.
● Don't try to call an API that is not supported by one of your licenses.
● If using one of our SDKs, don't assume that the license value listed in the Github example
code is the right one.
● Don't try to use an ability that doesn't pertain to your specific license. Examples:
○ When calling our US Street Address API, you include match=enhanced, but you don't have a US
Core Edition license. You only have the older US Standard Edition license (which doesn’t include
enhanced matching).
○ When calling our International Street API, you include geocode=true, but your license is an
International Global Basic license that doesn't include geocodes.
○ When calling our International Street API, you submit an address from a country not included with your
particular license.

29. Finishing Up
The Smarty Support team is here for you. We pride ourselves on being super responsive.
Our regular hours are weekdays 8 to 5 Mountain Time.
Phone: 801-877-5778
Chat: smarty.com
Email: support@smarty.com

30. Try our APIs for free!
smarty.com/signup