Merge branch 'master' into docs

api/invites.rst

@@ -199,12 +199,15 @@ Creating a new email
 .. http:post:: /api/v2/emails/
 
     Creates a new email. Data must be sent as an :mimetype:`application/json`-encoded
-    dictionary.
+    dictionary.  Which must included the fields ``subject``, ``sender``, and ``message``.
+
+    ``Sender`` must be in the form ``"Name <email@example.com>"`` and ``message`` must include the string "``[Invite Link]``" in it.  This token is replaced with the URL at which the recipient may take the survey.
 
     Sample request::
 
       {
 	"subject": "Email subject",
+	"sender": "John Doe <john@google.com>",
 	"message": "Dear [Full Name],\n\nMessage body: [Invite Link]"
       }
 
@@ -258,3 +261,104 @@ Removing recipients
 .. http:delete:: /api/v2/emails/:id/recipients/
 
     Deletes recipients from an email.
+
+Example
+-------
+
+    Let's write a quick python script to create a contact and add them to an email:
+
+Set up
+`````
+	We will be using the **requests** module to easily handle the details of HTTP requests. You can find out more about it at http://docs.python-requests.org. ::
+	
+		import requests, json
+		
+	We are also using the built in **json** module to send and receive all the json data we will be working with.  We will also need your API key (which you can find on your FluidSurveys settings page) and your password. ::
+	
+		API_KEY = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+		PASSWORD = 'password'
+		
+	We'll also save the base URI and Headers in some variables: ::
+
+		headers = {"Content-Type": "application/json"}
+		URI = 'https://app.fluidsurveys.com/api/v2/'
+		
+Create a Contact
+````````````````
+	To create a contact all we need is a *name* and *e-mail*::
+	
+		payload = {"name":"John Doe", "email":"johndoe@gmail.com"}
+		r = requests.post(URI+'contacts/', data=json.dumps(payload), 
+			headers=headers, auth=(api_key, password))
+		result = json.loads(r.content)
+		contact_id = result['contact']['id']
+		
+	Here we set the data we are going to attach to our POST request in the variable *payload*.  We use the **requests** module's *post* method with our headers, authentication details and our payload formatted as json.
+
+	Note that you will get an error message if you try and add a contact that already exists.  We are **not** doing any error checking for the purposes of this example but of course, you always **should**.
+
+Get our Surveys
+```````````````
+
+	A quick ``GET`` to ``/surveys/`` will return all our surveys.  We are just taking the first one here, but you can filter them however you would like::
+	
+		r = requests.get(URI+'surveys/',auth=(api_key,password))
+		result = json.loads(r.content)
+		survey_id = result['surveys'][0]['id']
+		
+Create an Email
+```````````````
+
+	Your email request must include a *subject*, *sender*, and *message*.  The *message* must include the string *[Invite Link]* and the sender must be formatted as ``'Name <email@domain.com>'``::
+
+		payload = {"subject":"Hello",
+			"message":"Hi, [Full Name], check out our survey: [Invite Link]!",
+			"sender":"Me <me@example.com>"
+			}
+		r = requests.post(URL+'emails/?survey=%d' % (survey_id,), 
+			data=json.dumps(payload), 
+			headers=headers, auth=(api_key,password))
+		result = json.loads(r.content)
+		send_uri = result['send_uri']
+		email_id = result['id']
+		recipients_uri = result['recipients_uri']
+		
+	The response returns uris for adding recipients and sending the email which we will use to finish our script.
+
+
+Add Contact to Email
+````````````````````
+
+	We do not need to send a single contact as json, we can simply ``POST``::
+
+		r = requests.post(recipients_uri, data='contacts=%d' % (contact_id,),
+		 	auth=(api_key,password))
+		
+Send Email
+``````````
+
+	Sending the email is just as easy, just *POST* to the send_uri we got when we created the email::
+	
+		r = requests.post(send_uri, headers={"Content-Length": '0'}, 
+			auth=(api_key,password))
+		
+	Note we have to specifiy ``Content-Length = 0`` in the headers when were are POSTing no data.  If everything went as planned you should get a response similar to::
+	
+		{
+			u'status': u'scheduled',
+			u'scheduled': u'2012-01-26T22:51:29Z',
+			u'sender': u'Me <me@example.com>',
+			u'footer': None,
+			u'created_at': u'2012-01-26T22:46:28Z',
+			u'num_recipients': 1,
+			u'updated_at': u'2012-01-26T22:46:28Z',
+			u'message': u'Hi, [Full Name], check out our survey: [Invite Link]!',
+			u'id': 25206,
+			u'subject': u'Hello'
+		}
+
+Source
+``````
+	Download the source file:
+
+	`Python <https://raw.github.com/chideit/fluidsurveys-docs/master/samples/email_contact/email_contact.py>`_  `PHP <https://raw.github.com/chideit/fluidsurveys-docs/master/samples/email_contact/email_contact.php>`_

api/surveys.rst

@@ -26,12 +26,33 @@ Getting a list of surveys
 	  }]
 	}
 
+
+Survey Status
+`````````````
+
+.. http:get:: /api/v2/surveys/:id/status/
+
+	Returns a JSON object with status either "live" or "closed".
+
+    Sample response: ::
+
+	{
+		"status" : "live"
+	}
+
+.. http:post:: /api/v2/surveys/:id/status/
+
+	Toggles the survey status from *closed* to *live* and vice versa.
+	Optionally, you can pass a switch parameter with the value `closed` or `live` to set it to a specific status.
+
+.. http:post:: /api/v2/surveys/:id/status/?switch=closed
+
 Getting survey details
 ``````````````````````
 
 .. http:get:: /api/v2/surveys/:id/
 
-    Returns details about the specified survey. This method returns data in
+    Returns summary details about the specified survey. This method returns data in
     :mimetype:`application/json` format.
 
     Sample response: ::
@@ -52,6 +73,12 @@ Getting survey details
 	    }
 	  }
 	}
+
+You may also send a GET parameter called `structure` to receive the entire survey object.
+
+.. http:get:: /api/v2/surveys/:id/?structure
+
+    This may be useful if you require advanced information such as if a question is required or not. 
 
 Getting survey responses
 ````````````````````````
@@ -64,7 +91,14 @@ Getting survey responses
     format.
 
     :query offset: response pagination offset (defaults to 0).
-    :query limit: maximum number of results to return (defaults to 10).
+    :query limit: maximum number of results to return (defaults to 50 max is 200).
+    :query filter: name of the filter you wish to filter responses by
+    Example:
+
+.. http:get:: /api/v2/surveys/:id/responses/?filter=myfilter
+
+    Filters are created from the web interface and are on a **per-survey basis**.  You may also use one of the pre-defined filters: *completed*, *invite_emails*, or *invite_codes*.
+
 
     Sample response: ::
 
@@ -86,6 +120,46 @@ Creating a new response
 
     Creates a new response to the survey specified by ``id``.
 
+Submitting a new response
+`````````````````````````
+
+.. http:post:: /api/v2/surveys/:id/responses/
+
+    *Note:* Submitting responses currently only works on single page surveys.
+
+    Submits a new response.  Send a post request as *application/json* with a dictionary of question ids and response values.
+
+    You will get a ``{success:true, id:response_id}`` response if your request was successful.
+
+    If there is an error, the sever will return a **status code 500** with JSON:
+
+    Example: ::
+
+	import requests, json
+	uri = 'https://app.fluidsurveys.com/api/v2/survey/55023/responses/'
+	API_KEY = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+	PASSWORD = 'password'
+	headers = {'Content-Type': 'application/json'}
+	payload = {'DiBzfaXB6b': '3'}	#must post strings
+	r = requests.post(uri,data=json.dumps(payload), 
+		headers=headers, auth=(API_KEY,PASSWORD))
+	response = r.content	
+
+    Sample response: ::
+
+	{
+	  "code": "survey_error",
+	  "description": [
+	                  ["DiBzfaXB6b", "'3' is not a valid choice for this field"],
+	                  ["5yEXFv1Bob", "An answer to this question is required."]
+	                 ]
+	}
+
+    You can also send a standard *application/x-www-form-urlencoded* POST request.  e.g. ::
+
+	5yEXFv1Bob=hello%20world&zIthHJ9tvZ=0&DiBzfaXB6b=1
+
+
 Deleting responses
 ``````````````````