Transfer and process files automatically

Introducing the List Upload API

Not to be confused with LiveAddress API, the list upload API is for using LiveAddress for Lists automatically without having to manually upload and download your list files. By using the list upload API, you can:

• send files to LiveAddress for Lists programmatically.
• observe the status of lists-in-process.
• download the completed files automatically.

Overview

The process for using the list upload API is really simple:

1. Submit a POST request containing your file to our REST endpoint.
2. Obtain the JSON response containing your file's ID.
3. Check the status of your list using a simple GET request.
4. When your list is finished, use a GET request to start downloading the .zip file.

In order to authenticate you with your account, you'll need to create a Secret Key Pair and include those values with your REST requests.

Authentication

Login to your account at SmartyStreets and go to Key Management. There you'll find an option to create a new key pair. Give it a label (or name) then click Add.

When performing requests to the REST endpoint, make sure to include these two parameters (URL-encoded) in the query string: ?auth-id=<your id here>&auth-token=<your token here> Keep these key pairs private so other people cannot use your account's lookups without your permission.

All your requests to the list upload API will use this base URL: https://api.smartystreets.com/lists Don't append a trailing slash (lists/). A clean URL is a happy URL, and you'll receive an empty response if you append a trailing slash.

Uploading a file

Request URL and method

Append a few query string parameters to the above URL, namely:

• auth-id — the ID from an enabled key-pair in your account
• auth-token — the token value associated with the chosen key-pair
• filename — the name you want the file to be called (e.g. "my_list.csv")

• Id — note: this will help you to link the data back to your source when done
• Street1 — address line 1
• Street2 — address line 2 (rarely used)
• Unit — secondary number such as apartment or suite
• City — you know, like a city
• State — you know, like a state
• ZIPCode — also known as postal code
• CityStateZip — combined city/state/zip all in one field
• FullName — you know, like the first and last name combined
• FirstName — given name
• LastName — family name
• Organization — company, business, or other organization name

Request body

Fill the body of the request with the bytes of the file. This is usually accomplished by opening an input file stream and reading the stream until the end of file.

Submit the request and we'll do the rest (that rhymes). As soon as your list is fully received, we will begin processing it. No account lookups will be deducted at this stage.

Note: Each account may have up to 5 concurrent lists in process. This means that if you have met this limit you will receive an HTTP response with status code 429 (Too Many Requests) .

JSON response

If your request was composed correctly, we'll send back a JSON object similar to the following: { "list_id": "4ba8807e-139b-45e1-a5c7-1e30b5dd5c9a", "polling_frequency_in_seconds": 30 }

The list_id value is what you will use when making further requests related to this particular file, such as checking the progress or downloading the results. The polling_frequency_in_seconds will tell you how frequently to submit a request to check the status of your list.

Checking the status

A GET request to the following URL will yield a JSON response with the status of your list: https://api.smartystreets.com/lists/<your list_id>?auth-id=<your id here>&auth-token=<your token here> Make sure to replace the appropriate values into the URL.

The possible status responses are: queued, opening, processing, compressing, publishing, failed, aborted, succeeded

For lists still processing

If your list is not yet finished, the response will look like this: { "current_step": "Processing", "step_progress": .54 }

For completed lists

If your list is done, the response is: { "current_step": "Succeeded" }

Downloading the results

When your list is done, perform an HTTP GET request to the following URL to start downloading the .zip file: https://api.smartystreets.com/lists/<your list_id>/download?auth-id=<your id here>&auth-token=<your token here>

Remember: You'll download a .zip file that contains the regular output files inside it. You'll have to extract the .zip file to get to its contents.

When you download your list, your account lookups will be deducted for that particular list. You can download your list multiple times but you will only be charged for it once. If you do not have enough lookups in your account to download the whole list, the response is 402 Payment Required. In that case, you'll need to purchase more LiveAddress for Lists lookups.

Alternatively, you could perform an HTTP HEAD request on the same URL to download the preview file for free.

Deleting a list

You can remove your list from our servers with an HTTP DELETE request to the following URL: https://api.smartystreets.com/lists/YOUR-LIST-ID?auth-id=YOUR-AUTH-ID&auth-token=YOUR-AUTH-TOKEN

Examples

You can access this API in many different ways, but we have cURL examples to help get you started on the command line. We also have sample code on GitHub you may try out.