Query API Response V2

On this Page

  1. Example Response Format
  2. Total Records
  3. Form
  4. Fields
  5. Complex Fields
  6. Alt Fields
  7. Entries

Related Material

  1. Querying Your Data
  2. Return Value
  3. Error Messages
  4. Examples

FAQs

  1. Where is the documentation for API V1.0?


Example XML Response Format

A successful request to the Query API will result in a response of the following format:

<wufoo_query success="true">
    <Form>
        <Fields>
            <Field>
                <SubFields>
                    <Subfield></Subfield>
                </SubFields>
            </Field>
            <AltField>
                <SubFields>
                    <Subfield></Subfield>
                </SubFields>
                <IsAltField>1</IsAltField>
            </AltField>
        </Fields>
        <Entries>
            <Entry>
                <EntryId>X</EntryId>
                <FieldX>Value</FieldX>
                <AltFieldName>Value</AltFieldName>
            </Entry>
        </Entries>
    </Form>
</wufoo_query>

Each child node will contain its own structure, explained below.

Form

This node represents the container for everything form related. A form contains several child nodes, which will be explained in turn, below.

  • FormId - The form’s unique ID. Since URLs may change, using the form ID protects you from this change. You may use this ID to query for records instead of by URL. To use the ID instead of the URL to query for data replace the w_form parameter with the w_form_id parameter. To read read more about parameters check out the Api Query Parameters page.

  • Name - This is the name you specified for your form in the Form Builder.

  • Description - You form’s description as specified in the Form Builder.

  • Url - The Form’s URL. This URL is built from the form name and changes over time with your form name. See FormId (above) for a unique identifier your form.

  • StartDate - If you’ve restricted the form submission date in the form builder (see Form Settings, this date represents the date/time the form will begin accepting submissions.

  • EndDate - Same as above, but specifies when a form stops accepting submissions.

  • EntryLimit - The maximum number of submissions allow for the form.

  • EntryCount - Contains a number representing the total amount of entries your form has collected. It is not the total amount of records returned by the query. The purpose of this node is to aid with processes such as paging. For example, you may show your users records 1 through 20 of 285. By providing the total (285 in this case), you know how far to let them page through.

Basic Fields

Within Wufoo, each user-configured field is represented by a Field node. Some fields are single-valued, like Date Fields. Others, like Likert fields, can become more complex. In this section we’ll talk what properties Fields have in common and then view some variations on this theme.

Basic fields are fields without Sub Fields.

Example: Date field.

<Field>
    <Title><![CDATA[Date]]></Title>
    <Instructions></Instructions>
    <Typeof><![CDATA[date]]></Typeof>
    <ColumnId><![CDATA[110]]></ColumnId>
    <DefaultVal></DefaultVal>
</Field>

Below is a description of the children from the Field node.

  • Title - You specify this value when you name your field. So, if you have a Date field and you name it Wedding Date, Title will contain “Wedding Date”.

  • Instructions - This is the text that appears near the field to assist the user when the form displays. See field settings

  • Typeof - Lets you, the consumer of the API, know what type of field this is. The possible field types are address, checkbox, date, email, eurodate, europhone, file, likert, money, name, number, phone, radio, select, shortname, text, textarea, time, url.

  • ColumnId - You’ll use this number to link the field to the entry.

  • DefaultValue - See field settings

Complex Fields

Some fields, like the Checkbox, are represented hierarchically. While complex fields have the same child nodes that standard ones do, they also have Sub Fields. Complex field types include checkbox, address, shortname, name, select, likert, and choice. As an example, let’s take a look at a Checkbox Field.

Example: Checkbox Field

<Field>
    <Typeof><![CDATA[checkbox]]></Typeof>
    ..NODES REMOVED FOR EXAMPLE ONLY..
    <SubFields>
        <Subfield>
            <Typeof><![CDATA[Text]]></Typeof>
            <ColumnId><![CDATA[4]]></ColumnId>
            <ChoicesText><![CDATA[First Choice]]></ChoicesText>
            <DefaultVal><![CDATA[1]]></DefaultVal>
        </Subfield>
        <Subfield>
            <Typeof><![CDATA[Text]]></Typeof>
            <ColumnId><![CDATA[4]]></ColumnId>
            <ChoicesText><![CDATA[Second Choice]]></ChoicesText>
            <DefaultVal><![CDATA[0]]></DefaultVal>
        </Subfield>
    </SubFields>
</Field>

The Checkbox field has a Subfields node, containing 1 or more Subfield nodes. Let’s look at the children of the Checkbox node.

  • Title - This value simply repeats the parent node’s value.

  • ColumnId - Each Entry in the Entries node is represented as name/value pair. The ColumnId represents the name in this relationship. To correctly match the name in the Entry, you must append the prefix ‘Field’. So, to do a lookup in the Entries, a ColumnId of 1 will be searched as ‘Field1’.

  • DefaultValue - 1 if checked, 2 if unchecked.

  • ChoicesText - This is the literal value that will be returned in the node.

Other fields, like choice, radio, and likert have a series of choices, from which the user may choose one. These fields with choices have a Choices node with one or more Choice nodes. Let’s take a look at a Radio field with choices.

Example: Radio Field

<Field>
    <Typeof><![CDATA[radio]]></Typeof>
    ..NODES REMOVED FOR EXAMPLE ONLY..
    <Choices>
        <Choice>
            <ColumnId><![CDATA[104]]></ColumnId>
            <Choice><![CDATA[First Choice]]></Choice>
            <IsDefault><![CDATA[1]]></IsDefault>
        </Choice>
        <Choice>
            <ColumnId><![CDATA[104]]></ColumnId>
            <Choice><![CDATA[Second Choice]]></Choice>
            <IsDefault><![CDATA[0]]></IsDefault>
        </Choice>
    </Choices>
</Field>

Here’s a list of the important children of the Choice node.

  • ColumnId - This ID is important because the data returned in Entries node can be associated with it.

  • Choice - This is the literal value that will be returned in the node.

  • IsDefault - You’ll see a 1 in this field if it is the default choice when choices are displayed.

The only other notable Complex field is the Likert field. Since a Likert field contains both questions and choices, these are represented by Subfield and Choice nodes, respectively. Take a look at this Likert field to see how this works.

<Field>
    <Typeof><![CDATA[radio]]></Typeof>
    ..NODES REMOVED FOR EXAMPLE ONLY..
    <SubFields>
        <Subfield>
            <Title><![CDATA[Likert]]></Title>
            <ColumnId><![CDATA[122]]></ColumnId>
            <ChoicesText><![CDATA[Global warming is a myth]]></ChoicesText>
            <DefaultVal><![CDATA[0]]></DefaultVal>
        </Subfield>
        <Subfield>
            <Title><![CDATA[Likert]]></Title>
            <ColumnId><![CDATA[123]]></ColumnId>
            <ChoicesText><![CDATA[Kilroy was here.]]></ChoicesText>
            <DefaultVal><![CDATA[0]]></DefaultVal>
        </Subfield>
    </SubFields>
    <Choices>
        <Choice>
            <ColumnId><![CDATA[122]]></ColumnId>
            <Choice><![CDATA[Disagree]]></Choice>
            <IsDefault><![CDATA[0]]></IsDefault>
        </Choice>
        <Choice>
            <ColumnId><![CDATA[122]]></ColumnId>
            <Choice><![CDATA[Neither Agree nor Disagree]]></Choice>
            <IsDefault><![CDATA[0]]></IsDefault>
        </Choice>
        <Choice>
            <ColumnId><![CDATA[122]]></ColumnId>
            <Choice><![CDATA[Agree]]></Choice>
            <IsDefault><![CDATA[0]]></IsDefault>
        </Choice>
    </Choices>
</Field>

Alt Fields

A final type of field exists in Wufoo which differs from standard and complex fields in that these fields are not user-configured. These represent either system fields or integration-related field information. Alt Fields are contained in the AltFields node. Let’s take a look at one of the types of Alt fields, the System Alt Field.

Example: An Alt Field with a System Typeof

<AltField>
    <Category><![CDATA[System]]></Category>
    <Typeof><![CDATA[System]]></Table>
    <SubFields>
        <Subfield>
            <Typeof><![CDATA[text]]></Typeof>
            <ColumnId><![CDATA[EntryId]]></ColumnId>
            <ChoicesText><![CDATA[Entry Id]]></ChoicesText>
            <DefaultVal><![CDATA[0]]></DefaultVal>
        </Subfield>
        <Subfield>
            <Typeof><![CDATA[date]]></Typeof>
            <ColumnId><![CDATA[DateCreated]]></ColumnId>
            <ChoicesText><![CDATA[Date Created]]></ChoicesText>
            <DefaultVal><![CDATA[0]]></DefaultVal>
        </Subfield>
        <Subfield>
            <Typeof><![CDATA[text]]></Typeof>
            <ColumnId><![CDATA[CreatedBy]]></ColumnId>
            <ChoicesText><![CDATA[Created By]]></ChoicesText>
            <DefaultVal><![CDATA[0]]></DefaultVal>
        </Subfield>
        <Subfield>
            <Typeof><![CDATA[date]]></Typeof>
            <ColumnId><![CDATA[DateUpdated]]></ColumnId>
            <ChoicesText><![CDATA[Last Updated]]></ChoicesText>
            <DefaultVal><![CDATA[0]]></DefaultVal>
        </Subfield>
        <Subfield>
            <Typeof><![CDATA[text]]></Typeof>
            <ColumnId><![CDATA[UpdatedBy]]></ColumnId>
            <ChoicesText><![CDATA[Updated By]]></ChoicesText>
            <DefaultVal><![CDATA[0]]></DefaultVal>
        </Subfield>
    </SubFields>
    <IsAltField><![CDATA[1]]></IsAltField>
</AltField>

  • Typeof - Lets you, the consumer of the API, know what type of field this is. The possible field types for altfields include text and date.

  • ColumnId - Entries are represented as name/value pairs. The ColumnId represents the name. You need not append a prefix as you must in the ColumnId for non-AltFields.

  • DefaultValue - 1 if checked, 2 if unchecked.

  • ChoicesText - Think of this as the column header for your data. It’s a display-friendly way to show this field.

Entries

Entries represent the user-supplied values for your fields. The Entries node has Entry child nodes that act as name-value pairs. The ‘name’ in the name-value pair is associated with the ColumnId value of the either the Field or Subfield nodes from the Fields node. The ‘value’ in the name-value pair is… well, the value! :)

One more thing to note: the EntryId is always listed first. But, it also appears in the AltField with the Typeof ‘System’.

Example: Entries Node

<Entries>
    <Entry>
        <EntryId>1</EntryId>
        <Field110>Field Value</FieldX>
        <DateCreated>2030-01-01 12:00:00</AltFieldName>
    </Entry>
</Entries>

Where is the documentation for API V1.0?

We’ve revamped the query API. Below are the links to the old documentation:

Updated : July 16th, 2009

Wufoo

Wufoo · Infinity Box Inc. · Tampa, FL!

About · Blog · Gallery · Forums · Terms · Privacy · Help · Contact