Entries API

Which tool you need

You want to	Use
Pull entries into your own system or script on demand	The Entries API (this article)
Send each new entry to Mailchimp, HubSpot, Klaviyo or another service as it arrives	Form integrations
Connect to a service without a built-in integration, without code	A webhook with Zapier
Download entries as a spreadsheet	Exporting entry data

Before you start

• The Entries API is included in the Max plan and higher. See plans on the pricing page.
• It's for developers. You'll need to be comfortable making HTTP requests, such as with curl.
• Every request needs your API key in this header: Authorization: Token token=YOUR_API_KEY. Keep the key private, like a password.
• Responses are JSON, in the form { "data": [...] }. Errors return a short message and a status code, such as 401 for a bad key or 404 for an entry that can't be found.

Get an API key and a ready-made request

1. Open the Entries Manager.
2. Filter to the entries you want, such as one list. This step is optional.
3. Click Actions, then Explore Entries API.
4. Choose an existing API key, or follow the steps to create one.
5. Copy the curl command. It includes the filters you set in the Entries Manager.

Make a request

Fetch the first 25 entries:

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
    }
  ]
}

To get one entry, add its ID. Add a profile to choose which fields come back:

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

Page through results

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

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

2. Find the Link: header, and copy the address inside <> that ends with rel="next".

3. Request that address to get 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 there's no rel="next" link. That's the last page.

To start again from the first page with the same filters, request the address that ends with rel="first".

Paging and sorting parameters

Parameter	What it does
per_page	How many entries to return. The default is 100 and the maximum is 5,000.
sort	The field to order results by. The default is id.
direction	ascending or descending.
last_id	The last id on the previous page. It's included in the next link.
last_sort	The last value of your sort field on the previous page, when sorting by anything other than id. It's included in the next link.

Filter parameters

Combine filters by joining them with &. For a range, write min,max, and leave one side blank for an open-ended range, such as age=18,.

Parameter	Filters by	Example
campaign	One or more campaign IDs	campaign=1,2
list	One or more list IDs	list=12,34
list_tag	One or more list tag names	list_tag=spring
feed	One or more social media feed IDs	feed=56
exclude_feeds	true or 1 for only entries not from a feed, unless feed is also sent	exclude_feeds=true
category	One or more category names	category=Photos
city, province, postal_code	One or more city, state or province, or postal or ZIP codes. Dashes in postal codes are ignored.	province=Oregon
country	One or more country codes or names	country=US
label	One or more labels	label=winner
email	One exact email address	email=name@example.com
search	Text across indexed fields. Email addresses match exactly.	search=winner
received	A date range, in ISO 8601	received=2024-01-01,2024-01-31
age	An age range	age=18,
id	An entry ID range	id=1000,2000
votes1, votes2, votes3	A vote count range for that voting round	votes1=10,20
image_width, image_height	An image size range, in pixels	image_width=1080,
recaptcha_score	A reCAPTCHA score range, as decimals	recaptcha_score=0.5,1
approved	Approval: true, false, 1 or 0	approved=true
image, video	true or false to require an image or video	image=true
test	true or false to find test entries	test=true
profile	An export profile ID, which sets the fields returned	profile=42
es_boolean_X, es_date_X, es_number_X, es_list_X	A custom field in your export profile, where X is the number shown in the profile. Date and number take a range, and list takes one or more values.	es_list_2=VIP,Priority

For example, approved entries from the United States received in the first quarter of 2024:

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"

If something goes wrong

What you see	What to do
401	The API key is missing or wrong. Check the header is exactly Authorization: Token token=YOUR_API_KEY, or create a new key in the API Explorer.
404 for one entry	The entry doesn't exist, or it belongs to another account. Check the ID.
Only 100 entries come back	That's the default page size. Set per_page, up to 5,000, and follow the next links for the rest.
You can't find the next link	Run the request with -i so headers are shown. If there's no rel="next", you're on the last page.
Fewer entries than you expected	Check your filters. A range is written min,max, with a comma, and email matches only the exact address.
Custom fields aren't in the response	Add profile= with an export profile that includes them.

FAQs

Where do I get an API key?

In the Entries Manager, click Actions, then Explore Entries API. The API Explorer lets you choose an existing key or create a new one.

How many entries can one request return?

Up to 5,000. Set per_page to choose how many; without it, you get 100. To get more, follow the next link in the response headers.

Can I send entries to my CRM without writing code?

Yes. Use a form integration, such as Mailchimp, HubSpot or Klaviyo, or a webhook through Zapier. See Form integrations.

Can the API return only the fields I need?

Yes. Add profile= with the ID of an export profile. The response then uses that profile's fields.

Related resources

• Form integrations
• Exporting entries with Export Profiles
• Entries Manager
• Securing webhook form integrations