The Fields API

Other APIs

  1. API Introduction
  2. Forms GET
  3. Fields GET
  4. Entries GET / POST
  5. Users GET
  6. Reports GET
  7. Widgets GET
  8. Comments GET
  9. Web Hooks PUT / DELETE
  10. Login POST
  11. Examples
  12. The Wufoo REST Principles


Introduction

The Fields API describes the hierarchy of your data. At the heart of this API is the listing of FieldId values. Each FieldId corresponds to a value in the Entries API.

Example Fields API Call

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 two formats:

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

and

https://{subdomain}.wufoo.com/api/v3/reports/{reportIdentifier}/fields.{xml|json}?[pretty=true]&[system=true]
  • {subdomain} - This must be replaced with your subdomain.

  • {formIdentifier} - This must be replaced with your form Url value or hash value.

  • {reportIdentifier} - This must be replaced with your form Url value or hash value.

  • {xml|json} - This must be replaced by xml or json

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

The Standard Fields

All fields have the following basic properties.

The following is an example of a basic field called ‘User Name.’

<Field>
    <Title>User Name</Title>
    <Type>text</Typeof>
    <ID>Field1</ColumnId>
    <IsRequired>0</IsRequired>
</Field>
  • Title - The title is the friendly name you gave the field when creating your form. For example, if you were building a table with the API, the Title would be a column header.

  • Type - The Type represents a Wufoo field type. A listing of the these types can be found in the Field Type section of this documentation.

  • ID - This is the unique reference ID for your field. There will be one corresponding ID for each Entry in return value of the the Entries API.

  • IsRequired - This value can be one or zero, representing whether or not the field has been marked required in the Form Builder.

  • HasOtherField - This value is true or false and is only set if the field has choices. Only Multiple-Choice fields have the option of an Other field. When a Multiple-Choice field is marked as HasOtherField, the last choice is the Other field.

Fancy Pants Fields

The more elaborate Fancy Pants fields have Subfields. These include name, shortname, checkbox, address, and likert.

The example below shows a SubFields element from a shortname field.

<SubFields>
    <Subfield>
        <ID>106</ColumnId>
        <Label>First</ChoicesText>
    </Subfield>
    <Subfield>
        <ColumnId>107</ColumnId>
        <ChoicesText>Last</ChoicesText>
    </Subfield>
</SubFields>

The properties of subfields are defined here.

  • ID - This element works the same way a ID does for a Standard Field. It, too, has a one-to-one relationahip with the result an Entries API call.

  • Label - You need a friendly way to refer to the value of a Subfield. The Label works similarly to the Title element. In most cases, however, this text is determined by us. For example, the First and Last Choices Text values are predetermined because your Typeof is set to Shortname.

Choices

Some fields, like the radio, dropdown and likert, represent a choice from several available choices. These are represented in the <Choices> element, which in turn has a series of <Choice> elements. The example below shows the choices for a likert field. Remember, the <Score> element only shows up in the likert field type.

<Choices>
    <Choice>
        <Score>1</Score>
        <Label>Strongly Disagree</Text>
    </Choice>
    <Choice>
        <Score>2</Score>
        <Label>Disagree</Text>
    </Choice>
    <Choice>
        <Score>3</Score>
        <Label>Agree</Text>
    </Choice>
    <Choice>
        <Score>4</Score>
        <Label>Strongly Agree</Text>
    </Choice>
</Choices>

A Choice element has the following elements:

  • Label - Is easy to picture if you think of a Drop Down. Each choice in the DropDown is represented by a <Label> element.

  • Score (optional) - Only Likert fields have a score. This is a number from 1 to 10 representing a choice’s value relative to the other choices. For example, if there are four choices, the score ranges from 1 to 4.

Note: If this is a Multiple-Choice field, the HasOtherField property tells you if the last choice is “Other”.

System Fields

The final type of field is a System field. System fields are like standard fields with an <IsSystem> element. To get System fields, you must add the system=true parameter to the query string. For example

https://{subdomain}.wufoo.com/api/v3/fields/{formName}.{format}?system=true

would return your system fields. Remember to replace the values in curly braces with values of your choice. Also, remember that if you call system=true on your fields API, you should also call the system=true on your Entries API.

Below is an example of a System Field.

<Field>
    <Title>IP Address</Title>
    <Type>text</Typeof>
    <ID>IP</ColumnId>
    <IsSystem>1</IsSystem>
</Field>

Currently, the Wufoo API offers the following system fields. We hope to add many more system stats to this list as time goes on.

  • IP - The IP Address of the user submitting the form.

  • Last Page Accessed - If a user did not complete the form, this number represents the last page the user did submit.

  • Completion Status - Is a one or zero, representing either completed (1) or incomplete (empty value).

  • Status - Indicates what state your payment is in. An example is ‘Paid’. To see more payment types, check out the payment status documentation

  • PurchaseTotal - The total purchase, after discounts, etc.

  • Currency - The type of currency. An example is USD. Below is a listing of other currency types:

  • USD - U.S. Dollar
  • EUR - € Euro
  • GBP - £ Pound Sterling
  • JPY - ¥ Japanese Yen
  • CAD - C$ Canadian Dollar
  • MXN - Mex$ Mexican Peso
  • HKD - HK$ Hong Kong Dollar
  • HUF - Ft Hungarian Forint
  • NOK - kr Norwegian Kroner
  • NZD - NZ$ New Zealand Dollar
  • SGD - S$ Singapore Dollar
  • SEK - kr Swedish Kroner
  • PLN - zł Polish Zloty
  • AUD - A$ Australian Dollar
  • DKK - kr Danish Kroner
  • CHF - CHF Swiss Francs
  • CZK - Kč Czech Koruny
  • ILS - ₪ Israeli Sheqel
  • BRL - R$ Brazilian Real
  • TWD - NT$ Taiwan New Dollars
  • THB - ฿ Thai Baht
  • TransactionId - The confirmation number sent back from the merchant gateway.

  • MerchantType - The merchant name. An example is authnet

Putting It All Together

The following is an example of the most complicated field type, the likert. Let’s discuss what we’re seeing.

The Field Type is likert, which is like a combination of a checkbox and a select type. The <ID> is Field121. The subfields each have a ID as well, because each represents a possible field value. So, Field121, Field122, and Field123 will all result in a corresponding entry value when the Entries API is called. Note that the <ID> element on the <Field> element matches the first <ID> of the <SubFields> element. This useful on the client side if you’re using standard like XPath to navigate your DOM. The <Field> element also has a <Choices> element, which represents the possible values for each of the <Subfield> elements.

<Field>
    <Title>Likert</Title>
    <Type>likert</Typeof>
    <ID>Field121</ColumnId>
    <SubFields>
        <Subfield>
            <ID>121</ColumnId>
            <Label>Statement One</ChoicesText>
        </Subfield>
        <Subfield>
            <ID>122</ColumnId>
            <Label>Statement Two</ChoicesText>
        </Subfield>
        <Subfield>
            <ID>123</ColumnId>
            <Label>Statement Three</ChoicesText>
        </Subfield>
    </SubFields>
    <Choices>
        <Choice>
            <Score>1</Score>
            <Label>Strongly Disagree</Text>
        </Choice>
        <Choice>
            <Score>2</Score>
            <Label>Disagree</Text>
        </Choice>
        <Choice>
            <Score>3</Score>
            <Label>Agree</Text>
        </Choice>
        <Choice>
            <Score>4</Score>
            <Label>Strongly Agree</Text>
        </Choice>
    </Choices>
</Field>
Updated : August 20th, 2012