Wufoo Rest API V3

Introduction

The Wufoo API is designed to unlock the potential of the data stored inside your Wufoo account. We provide all the tools required to build applications, advanced reports and visualizations not currently offered by the default Wufoo UI.

What’s even better is that you don’t need any programming experience to at least view the data, because if you’re reading this, you already have the tools required: a web browser. We’ve added a special parameter to the request that makes the process of exploring the API a simple, visual experience.

Although this page is littered with tidbits explaining details of the process, you can actually dive right in by exploring the links at the top section of each page. On each of those linked pages you’ll find short pages designed to get you working with the data. Once you’ve familiarized yourself with what the API can do, return here to learn the details of topics like Authentication or writing your first Wufoo PHP script.

Finding Your Key

To use the API, you will need your API key and some information about your forms. To obtain your key, log in to your Wufoo account, head to the Form Manager or Forms tab, and click the Code button beneath the name of the form for the form you want to integrate. This will take you to the code manager where you’ll want to click the API Information button to access your API credentials. On that page there should be a 16 digit code, which is your unique API key. This key acts as a password to your data, so be sure to keep it private and to never give it out.

Wufoo REST Structure

We’ve tried to break the Wufoo API structure up into logical sections, following as closely as we can to RESTful web service principles. This means that we’ve organized the Wufoo API into a series of resources represented by URLs and that you interact with these URLs using the HTTP methods of GET, PUT, POST, and DELETE.

URL Prefix

All API URLs will begin with

/api/{version}

The version number we’ll begin at is v3 out of respect for our two previous attempts. v3 may be thought of as version 3.0, although we’ll leave off the decimal. For minor revisions (right of the decimal) we promise not to make any breaking changes, only additions. A major departure from our current style will require an increment to 4.0, although we hope that with careful thought and review, this will not be necessary.

The Extension

The API will support XML and JSON for both input and output formats. The extension you add to the request will denote your choice. For example, this request will return a JSON response:

https://fishbowl.wufoo.com/api/v3/users.json

While this request will return XML.

2) https://fishbowl.wufoo.com/api/v3/users.xml

The corresponding HTML content type will be returned with your choice as well.

Convenience Parameters

We know that debugging scripts and code in a browser can be a real pain. In PHP, for example, to prevent your tags from being stripped you must echo your response using htmlentities. This still does nothing in terms of formatting. With this in mind, we’ve added a convenient GET parameter to provide an in-browser view of the output. Here’s

https://fishbowl.wufoo.com/api/v3/users.xml?pretty=true

https://fishbowl.wufoo.com/api/v3/users.json?pretty=true

In the examples above, we’ve added the GET parameter “pretty=true” to the query string. Using this parameter does two things:

• Formatted Output : Your response will be returned with all the indentation and newlines, which make reading the XML and JSON a breeze.

• Tag Preservation : Most modern browsers will strip your XML tags away, leaving you with only the concatenated text to view. The pretty parameter keeps your tags visible so you get up and running more quickly.

Remember, this is a convenience feature only and must not be used in production. Here’s why: To make your output pretty we must run Google’s pretty print code snippet, which adds a 50% overhead increase to the call. Just to be safe, we throw a non-escaped greater than sign (>) which makes the markup non-valid and causes xml parsers to choke. In short, use this method all you like, but remember to remove it when you’re writing your scripts.

Authenticating

You can not reach protected Wufoo pages without authentication. But, authenticating to Wufoo’s API is simple. Wufoo employs basic authentication for each request. You provide the authentication credentials by adding your credentials to your favorite data transfer client or scripting language. We’ll show you how to do that here.

User Authorization

An added feature in this iteration of the API is the addition of user-level authorization. This means that each user is granted an API key. API keys restrict access to forms and reports based the user’s permissions set up in User Management.

Session Login

As a convenience, you can access all GET requests using your browser if you are logged into Wufoo. Remember to use your convenience parameter to view the output in ‘pretty’ format. To use your session login, just provide your user name and password at the login screen and then make a request through your browser to any of the API resources.

Authentication through CURL

Arguably, one of the most popular and easy to use data transfer libraries in the universe is cURL. The instructions below outline how to connect to your data using the command line. Feel free to adapt this method to your favorite programming language. Follow the instructions listed on cURL’s site to get the binaries you need. Once you do, making a call through your command line is as simple as the snippet shown below.

curl -u AOI6-LFKL-VM1Q-IEX9:footastic https://fishbowl.wufoo.com/api/v3/users.xml

Let’s break apart the syntax above piece-by-piece.

• curl : This is the call to your cURL library.

• -u : Tells the cURL library that you’ll be sending the credentials in the form of {username}:{password}

• AOI6-LFKL-VM1Q-IEX9:footastic : The first value before the colon is your API key. You’ll obviously change this to your API key.

• footastic : This value is required to meet cURL’s spec, but is ignored at the server, so let’s just send footastic through for giggles.

• https://fishbowl.wufoo.com/api/v3/users.xml : This is your URL.

Authentication through PHP

Finally, we’ll show you how to make a GET request using our favorite scripting language, PHP. Below is the snippet we’ll use:

$curl = curl_init('https://fishbowl.wufoo.com/api/v3/users.xml');       //1
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);                          //2
curl_setopt($curl, CURLOPT_USERPWD, 'AOI6-LFKL-VM1Q-IEX9:footastic');   //3
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY);                     //4
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);                          
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);                           
curl_setopt($curl, CURLOPT_USERAGENT, 'Wufoo Sample Code');             //5

$response = curl_exec($curl);                                           //6
$resultStatus = curl_getinfo($curl);                                    //7

if($resultStatus['http_code'] == 200) {                     //8
    echo htmlentities($response);
} else {
    echo 'Call Failed '.print_r($resultStatus);                         //9
}

If you’re new to PHP, this code requires some explanation. The code is numbered down the right side, and I’ll reference each as I move along. Also, a quick scan of the PHP cURL documentation would be useful for you, too.

• Line 1 - This starts things off by setting our URL and initializing the $curl object. Note the use of the https. This is important to protect your data.

• Line 2 - Tells cURL to write the entire response to a string, rather than returning it as a stream.

• Line 3 - We’re setting your API key and a stand-in for a password, separated by the colon. Remember, Wufoo servers will compare your API key against your subdomain (provided in the url), but will ignore the password. In this case, we use the value ‘footastic,’ but you may use anything you like.

• Line 4 - Just set these values and move along. If you’re really curious about them, ask the internet.

• Line 5 - Sets your user agent. This identifies your code to our servers. We can’t force you to add this, but we do reserve the rights to block

Hashed URL Vs Friendly URL

Each entity you interact with in Wufoo (forms, reports, widgets, users, etc.) has a Friendly URL and a Hashed URL. A friendly URL is easy to read and remember, but is subject to change based on the form title. A hashed URL is less memorable, but is not subject to change when the form title changes. Below you’ll see two links, both to the same place.

//friendly URL

https://fishbowl.wufoo.com/api/v3/forms/web-hook-example/entries.xml

//hashed URL

https://fishbowl.wufoo.com/api/v3/forms/w7x1p5/entries.xml

Since these two variables are interchangeable, we’ll call them Identifiers. For the rest of the documentation, you’ll see notation signifying identifiers. They will be surrounded by curly brackets. So, the URL

https://fishbowl.wufoo.com/api/v3/forms/{formIdentifier}/entries.xml

means both

https://fishbowl.wufoo.com/api/v3/forms/w7x1p5/entries.xml

AND

https://fishbowl.wufoo.com/api/v3/forms/web-hook-example/entries.xml

Widgets, Reports, Forms, Users, and WebHooks all have hash identifiers.

Are there any API restrictions?

We currently restrict your API usage to 5000 requests per day.

Can sub-users use the API?

Each sub-user is issued their own API key. Sub-users are only able to access resources granted to them through User Management.

Where are the old APIs?

We highly encourage you to work with the new APIs listed here. We will eventually discontinue support for V2 of the API. However, for posterity, we’ve left the Version 2 API Docs available.