New 42-day free trial
Smarty

    • Technical requirements

    This page describes the technical requirements for using our services. Following them to a T (for technical 😉) will help you not only avoid encountering connectivity issues but also help you avoid the types of service interruptions that are not covered under any Service Level Agreement we offer.

    On this page:

    Use DNS to resolve IP addresses

    Please don’t hard-code IP addresses—either in code or in your configuration. Our services are geo-distributed, and the IP addresses of our servers will change regularly and without notice according to changing and unpredictable network traffic patterns. If you require static IPs due to regulatory compliance, we have an Enterprise plan that should help with that.

    Resolve DNS according to published TTLs

    Some network-layer software (we see it most commonly with the JVM) bypasses the DNS-provided time-to-live (TTL) value by default by indefinitely caching DNS lookups. This is effectively the same as hard-coding IP addresses, as described above. Ensure that your software stack is correctly resolving DNS on a regular basis to avoid unexpected outages.

    Trusted certificate authorities

    Here is the list of trusted certificate authorities with their respective SHA256 Fingerprints:

    Expect our SSL certificates to change

    Don't hard-code our SSL certificates.

    In the case of OpenSSL vulnerabilities, certificate authority compromise, or other exploits, our certificates may need to be quickly replaced. (Remember Heartbleed?) Our certificates are rotated before their expiration dates and we may change issuers at any time. We always select an issuer from the major brands as found in the Mozilla Trust Store list. We also rotate our various certificate private keys as an internal best practice.

    Use modern security software, cipher suites, and cryptographic protocols

    Supported protocols: TLS 1.2, TLS 1.3

    Supported cipher suites:

    • ECDHE-ECDSA-AES256-GCM-SHA384
    • ECDHE-RSA-AES256-GCM-SHA384
    • ECDHE-ECDSA-AES128-GCM-SHA256
    • ECDHE-RSA-AES128-GCM-SHA256
    • ECDHE-ECDSA-CHACHA20-POLY1305
    • ECDHE-RSA-CHACHA20-POLY1305
    • DHE-RSA-AES256-GCM-SHA384
    • DHE-RSA-AES128-GCM-SHA256
    • ECDHE-RSA-AES256-SHA384
    • ECDHE-RSA-AES128-SHA256
    • AES256-GCM-SHA384
    • AES128-GCM-SHA256
    • AES256-SHA256
    • AES128-SHA256
    • ECDHE-RSA-AES256-SHA
    • ECDHE-RSA-AES128-SHA
    • AES256-SHA
    • AES128-SHA

    According to the Mozilla SSL Configurator Generator, the above configuration is properly supported by the following frameworks and browsers:

    • Android 4.4.2
    • Java 8u31
    • OpenSSL 1.0.1
    • Firefox 27
    • Chrome 31
    • Edge
    • IE 11 on Windows 7
    • Safari 9
    • Opera 20

    We reserve the right to remove support for compromised or cryptographically weak encryption ciphers at any time.

    Customers connecting to our servers must be able to support modern ciphers. Please keep all security software updated and patched, especially after critical vulnerabilities are announced. We may change what SSL/TLS protocol versions and encryption ciphers are utilized according to recently published security exploits such as BEAST, CRIME, and POODLE, among others.

    As always, please contact us if you have security-related concerns or visit SSL Labs for a thorough discussion of these matters.

    Over time, the relative strength of a given certificate component will have to be increased to avoid changes in computing and cryptography.

    Furthermore, the relative strength of a given cipher, DHE for example, may need to be increased from 2048 to a larger value.

    Lastly, the hashing function that verifies a certificate may change from SHA2 to another hashing function such as SHA3. As long as your client library and operating system are updated and supported, our software will work as expected in your system.

    Add technical/operations contacts to your account

    Please keep your contact information current and correct.

    We can't stress this enough.

    Your information will be used only for account-related business, including important technical and billing notifications. We don't use it to spam you, and we don't sell or share it.

    Please ensure that your organization's administrative, billing, and technical personnel have current email addresses and phone numbers.

    Refer to our documentation as often as you need

    We know our system inside and out, so we’re happy to walk you through whatever you might need more clarity on.

    Some things in our documentation might seem unimportant or unnecessary, naming and character casing for example, but staying true to what’s provided in our documentation will provide you with the smoothest setup and integration possible so that you can get back to doing what you do best and we’ll run quietly and effectively in the background.

    A frequent issue many devs encounter (that we’re hoping to help you avoid) is when you change the casing or structure of an input. For example, an input of “ZIP_Code isn't the same as "zipcode".

    Another example of a common pitfall to avoid is deviation from specified data types. We know that you know this: A string isn’t the same as an integer, which also isn’t the same as a boolean.

    For example, the "zipcode" field is encoded as a string, not an integer. Incorrect naming, casing, or field type will unfortunately cause the request to be rejected or ignored.

    For the best and smoothest setup, please follow the HTTP methods or verbs according to the documentation.

    If our documentation specifies a "GET" request, please use that request type.

    It’s also important to keep in mind that HTTP verbs should not be matched with incompatible payloads. For example, please don't submit an HTTP body with a “GET" request.

    Instead, use a "POST" request, as indicated in the documentation. Otherwise, we cannot guarantee stability of implicit or inferred behavior that may occur. We also may not be able to provide the right type of support you need as quickly as you need it while we try to diagnose the problem.

    Comply with HTTP, URI, XML, and JSON specifications

    When sending or receiving data from our service, you will use HTTP and URIs, and often, JSON and/or XML.

    To ensure consistent and reliable performance, your software must send well-formed, standards-compliant payloads to Smarty. Requests that don’t meet our specifications may be rejected, even if they’ve worked in the past. This helps us maintain service quality and protect system integrity. Please note: any disruptions caused by non-compliant requests are not covered under your service level agreement.

    Please ensure that all URIs and query strings are properly constructed, including URL-encoding any query string parameters. When handling HTTP responses, use the Content-Type header to determine how to interpret the payload—e.g., application/json responses be parsed as JSON using a reliable library, not manually or via string comparison.

    To avoid surprises and ensure smooth communication, always include Content-Type and Accept headers in your requests to clearly indicate what you’re sending and what format you expect in return. We recommend using proven serialization and deserialization libraries appropriate for your tech stack to handle this reliably.

    When working with JSON payloads, your software should fully comply with the ECMA-404 JSON specification. Our API responses follow this standard—including the use of whitespace between tokens—so it's important to use a parser that correctly handles valid JSON structures.

    Improper handling of JSON may lead to issues we’re unable to support. The same best practices apply to XML responses as well. Using standards-compliant parsers helps ensure smooth, error-free integration (and fewer stress-induced sweats on your end 🥵).

    When working with serialized data formats—like JSON or URI query strings—please design your integration to gracefully handle changes. From time to time, we may add new fields to our API responses. One of the advantages of JSON is that well-structured clients can easily accommodate these additions without breaking. For example, if your code handles this: 

    {
	"city": "Miami",
	"state": "Florida"
}

    It should also work just fine when the response evolves to include additional fields:

    {
	"city": "Miami",
	"state_abbreviation": "FL",
	"state": "Florida"
}

    Likewise, to optimize performance, fields with null, empty, false, or zero values might be omitted entirely from responses. Your implementation should be able to handle both new and missing fields without issue.

    Ideally, your code would be accessing values through their keys, not position or offset. In the case of arrays, please anticipate more or fewer array elements unless the contract specifically says otherwise.

    Use modern browsers

    Smarty supports all major, modern desktop web browsers including Chrome, Firefox, Safari, Edge, and Opera.

    Old browsers unfortunately render content poorly, don't support the latest web standards or technologies, and have known security vulnerabilities.

    For the best experience and ongoing security, we recommend enabling automatic updates in your browser. While we aim to support a wide range of browsers, that support can change over time. Older versions—like legacy Internet Explorer—may be phased out as the web evolves. Likewise, brand-new browsers or versions might take us a little time to fully support. In short, browser compatibility may change without notice, so staying current helps ensure everything keeps working smoothly on your end.

    Retry requests

    HTTP is a stateless, unreliable protocol built on top of TCP with no delivery guarantees. Clients accessing our API should build in a retry mechanism in case packets are dropped or connectivity is interrupted due to circumstances and changing network conditions beyond our control.

    DNS will provide multiple IP addresses to our API. If any one IP address becomes unresponsive, please have your client software reacquire via DNS and temporarily target a different IP while excluding the unresponsive one.

    Use secure endpoints and don't ignore security warnings

    Always connect to our API over HTTPS/TLS to ensure secure communication—plaintext endpoints aren’t supported. If your browser or libraries surface security warnings, don’t ignore or suppress them. These alerts often point to important issues like outdated TLS versions or unsupported ciphers that need to be addressed to maintain a secure and successful connection.

    Stay in the loop

    We may use social media, emails, blog posts, web pages, and sometimes phone calls to announce widespread operational changes. We'd love it if you followed us on our various channels to stay informed. To subscribe to updates, simply go to our Status Page and click on "SUBSCRIBE TO UPDATES."

    Character set UTF-8

    First thou shalt indicate UTF. Then thou must count to 8. 8 shall be the number of the counting and the number of the counting shall be 8. 9 shalt thou not count; neither shalt thou count 7, excepting that thou then proceedeth to 8. 10 is right out.

    Once the number 8, being the number of the counting, be reached, then lobbest thou...

    Just be happy and use UTF-8. That is all. 😘

    For what it's worth

    The requirements on this page are not specific to Smarty. Most customers will have no problems following these basic "best practices." We're confident that if you rigorously follow these principles, you will have a positive experience using our service.

    Please don't hesitate to contact us if you have further questions. We're happy to help!

    Ready to get started?

    Schedule Demo
    42-day Free Trial