Home → FormSpring API → Printer Friendly Version
FormSpring API
1. Overview
1.1. Overview
Requests
- All requests must be submitted with a valid API key. (e.g. api_key=ABCDE)
- All requests must be made to the url https://www.formspring.com/api/METHOD where METHOD is the name of one of the methods specified below.
- All requests must be submitted over SSL.
- Requests may be submitted using HTTP POST or GET methods, although POST is required for file uploads.
- Requests are limited to 14,400 calls per day (an average of 10 requests per minute). This limit is per account, not per API key.
Responses
- The default response type is XML
- The response type may be requested using the type parameter with one of xml, json or php. (e.g. type=json)
- All successful calls will be returned with an HTTP status code of 200
- Calls that reference a form or data object that could not be found will be returned with an HTTP status code of 400
- Invalid calls will be returned with an HTTP status code of 500
Example Successful XML Response
<?xml version="1.0" encoding="utf-8" ?> <response status="ok"> [xml] </response>
Example Successful JSON Response
{
"status" : "ok",
"response" : [ ]
}
Example Successful PHP Response
a:2:{s:6:"status";s:2:"ok";s:7:"response";a:0:{}}
Example Error XML Response
<?xml version="1.0" encoding="utf-8" ?> <response status="error"> <error>ERROR MESSAGE</error> </response>
Example Error JSON Response
{
"status" : "error",
"error" : "ERROR MESSAGE"
}
Example Error PHP Response
a:2:{s:6:"status";s:5:"error";s:5:"error";s:13:"ERROR MESSAGE";}
Authentication
Multiple API keys can be created per account, and each key can be configured to indicate which forms can be accessed, and what permissions are allowed when doing so.
Permissions are defined as:
- Info: can get the form name, certain settings, and statistics such as the # of submissions and views
- Data: can search and view data collected for the form
- Submit: can submit new entries but not view or edit data
- Write: can view or edit data, or submit new entries
| Info | Data | Submit | Write | |
|---|---|---|---|---|
| forms | Y | Y | Y | Y |
| form | Y | Y | Y | Y |
| data | N | Y | N | Y |
| submission | N | Y | N | Y |
| submit | N | N | Y | Y |
| edit | N | N | N | Y |
| delete | N | N | N | Y |
2. Methods
2.1. forms
This method returns a list of forms in an account. The response includes all of the information returned by the form method, with the exception of information about each form field and the HTML or JavaScript required to display the form.
Authentication
This method requires an API key with info, data or write permissions. The response will only list forms that the API key has access to.
Arguments
- api_key (required)
Example Request
https://www.formspring.com/api/forms?api_key=ABCDE&type=xml
Response
- forms - array containing one entry per form
- id - form id
- name - form name
- views - the number of times the form has been viewed
- submissions - the number of submissions stored for the form
- created - the date the form was created in YYYY-MM-DD HH:MM:SS format
- last_submission_id - the id of the latest submission
- last_submission_time - the timestamp of the latest submission in YYYY-MM-DD HH:MM:SS format
- url - public url for the form
- data_url - share data url with full data access (only supplied if the API key has data access)
- summary_url - share data url with summary access (only supplied if the API key has data access)
- rss_url - url to the rss feed for data (only supplied if the API key has data access)
Example XML Response:
<?xml version="1.0" encoding="utf-8"?> <response status="ok"> <forms> <form> <id>1001</id> <name>Test Form 1</name> <views>100</views> <created>2007-01-01 23:59:59</created> <submissions>100</submissions> <last_submission_id>1111</last_submission_id> <last_submission_time>2007-01-02 23:59:59</last_submission_time> <url>https://www.formspring.com/admin/data.php?1111A</url> <data_url>https://www.formspring.com/admin/data.php?1111B</data_url> <summary_url>https://www.formspring.com/admin/data.php?1111C</summary_url> <rss_url>https://www.formspring.com/admin/rss.php?1111D</rss_url> </form> <form> <id>1002</id> <name>Test Form 2</name> <views>100</views> <created>2007-02-01 23:59:59</created> <submissions>100</submissions> <last_submission_id>2222</last_submission_id> <last_submission_time>2007-02-02 23:59:59</last_submission_time> <url>https://www.formspring.com/admin/data.php?2222A</url> <data_url>https://www.formspring.com/admin/data.php?2222B</data_url> <summary_url>https://www.formspring.com/admin/data.php?2222C</summary_url> <rss_url>https://www.formspring.com/admin/rss.php?2222D</rss_url> </form> </forms> </response>
Example JSON Response:
{
"status" : "ok",
"response" : {
"forms" : [ {
"id" : "1001",
"name" : "Test Form 1",
"views" : "100",
"created" : "2007-01-01 23:59:59",
"submissions" : 100,
"last_submission_id" : "1111",
"last_submission_time" : "2007-01-02 23:59:59",
"url" : "https://www.formspring.com/admin/data.php?1111A",
"data_url" : "https://www.formspring.com/admin/data.php?1111B",
"summary_url" : "https://www.formspring.com/admin/data.php?1111C",
"rss_url" : "https://www.formspring.com/admin/rss.php?1111D"
}, {
"id" : "1002",
"name" : "Test Form 2",
"views" : "100",
"created" : "2007-02-01 23:59:59",
"submissions" : 100,
"last_submission_id" : "2222",
"last_submission_time" : "2007-02-02 23:59:59",
"url" : "https://www.formspring.com/admin/data.php?2222A",
"data_url" : "https://www.formspring.com/admin/data.php?2222B",
"summary_url" : "https://www.formspring.com/admin/data.php?2222C",
"rss_url" : "https://www.formspring.com/admin/rss.php?2222D"
} ]
}
}
Example PHP Response:
a:2:{s:6:"status";s:2:"ok";s:8:"response";a:1:{s:5:"forms";a:2:{i:0;a:11:{s:2:"id";s:4:"1001";s:4:"name";s:11:"Test Form 1";s:5:"views";s:3:"100";s:7:"created";s:19:"2007-01-01 23:59:59";s:11:"submissions";i:100;s:18:"last_submission_id";s:4:"1111";s:20:"last_submission_time";s:19:"2007-01-02 23:59:59";s:3:"url";s:47:"https://www.formspring.com/admin/data.php?1111A";s:8:"data_url";s:47:"https://www.formspring.com/admin/data.php?1111B";s:11:"summary_url";s:47:"https://www.formspring.com/admin/data.php?1111C";s:7:"rss_url";s:46:"https://www.formspring.com/admin/rss.php?1111D";}i:1;a:11:{s:2:"id";s:4:"1002";s:4:"name";s:11:"Test Form 2";s:5:"views";s:3:"100";s:7:"created";s:19:"2007-02-01 23:59:59";s:11:"submissions";i:100;s:18:"last_submission_id";s:4:"2222";s:20:"last_submission_time";s:19:"2007-02-02 23:59:59";s:3:"url";s:47:"https://www.formspring.com/admin/data.php?2222A";s:8:"data_url";s:47:"https://www.formspring.com/admin/data.php?2222B";s:11:"summary_url";s:47:"https://www.formspring.com/admin/data.php?2222C";s:7:"rss_url";s:46:"https://www.formspring.com/admin/rss.php?2222D";}}}}
2.2. form
This method returns detailed information about a form.
Authentication
This method requires an API key with info, data or write permissions for the form. If the API key does not have permissions to access the form, a 404 (not found) will be returned.
Arguments
- api_key (required)
- id - form id (required)
Example Request
https://www.formspring.com/api/form?api_key=ABCDE&type=xml&id=100
Response
- name - form name
- views - the number of times the form has been viewed
- submissions - the number of submissions stored for the form
- created - the date the form was created in YYYY-MM-DD HH:MM:SS format
- last_submission_id - the id of the latest submission
- last_submission_time - the timestamp of the latest submission in YYYY-MM-DD HH:MM:SS format
- url - public url for the form
- data_url - share data url with full data access (only supplied if the API key has data access)
- summary_url - share data url with summary access (only supplied if the API key has data access)
- rss_url - url to the rss feed for data (only supplied if the API key has data access)
- javascript - contents of the javascript code required to embed the form within an external page
- html - contents of the full html code used to construct the form
- fields - array containing one entry per field on the form
- id - field id
- label - field label
- name - name of the field, used when submitting
- type - field type (one of text, textarea, select, checkbox, radio, datetime, email or file)
- options - list of options set for the field (if applicable)
- label - option label
- value - option value
- default - default value for the field
- required - "1" or "0" depending on whether or not the field is required
Example XML Response
<?xml version="1.0" encoding="utf-8"?> <response status="ok"> <name>Test Form</name> <views>100</views> <created>2007-01-01 23:59:59</created> <submissions>100</submissions> <last_submission_id>9999</last_submission_id> <last_submission_time>2007-02-02 23:59:59</last_submission_time> <url>https://www.formspring.com/admin/data.php?11111</url> <data_url>https://www.formspring.com/admin/data.php?11112</data_url> <summary_url>https://www.formspring.com/admin/data.php?11113</summary_url> <rss_url>https://www.formspring.com/admin/rss.php?11114</rss_url> <html></html> <javascript></javascript> <fields> <field> <id>1001</id> <label>First Name</label> <name>first_name</name> <type>text</type> <options></options> <default></default> <required>1</required> </field> <field> <id>1002</id> <label>State</label> <name>state</name> <type>select</type> <options> <option> <label>Idaho</label> <value>Idaho</value> </option> <option> <label>Illinois</label> <value>Illinois</value> </option> <option> <label>Indiana</label> <value>Indiana</value> </option> <option> <label>Iowa</label> <value>Iowa</value> </option> </options> <default>Indiana</default> <required>0</required> </field> </fields> </response>
Example JSON Response
{
"status" : "ok",
"response" : {
"name" : "Test Form",
"views" : "100",
"created" : "2007-01-01 23:59:59",
"submissions" : 100,
"last_submission_id" : "9999",
"last_submission_time" : "2007-02-02 23:59:59",
"url" : "https://www.formspring.com/admin/data.php?11111",
"data_url" : "https://www.formspring.com/admin/data.php?11112",
"summary_url" : "https://www.formspring.com/admin/data.php?11113",
"rss_url" : "https://www.formspring.com/admin/rss.php?11114",
"html" : "",
"javascript" : "",
"fields" : [ {
"id" : "1001",
"label" : "First Name",
"name" : "first_name",
"type" : "text",
"options" : [ ],
"default" : "",
"required" : "1"
}, {
"id" : "1002",
"label" : "State",
"name" : "state",
"type" : "select",
"options" : {
"1" : {
"label" : "Idaho",
"value" : "Idaho"
},
"2" : {
"label" : "Illinois",
"value" : "Illinois"
},
"3" : {
"label" : "Indiana",
"value" : "Indiana"
},
"4" : {
"label" : "Iowa",
"value" : "Iowa"
}
},
"default" : "Indiana",
"required" : "0"
} ]
}
}
Example PHP Response
a:2:{s:6:"status";s:2:"ok";s:8:"response";a:13:{s:4:"name";s:9:"Test Form";s:5:"views";s:3:"100";s:7:"created";s:19:"2007-01-01 23:59:59";s:11:"submissions";i:100;s:18:"last_submission_id";s:4:"9999";s:20:"last_submission_time";s:19:"2007-02-02 23:59:59";s:3:"url";s:47:"https://www.formspring.com/admin/data.php?11111";s:8:"data_url";s:47:"https://www.formspring.com/admin/data.php?11112";s:11:"summary_url";s:47:"https://www.formspring.com/admin/data.php?11113";s:7:"rss_url";s:46:"https://www.formspring.com/admin/rss.php?11114";s:4:"html";s:0:"";s:10:"javascript";s:0:"";s:6:"fields";a:2:{i:0;a:7:{s:2:"id";s:4:"1001";s:5:"label";s:10:"First Name";s:4:"name";s:10:"first_name";s:4:"type";s:4:"text";s:7:"options";a:0:{}s:7:"default";s:0:"";s:8:"required";s:1:"1";}i:1;a:7:{s:2:"id";s:4:"1002";s:5:"label";s:5:"State";s:4:"name";s:5:"state";s:4:"type";s:6:"select";s:7:"options";a:4:{i:1;a:2:{s:5:"label";s:5:"Idaho";s:5:"value";s:5:"Idaho";}i:2;a:2:{s:5:"label";s:8:"Illinois";s:5:"value";s:8:"Illinois";}i:3;a:2:{s:5:"label";s:7:"Indiana";s:5:"value";s:7:"Indiana";}i:4;a:2:{s:5:"label";s:4:"Iowa";s:5:"value";s:4:"Iowa";}}s:7:"default";s:7:"Indiana";s:8:"required";s:1:"0";}}}}
2.3. data
This method returns data collected for a form.
Authentication
This method requires an API key with data or write permissions for the form. If the API key does not have permissions to access the form, a 404 (not found) will be returned
Arguments
- api_key (required)
- id - form id (required)
- encryption_password - data encryption password, if one is set. (optional)
- min_time - only entries submitted after this date will be returned. YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format is expected. (optional)
- max_time - only entries submitted before this date will be returned. YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format is expected. (optional)
- search_field_x - x must be a number 0-9. name or id of the field that should be searched. should be paired with search_value_x. not implemented for encrypted data. (optional)
- search_value_x - x must be a number 0-9. text that should be searched for within the corresponding search_field_x field. at this time all searches are case-insensitive "contains" searches. not implemented for encrypted data. (optional)
- per_page - number of results to return per page. the default is 25 and the maximum value is 100. (optional)
- page - the page of results that should be returned. the default is 1. (optional)
Example Request
https://www.formspring.com/api/data?api_key=ABCDE&id=111&min_date=2007-04-04&per_page=100&search_field_0=first_name&search_value_0=john&search_field_1=last_name&search_value_1=smith
Response
- total - the total number of submissions that match the search
- pages - the total number of pages of results, given the per_page value
- submissions - array containing one entry per form submission
- id - submission id, unique to each entry
- timestamp - date/time of the submission in YYYY-MM-DD HH:MM:SS format.
- user_agent - user agent string taken from the submitter's browser
- remote_addr - IP address taken from the submitter
- data - key/value pairs, with one entry per field on the form
- field - field id
- value - the value that was submitted for this field
Example XML Response
<?xml version="1.0" encoding="utf-8"?> <response status="ok"> <submissions> <submission> <id>1001</id> <timestamp>2007-01-01 01:01:01</timestamp> <user_agent>Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)</user_agent> <remote_addr>127.0.0.1</remote_addr> <data> <item> <field>1111</field> <value>John Smith</value> </item> <item> <field>2222</field> <value>Apple</value> </item> </data> </submission> <submission> <id>1001</id> <timestamp>2007-02-02 02:02:02</timestamp> <user_agent>Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)</user_agent> <remote_addr>127.0.0.1</remote_addr> <data> <item> <field>1111</field> <value>Jane Smith</value> </item> <item> <field>2222</field> <value>Banana</value> </item> </data> </submission> </submissions> <total>2</total> <pages>1</pages> </response>
Example JSON Response
{
"status" : "ok",
"response" : {
"submissions" : [ {
"id" : "1001",
"timestamp" : "2007-01-01 01:01:01",
"user_agent" : "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)",
"remote_addr" : "127.0.0.1",
"data" : [ {
"field" : "1111",
"value" : "John Smith"
}, {
"field" : "2222",
"value" : "Apple"
} ]
}, {
"id" : "1001",
"timestamp" : "2007-02-02 02:02:02",
"user_agent" : "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)",
"remote_addr" : "127.0.0.1",
"data" : [ {
"field" : "1111",
"value" : "Jane Smith"
}, {
"field" : "2222",
"value" : "Banana"
} ]
} ],
"total" : 2,
"pages" : 1
}
}
Example PHP Response
a:2:{s:6:"status";s:2:"ok";s:8:"response";a:3:{s:11:"submissions";a:2:{i:0;a:5:{s:2:"id";s:4:"1001";s:9:"timestamp";s:19:"2007-01-01 01:01:01";s:10:"user_agent";s:50:"Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)";s:11:"remote_addr";s:9:"127.0.0.1";s:4:"data";a:2:{i:0;a:2:{s:5:"field";s:4:"1111";s:5:"value";s:10:"John Smith";}i:1;a:2:{s:5:"field";s:4:"2222";s:5:"value";s:5:"Apple";}}}i:1;a:5:{s:2:"id";s:4:"1001";s:9:"timestamp";s:19:"2007-02-02 02:02:02";s:10:"user_agent";s:50:"Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)";s:11:"remote_addr";s:9:"127.0.0.1";s:4:"data";a:2:{i:0;a:2:{s:5:"field";s:4:"1111";s:5:"value";s:10:"Jane Smith";}i:1;a:2:{s:5:"field";s:4:"2222";s:5:"value";s:6:"Banana";}}}}s:5:"total";i:2;s:5:"pages";i:1;}}
2.4. submission
This method returns a single submission collected for a form.
Authentication
This method requires an API key with data or write permissions for the form. If the API key does not have permissions to access the form, a 404 (not found) will be returned
Arguments
- api_key (required)
- id - submission id (required)
- encryption_password - data encryption password, if one is set. (optional)
Example Request
https://www.formspring.com/api/submission?api_key=ABCDE&id=1001
Response
- id - submission id, unique to each entry
- timestamp - date/time of the submission in YYYY-MM-DD HH:MM:SS format.
- user_agent - user agent string taken from the submitter's browser
- remote_addr - IP address taken from the submitter
- data - key/value pairs, with one entry per field on the form
- field - field id
- value - the value that was submitted for this field
Example XML Response
<?xml version="1.0" encoding="utf-8"?> <response status="ok"> <id>1001</id> <timestamp>2007-01-01 01:01:01</timestamp> <user_agent>Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)</user_agent> <remote_addr>127.0.0.1</remote_addr> <data> <item> <field>1111</field> <value>John Smith</value> </item> <item> <field>2222</field> <value>Apple</value> </item> </data> </response>
Example JSON Response
{
"status" : "ok",
"response" : {
"id" : "1001",
"timestamp" : "2007-01-01 01:01:01",
"user_agent" : "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)",
"remote_addr" : "127.0.0.1",
"data" : [ {
"field" : "1111",
"value" : "John Smith"
}, {
"field" : "2222",
"value" : "Apple"
} ]
}
}
Example PHP Response
a:2:{s:6:"status";s:2:"ok";s:8:"response";a:5:{s:2:"id";s:4:"1001";s:9:"timestamp";s:19:"2007-01-01 01:01:01";s:10:"user_agent";s:50:"Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)";s:11:"remote_addr";s:9:"127.0.0.1";s:4:"data";a:2:{i:0;a:2:{s:5:"field";s:4:"1111";s:5:"value";s:10:"John Smith";}i:1;a:2:{s:5:"field";s:4:"2222";s:5:"value";s:5:"Apple";}}}}
2.5. submit
This method submits data to a form. This method does not honor any validation or default values configured for a field. It also does not trigger any auto-responders or email notifications. It is designed to be useful to import data into the database, because of the lack of validation checks, it is not intended for day-to-day use for public submissions.
The form must be configured to store submissions in the database. An error will be returned if the maximum number of submissions for the account has been reached.
Authentication
This method requires an API key with write permissions for the form. If the API key does not have permissions to access the form, a 404 (not found) will be returned.
Arguments
- api_key (required)
- id - form id (required)
- timestamp - the time that should be recorded for the submission. YYYY-MM-DD HH:MM:SS format is expected. defaults to the current time. (optional)
- user_agent - browser user agent value that should be recorded for the submission. defaults to value in the request User-Agent header, or blank if none is found. (optional)
- remote_addr - IP address that should be recorded for the submission. defaults to the IP address from the API request. (optional)
- field_x - value that should be stored for a specific field on the form. x must contain the id of the field whose value should be set. (optional)
Example Request
https://www.formspring.com/api/submit?api_key=ABCDE&id=111&field_1001=john&field_1002=smith
Response
- id - the id of the new submission, unique to each entry
Example XML Response
<?xml version="1.0" encoding="utf-8"?> <response status="ok"> <id>10001</id> </response>
Example JSON Response
{
"status" : "ok",
"response" : {
"id" : 10001
}
}
Example PHP Response
a:2:{s:6:"status";s:2:"ok";s:8:"response";a:1:{s:2:"id";i:10001;}}
File Uploads
Files can be uploaded via the API in a similar way text values are passed, except that file contents must be base64 encoded before transfer. You can also optionally specify the file name to use by pre-pending it to the data along with a semicolon. e.g.:
https://www.formspring.com/api/submit?api_key=ABCDE&id=111&field_1001=hello.txt;SGVsbG8hIFRoYW5rcyBmb3IgdXNpbmcgdGhlIEZvcm1TcHJpbmcgQVBJLg==
2.6. edit
This method makes changes to an existing submission. Only values supplied within the API arguments will be overwritten.
File uploads are not currently supported
Authentication
This method requires an API key with write permissions for the form. If the API key does not have permissions to access the form, a 404 (not found) will be returned.
Arguments
- api_key (required)
- id - submission id (required)
- timestamp - the time that should be recorded for the submission. YYYY-MM-DD HH:MM:SS format is expected. the existing timestamp will be preserved if left blank. (optional)
- user_agent - browser user agent value that should be recorded for the submission. the existing user agent will be preserved if left blank. (optional)
- remote_addr - IP address that should be recorded for the submission. the existing ip address will be preserved if left blank. (optional)
- field_x - value that should be stored for a specific field on the form. x must contain the id of the field whose value should be changed. (optional)
Example Request
https://www.formspring.com/api/edit?api_key=ABCDE&id=10001&field_1001=john&field_1002=smith
Response
- id - the id of the updated submission
Example XML Response
<?xml version="1.0" encoding="utf-8"?> <response status="ok"> <id>10001</id> </response>
Example JSON Response
{
"status" : "ok",
"response" : {
"id" : 10001
}
}
Example PHP Response
a:2:{s:6:"status";s:2:"ok";s:8:"response";a:1:{s:2:"id";i:10001;}}
2.7. delete
This method deletes an existing submission.
Authentication
This method requires an API key with write permissions for the form. If the API key does not have permissions to access the form, a 404 (not found) will be returned.
Arguments
- api_key (required)
- id - submission id (required)
- encryption_password - data encryption password, if one is set. (optional)
Example Request
https://www.formspring.com/api/delete?api_key=ABCDE&id=10001
Response
- id - the id of the deleted submission
Example XML Response
<?xml version="1.0" encoding="utf-8"?> <response status="ok"> <id>10001</id> </response>
Example JSON Response
{
"status" : "ok",
"response" : {
"id" : 10001
}
}
Example PHP Response
a:2:{s:6:"status";s:2:"ok";s:8:"response";a:1:{s:2:"id";i:10001;}}
3. Examples
3.1. PHP Examples
Download the FormSpring PHP example files.
3.2. .NET Examples
A .NET wrapper around the FormSpring API is available. The wrapper is targeted for the .NET 3.0 Framework or Mono 2.0.1. The wrapper abstracts away the HTTP calls to the FormSpring API and allows you to make requests with native .NET objects as parameters.
The FormSpring.dll and an example project are available for download.
3.3. Mashups and Widgets





