Query API Parameters V2
On this Page
FAQs
Introduction
Querying the Wufoo data is very flexible and easy, as explained in the query intro. There are some basic things you’ll have to do, like provide the Required Parameters to get your data back. But, like an evil overlord, you’ll eventually seek more power. We’re here to provide that for you in the later sections like Paging, Sorting or Conditions. What you do with your power is up to you.
Required Parameters
To complete your query, some parameters are required. Without them, your API call will be unsuccessful, resulting in an error.
w_api_key
Your 16 digit API key. If you do not have a key, read how to get one here.
w_form
The URL of the form you would like to pull data from.
w_version
The API version you wish to query. The most current version of this API is 2.0. Instructions for how to query the old API may be found here.
w_condition_count
Ok, this parameter is not really required for a condition-less call, but as soon as you begin filtering your data, you’ll need to remember to add this parameter. To find out more, read about conditions.
w_format
This parameter is required if you want your data to be returned in a format other than JSON. The acceptable values for this parameter are JSON and XML. This trips people up who prefer XML over JSON, so remember to set w_format=XML if you want to work with XML.
Paging
When paging with the Wufoo API, you use a Page Start and Page Size parameter, which will be explained below. What we’ll try to get you to understand here is how the two work together.
If you have If you know SQL, you can think of Page Start and Page Size as the Offset and Limit database keywords. If not, here’s an example: Let’s say you have an unknown number of entries that you’d like to page through 10 at a time. To get the first 10, you’d set the w_page_start parameter to 0 and the w_page_size parameter to 10. To get the next 10, you’d set w_page_start to 10 and the w_page_size parameter to 10 again. You’d continue this pattern, increasing the w_page_start parameter by 10. A good way to tell if you’ve reached the last entry is to compare the number of entries returned to the w_page_size parameter. If the returned number of entries matches the w_page_size value, you have more calls to the API left to do. If you are returned a number smaller than the page size, you’re done making calls.
w_page_start
The entry count from which to start. This parameter is not required and it defaults to the first entry our system encounters. Note: This should not be confused with the EntryId, which is a column name you can use for conditional filtering. Instead, it is a count from which to start.
w_page_size
How many records you would like to retrieve. The maximum is 100, and the default is 25. This parameter is not required.
Sorting
Sorting is easy with the Wufoo API. The only real hangup people when sorting is that they don’t know where to grab their FieldID.
w_sort
You sort on a FieldID as which is a concept explained earlier. If you know your FieldID, you’d supply it here. For example, if you had a field titled First Name with a corresponding ID of 1, you’d supply it to this Post Parameter and your results would be returned with an ascending sort on First Name (Field 1). You may also sort on Reserved Field IDs.
w_sort_direction
This paramtere takes two values: ‘ASC’ or ‘DESC’. The default value is ‘ASC’. In the example above, ‘ASC’ would return rows from a to z, while ‘DESC’ would return rows from z to a.
Conditions
w_condition_count
If you would like to apply filters to your data, you must supply conditions. To supply a condition, you must tell Wufoo your Condition Count. You do so with the w_condition_count parameter.
An example of this in conversation would be:
Show me all entries where First Name is equal to Ryan
In the example above, there would be one condition: ‘where First Name is equal to Ryan’. So, for the w_condition_count parameter, you would set a value of 1. Below, we will learn how to specify the actual conditions.
w_condition_field_i
Using the same example set above in w_condition_count, we will now set the condition field. In this case, it would be ‘First Name’. It is also important to note that in w_condition_field_i, the i represents the condition count. If this is the first condition, you would put a 1 there, like so:
w_condition_field_1 = 1
Again, we will use the corresponding field ID to represent the field. You can add up to 10 conditions. For each one, you would place the number instead of the i.
w_condition_i
Using the same example set above in w_condition_count, we will now set the condition. In this case, it would be ‘is equal to’. It is also important to note that in w_condition_i, the i represents the condition count. If this is the first condition, you would put a 1 there, like so:
w_condition_1 = Is equal to
You can add up to 10 conditions. For each one, you would place the number instead of the i.
Acceptable conditional operators are listed below with examples.
- Contains - True if a one string is contained within another. This argument is case insensitive.
- Does not contain - True if the string is not present. This operator is case insensitive.
- Begins with - You get the picture.
- Ends with - Again, self explanatory.
- Is less than - A string comparison operator. True if: 1 is < 2. A is < B. a is < A.
- Is greater than - A string comparison operator. True if: 2 is > 1. B is > b. A is > a.
- Is on - A date comparison operator. If you ask DateCreated is on 2008-08-13 and the Date Created is 2008-08-13 19:06:38, would return true. Use on Date Fields.
- Is before - A comparison operator. Use on Date Fields
- Is after - A comparison operator. Use on Date Fields
- Is not equal to - You get the picture.
- Is equal to - You got it.
- Is not NULL - if your argument is not empty.
w_condition_value_i
Using the same example set above in w_condition_count, we will now set the condition value. In this case, it would be ‘Ryan’. It is also important to note that in w_condition_value_i, the i represents the condition count. If this is the first condition, you would put a 1 there, like so:
w_condition_value_1 = Ryan
You can add up to 10 conditions. For each one, you would place the number instead of the i.
w_condition_match
This parameter comes into play when you have more than one condition. You may supply it with two values: ‘any’ or ‘all’. If you use ‘any’, then the returned result will contain data that matches any of your conditions. If you use ‘all’, then the returned result will only contain data that matches all of your conditions. The default value is ‘any’.
Why do I need the w_version parameter?
This is the new API, that’s why! While users transition from the old API to the new one, we’ll maintain both versions. If you leave off your w_version="2.0" parameter, you’ll end up querying against Version 1.0 of the API. The success node will return true, but your data will be structured according to the old API response
What is a FieldID?
Field IDs are used to uniquely identify fields on your Wufoo form and are used when sorting or setting up conditions and can be found on the API Information Page via the Code Manager. Some people may ask, “why not just query by the Field Title”? The answer is simple: We set up Wufoo with FieldIDs so you could change your Field Titles without having to worry about breaking your existing API queries.
What is a reserved Field ID?
Three FieldIDs exist for every form and are explained below:
EntryID - This is the unique ID given to each submitted entry.
DateCreated - This is the date that your entry was first submitted.
DateUpdated - This is the date that you entry was edited by you through the Entry Manager
Would you please provide some example condition code?
Conditional code seems to trip people up, so we’ve created a few examples here.
Here’s an example of the conditions you’d see if you wanted to filter on the Reserved Field ‘DateCreated’.
'w_condition_count' => 1,
'w_condition_field_1' => 'DateCreated',
'w_condition_1' => 'Contains',
'w_condition_value_1' => '2009-10-14'
Here’s another example of how to filter by a non-reserved field. In other words, a field defined in your API Information. Let’s say that you field ID is 12 from your API Information and you want to filter that by text field by the phrase ‘Boy Genius’. The following code would do that.
'w_condition_count' => 1,
'w_condition_field_1' => '12',
'w_condition_1' => 'Is equal to',
'w_condition_value_1' => 'Boy Genius'
Notice that w_condition_field_1 is the key and 12 is the value.
So let’s put those two examples together. For example, you wanted to search for all entries created on 2009-10-14 with the phrase ‘Boy Genius’ in Field12 than you’d use the following code:
'w_condition_count' => 2,
'w_condition_field_1' => 'DateCreated',
'w_condition_1' => 'Contains',
'w_condition_value_1' => '2009-10-14',
'w_condition_field_2' => '12',
'w_condition_2' => 'Is equal to',
'w_condition_value_2' => 'Boy Genius',
'w_condition_match' => 'all'
Things to note about this code:
- We set w_condition_count to 2.
- The key w_condition_field_1 value DateCreated pair means ‘The first of the two conditions will filter on Date Created’.
- The key w_condition_field_2 value 12 pair means ‘The second of the two conditions will filter on Field12 from the API Information’.
- the key w_condition_match is set to all which means that we’ll want to match all the conditions. In other words, the entries must be created on 2009-10-14 AND contain the text ‘Boy Genius’. You can read about w_condition_match here.
- DateCreated in w_condition_field_1 contains seconds, so to filter on any entry created that day, we use the condition Contains instead of Is equal to.
