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.
The process for using the list upload API is really simple:
- Submit a POST request containing your file to our REST endpoint.
- Obtain the JSON response containing your file's ID.
- Check the status of your list using a simple GET request.
- 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.
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:
Don't append a trailing slash (
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")
POSTverb. The URL will look something like this:
https://api.smartystreets.com/lists?auth-id=<your id here>&auth-token=<your token here>&filename=<filename here>Important: Lists submitted via the list upload API must have clearly-defined column names for each field since there is currently no way to manually define each field. We recommend column names such as the following:
- 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
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) .
If your request was composed correctly, we'll send back a JSON object similar to the following:
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
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:
For completed lists
If your list is done, the response is:
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: