The Entries GET API

Introduction

The Entries API is used to gather the data that users have submitted to your form. In this section we’ll describe the hierarchy of the entries element as well as describe the syntax for filtering this data.

If you are unsure how to get started with our API’s, please read our intro page for information on authenticating, sending and processing your request.

Request Format

This API accepts GET requests in the following formats:

https://{subdomain}.wufoo.com/api/v3/forms/{formIdentifier}/entries.{xml|json}[?pretty=true]

and

https://{subdomain}.wufoo.com/api/v3/reports/{reportIdentifier}/entries.{xml|json}[?pretty=true]

• {subdomain} - This placeholder must be replaced with your subdomain.

• {formIdentifier} - This placeholder must be replaced with your URL or hash.

• {reportIdentifier} - This placeholder must be replaced with your URL or hash.

• {xml|json} - You must choose between xml or json

• pretty=true - This optional get parameter formats your output as HTML for debugging through the browser.

The <Entry> Element

The <Entry> element lives inside the <Entries> parent. One <Entry> element exists for each submission to your form. So, if you have 5 submission to your form, you’ll have 5 <Entry> elements in the return value from your API call.

Sample Response

Here’s an example of a call to the Entries API.

<Entries>
    <Entry>
        <EntryId>1</EntryId>
        <Field2>Tim</Field2>
        <Field3>Sabat</Field3>
        <Field1>1</Field1>
        <DateCreated>2010-04-22 09:55:43</DateCreated>
        <CreatedBy>public</CreatedBy>
        <DateUpdated/>
        <UpdatedBy/>
    </Entry>
</Entries>

Default Fields

Every Entries API call returns five default fields with every request. Below is a list of the default fields and description of what they mean.

• EntryId - This value is the unique identifier for your entry.

• DateCreated - The date that this entry was submitted.

• Created By - The person who created the entry. If submitted through a form, the value here will be public. If the submission originated in the Entry Manager this value will be the user name of the submitting user.

• DateUpdated - The date that this entry was edited through the Entry Manager. If the submission has never been updated, this value will be blank.

• UpdatedBy - The user name of the person who updated the entry in the Entry Manager will appear in this element.

System Fields

System fields are also returned if you add the query parameter system=true to your call. For example, the url below will return system fields.

 https://fishbowl.wufoo.com/api/v3/forms/ticlkes/entries.xml?pretty=true&system=true

You may read more about system fields through the system Fields documentation.

Putting it all together

The relationship between the Entries API and the Fields API warrants some study. Let’s look at the relationship between two example calls to our fictional RSVP form.

First, the call to the Fields API.

https://{subdomain}.wufoo.com/api/v3/rsvp/fields.xml?pretty=true

Let’s say that the call above returns this value.

<Fields>
    <Field>
        <Title>Entry Id</Title>
        <Type>text</Type>
        <ID>EntryId</ID>
    </Field>
    <Field>
        <Title>Name</Title>
        <Type>shortname</Type>
        <ID>Field2</ID>
        <SubFields>
            <Subfield>
                <ID>Field2</ID>
                <Label>First</Label>
            </Subfield>
            <Subfield>
                <ID>Field3</ID>
                <Label>Last</Label>
            </Subfield>
        </SubFields>
    </Field>
    <Field>
        <Title>Number Of Guests</Title>
        <Type>number</Type>
        <ID>Field1</ID>
    </Field>
    <Field>
        <Title>Date Created</Title>
        <Type>date</Type>
        <ID>DateCreated</ID>
    </Field>
    <Field>
        <Title>Created By</Title>
        <Type>text</Type>
        <ID>CreatedBy</ID>
    </Field>
    <Field>
        <Title>Last Updated</Title>
        <Type>date</Type>
        <ID>LastUpdated</ID>
    </Field>
    <Field>
        <Title>Updated By</Title>
        <Type>text</Type>
        <ID>UpdatedBy</ID>
    </Field>
</Fields>

NOTE: LastUpdated appears as DateUpdated in the API. This is an issue we plan to fix soon. To follow the progress of this issue, please sign up for the developer newsletter.

Pay careful attention to the relationship between the <ColumId> values for the Fields API call and the elements contained within the <Entry> elements for the Entries call. For each field (or subfield) ID there is a matching <Entry> child node. This has many uses, but think of it in context of drawing a table. To draw the header, you’d iterate over all the <Title> or <Label> elements in the <Fields> or <Subfields> nodes, adding each as the header column text. Then, for each row of the table, you’d iterate over the <Entry> elements, adding the the child nodes in each column.

Filtering

You can filter your entries through the Wufoo API. To do so, you add parameters to the query string. Let’s look at an example:

 https://fishbowl.wufoo.com/api/v3/entries/ticlkes.xml?Filter1=EntryId+Is_equal_to+1

The snippet above would filter your entries, returning only those with the EntryId of 1. Now let’s look at a more complex filter.

?Filter1=EntryId+Is_after+1&Filter2=EntryId+Is_before+200&match=AND

This is actually two filters separated with the & sign which follow the pattern listed below.

Filter{Number}={ID}+{Operator}+{Value}

followed by the match parameter

match=AND

The parts of this filter are as follows:

• Filter{Number} - The number uniquely identifies your filter. In example above, there are two Filter{Number}s, Filter1 and Filter2. Filters, just like other query arguments are separated by

• {ID} - In this example, we’re seeking the EntryId, but you can choose any ID found using the Fields API for your form.

• {Operator} - This is the comparison operator used to filter your data. In this case, we’re looking for Is_equal_to. Acceptable operators include

• ‘Contains’;
• ‘Does_not_contain’;
• ‘Begins_with’;
• ‘Ends_with’;
• ‘Is_less_than’;
• ‘Is_greater_than’;
• ‘Is_on’;
• ‘Is_before’;
• ‘Is_after’;
• ‘Is_not_equal_to’;
• ‘Is_equal_to’;
• ‘Is_not_NULL’;

• {Value} - This is the value your operator uses to modify the query. In the example above, changing the {Value} from 1 to 2 will result in a query which asks for entries meeting the query EntryId+Is_equal_to+2.

Remember to add the + sign to separate your {ID}, {Operator} and {Value}. If your {Value} contains special characters like spaces or non-ascii characters, remember to urlencode it.

• match - The match parameter allows you to specify AND or OR to your filters. This will specify whether your query is performed as an AND or an OR. The default is AND.

• Timezone - Wufoo values are always returned offset from the date set in the user’s profile. However, we do not adjust your input fiter date. Instead, your dates are always interpreted as Eastern Standard Time (UTC - 5). Be sure to compensate for this by adjusting to your local timezone when doing filters by date. So, for example, if you’re looking for all values submitted after Tuesday at 10:30 PM and you’re in the central timzone, you’ll have to request values after Tuesday at 9:30 PM. Wufoo accepts Date arguments in MySql DateTime format.

Paging

You can also request pages of data. This is useful because the maximum page size for the Entries Api is 100. So if you wanted to page through your data 25 entries at a time, you’d write paging arguments which looked like the example below.

pageStart=0&pageSize=25

Let’s look at the different parts of the example above.

• pageStart - The page number you’d like to start from.

• pageSize - The number of entries returned in your page.

Example

This concept is best explained with an example: So, if you’re filtering for all entries where Field1 Contains Bob and the filter returned 1000 entries, and you set pageStart=0 and pageSize=25 you’d end up with the first 25 entries which fit the filter. If you up the pageStart to 25 and left the pageSize the same, you’d get the next 25 entries.

Some things to note about pageStart and pageSize:

• pageStart defaults to 0
• pageSize defaults to 25 and the maxim is 100

Entry Count

When creating complex UIs, it is often necessary to get the count for your API request so that paging code is easier to write. We’ve given this thought in the form of the Entry Count API.

The format for this API looks like this:

https://{subdomain}.wufoo.com/api/v3/forms/{formIdentifier}/entries/count.{xml|json}[?pretty=true]

https://{subdomain}.wufoo.com/api/v3/reports/{reportIdentifier}/entries/count.{xml|json}[?pretty=true]

This API returns the <EntryCount> element, which looks like this:

<EntryCount>105</EntryCount>

One thing to keep in mind: this number represents the total entries in your form matching your filter. If you don’t understand filters, please read the filter section of this documentation before proceeding.

So, this means that if your filter (or lack of filter) for your request returns an <EntryCount> of 105 and you set your page size to 100, you have 5 more entries to retrieve on your next request.

Sorting

Sorting works with the pattern you see below.

sort={ID}&sortDirection={DESC|ASC}

Let’s look at the arguments listed here

• {ID} - You may also sort on a single ID, as retrieved from the Fields API.

• {DESC|ASC} - You may choose to sort your entries ASC (lowest to highest) or DESC (highest to lowest).