API
The UserBob API is a REST based API. A sample PHP based site using the UserBob API is available on github. All API requests should have a base URL of https://userbob.com/
The following parameters must be passed on every api call.| apiKey | get key |
| clientId | 0 |
You must keep the value of the apiKey private. Otherwise, anyone who learns your apiKey would be able to start tests and they would get charged to your account. So do not make UserBob api requests from your public web site pages or from a public app. Instead have your app or website make a request to your webserver and have the webserver call the UserBob API. If you suspect that your apiKey has been leaked, you will need to reset the apiKey.
apiGetBalance
This method returns the amount of unused funds that are credited to your account.
(Currently to add funds to your account you must use the
https://userbob.com/addFunds page.)
A successful response would look like:
{ "balance": 39.0 }
apiCreateTest
This method creates a test but does not start it. After successfully calling this method, you would want to call apiStartTest passing the test id that was returned. You must pass the following parameters with this request:
A successful response would look like:{ "testId": 1234, "cost": 1.00 }
apiStartTest
This method deducts the appropriate amount from your balance and starts the process of recruiting users to complete the test. You must pass a testId parameter matching a testId which was returned by an apiCreateTest request. If you specify a Webhook URL above, a request will be made to that URL whenever a user submits a video for any of your tests.
A successful response would look like:{ "started": true }
An unsuccessful response would look like:
{ "error": "error message" }
apiAbortTest
This method starts the process of aborting a test. You must pass a testId parameter with a testId matching a test that you started with the apiStartTest request. If any users have already accepted the test, they will be allowed to complete it. So the abortion process could potentially take around 30 minutes to complete.
A successful response would look like:{ "aborting": true }
An unsuccessful response would look like:
{ "error": "error message" }
apiGetTestResults
This method returns an array of test results for all of your tests. The results will be in order by their ids. If the minTestResultId parameter is specified, then any results with ids less than that value will not be returned. So typically you would call this method and then store the max id that was returned so that the next time you call this method you could pass a minTestResultId value that was 1 greater than that max value so that only new results would be returned. You could poll this method every few minutes and/or call it after receiving a call to your webhook URL. At most 100 results will be returned at a time.
A successful response would look like:
[
{"id":"1001", "rcvdTime":"2015-09-22T16:05:07+0000", "testId":"379", "workerId":"30755", "videoId":"942", "code":"123456"},
{"id":"1004", "rcvdTime":"2015-09-22T16:30:55+0000", "testId":"379", "workerId":"30756", "videoId":"945", "code":"987654"},
{"id":"1007", "rcvdTime":"2015-09-22T17:02:45+0000", "testId":"379", "workerId":"30758", "videoId":"948", "code":"102934"}
]
A video file can be downloaded or streamed from a URL in the following format:
https://userbob.com/servlet/screencast?download=true&id=<videoId>&code=<code>
Video files get deleted from UserBob's server 30 days after they were created. So if you want to be able to view them after
that length of time you will need to download and store them before that time.
apiGetWorkerInfo
This method returns demographic information about a particular worker. You must pass a numeric workerId parameter with a value corresponding to a workerId that was included in a response to apiGetTestResults request.
A sample response would be: {"id":"4", "alias":"SuperMan", "demographics":"Male, Born: 1966, From: Suburban, OK, Married, people in house: 4, kids in house: 2, pets: Yes, College 4yr, occupation: computer programmer, favorite movie: Up, favorite website: studystack.com, userbob.com, hobbies: computer programming, French Horn, computer: Windows, browser: Chrome, smartphone: Android, income: 100,000 or more"}apiRateResult
This method rates a result video. You must pass a resultId parameter matching an id previously returned by apiGetTestResults. Workers of any results that you rate Useless will be blocked from completing any more of your tests in the future.
A successful response would look like:{ "rated": true }
An unsuccessful response would look like:
{ "error": "error message" }