Skip to main content

Entries API

Elite.svgELITE PLAN

Overview

ShortStack offers an Entries API that enables you to retrieve entry data collected and stored in your account. ShortStack's API is intended for use by software developers and is an advanced feature. If you are unsure, please feel free to use one of the Form Integration options detailed below.

Before You Start

  • Every request needs the header Authorization: Token token=YOUR_API_KEY. If you don’t yet have an API key, you can create one using the API Explorer (see next section).
  • Successful calls return JSON that looks like { "data": [...] }. Errors come back with a short text message and a status code such as 401 (bad key) or 404 (item not found).

API Explorer

You can use the Entries Manager to filter entries based on your chosen criteria, then use our Entry API Explorer to build a curl command to retrieve the same entries via our API.

  1. From the navigation bar, choose Manage > Entries.
  2. (Optional) Sort and filter by the list you wish to export. 
  3. Click the Actions drop-down at the top right of the Entries Manager. 
  4. Select Explore Entries API. 
  5. Follow the API Explorer instructions to select an existing API key (if any) or to create a new one. 
  6. The generated curl command will reflect any filters applied in the Entries Manager.

Basic List Request

Fetch the first 25 entries you can see:

curl -i -H "Authorization: Token token=$API_KEY" \
  "https://entries.shortstack.com/entries?per_page=25"

Sample response:

{
  "data": [
    {
      "id": 12345,
      "campaign_id": 678,
      "list_id": 91011
    }
  ]
}

Paging Through Results

  1. Run your request with -i so headers are shown:

    curl -i -H "Authorization: Token token=$API_KEY" \
  "https://entries.shortstack.com/entries?sort=received&direction=descending&per_page=50"
  2. Look in the output for a header named Link:. Copy the web address inside <> that ends with rel="next".

  3. Call that address to load the next page:

    curl -i -H "Authorization: Token token=$API_KEY" \
  "https://entries.shortstack.com/entries?sort=received&direction=descending&per_page=50&last_id=45678&last_sort=2024-04-10T16:45:00Z"
  4. Repeat until the header no longer shows rel="next".

  5. To jump back to the beginning with the same filters, copy the address that ends with rel="first" and call it:

    curl -i -H "Authorization: Token token=$API_KEY" \
  "https://entries.shortstack.com/entries?sort=received&direction=descending&per_page=50"

Paging & Sorting Parameters

  • per_page – how many entries to return (default 100, max 5000).
  • sort – the field to order results by (defaults to id).
  • direction – ascending or descending order.
  • last_id – the final id from the previous page when you follow a next link.
  • last_sort – the last value of your sort field when sorting by something other than id.

Filtering Parameters

  • campaign – one or more campaign IDs, passed as campaign=1,2.
  • list – one or more list IDs.
  • feed – one or more social media feed IDs.
  • list_tag – one or more tag names that map to list IDs.
  • category – one or more category names.
  • city – one or more city names.
  • country – one or more country codes or names.
  • province – one or more state or province names.
  • postal_code – one or more postal or ZIP codes (dashes are ignored).
  • label – one or more label values.
  • email – exact email address to match.
  • received – date range in the form start,end (ISO8601).
  • age – age range in the form min,max.
  • id – ID range in the form min,max.
  • votes1, votes2, votes3 – vote count ranges in the form min,max.
  • image_width, image_height – image dimension ranges in the form min,max.
  • recaptcha_score – decimal score range in the form min,max.
  • approved – true, false, 1, or 0 to filter by approval status.
  • exclude_feeds – set to true/1 to include only entries without a feed unless feed is also sent.
  • image – true/false to require an image.
  • test – true/false to find test entries.
  • video – true/false to require a video.
  • profile – export profile ID that controls which fields appear.
  • es_boolean_X – filters on a custom boolean field defined in your profile (X is the number shown in the profile).
  • es_date_X – filters on a custom date range for profile field X.
  • es_number_X – filters on a custom numeric range for profile field X.
  • es_list_X – filters on a custom list field for profile field X; pass multiple values as a list.

Filter Examples by Parameter Type

  • Text match: add country=US to find entries from the United States.
  • Boolean switch: add approved=true to find only approved entries (true, false, 1, or 0 are accepted).
  • List of IDs: add list=12,34 to pull entries from those two lists.
  • Date range: add received=2024-01-01,2024-01-31 for entries received in January 2024 (leave a side blank for open-ended ranges, e.g., received=,2024-01-31).
  • Number range: add age=18, to find ages 18 and higher, or votes1=10,20 for a specific span.
  • Search term: add search=winner to look across indexed text fields; emails like name@example.com are matched exactly.
  • Profile output: add profile=42 if you have an export profile that maps fields for download.
  • Custom profile field: add es_list_2=VIP,Priority to filter on a mapped list-type custom field.

Combine filters by joining them with &, for example:

curl -i -H "Authorization: Token token=$API_KEY" \
  "https://entries.shortstack.com/entries?per_page=50&country=US&approved=true&received=2024-01-01,2024-03-31"

Get a Single Entry

Provide the entry ID, and optionally a profile to shape the response:

curl -i -H "Authorization: Token token=$API_KEY" \
  "https://entries.shortstack.com/entries/12345?profile=42"

If the entry belongs to another account or does not exist you will receive a 404 response.

Other Options for Form Integrations

ShortStack also supports form integrations to enhance your campaign functionality. These include:

  • MailChimp
  • Google Maps
  • Webhooks

Learn more about Form Integrations.

 

Was this article helpful?