Introduction

Overview

The API provided by HumanAPI allows you to schedule a range of different tasks for completion by our team of virtual assistants.

The Request

An HTTPS call is made from your software to the HumanAPI server giving details of the task to be performed. Tasks are automatically allocated and scheduled for completion by members of the HumanAPI assistant team.

The Response

When the assistant completes your task, HumanAPI executes an HTTP or HTTPS call back to your server with an update on the task, and details of the outcome - for example the success of the task, name of the hotel that was booked, etc.

Transport Layer

All communication with HumanAPI is provided over Secure HTTP (HTTPS).

Commands to be sent to HumanAPI - such as requests for new tasks, should be posted the following URL:

https://secure.comcetera.com/humanapi

Callbacks from HumanAPI to your server (containing progress or status updates) can be posted to any URL of your choice, http or https - though we highly recommend https if you have it available, or if you are dealing with any kind of sensitive information.

Mandatory parameters for all calls

All requests much include parameter "user" and "pass", which should be set to your HumanAPI account username and password.

Scheduling a new task

Introduction

To schedule a new task to be performed by a HumanAPI Assistant, you should make an HTTPS call of the form:

https://secure.comcetera.com/humanapi?user=xx&pass=yy&action=newtask&task=TYPE&p1=xx&p2=yy

Request Parameters

Parameter Description user Your HumanAPI username pass Your HumanAPI password action newtask task Type of task to schedule (See list below) geocontext Geographical Context * subuser Sub user account * p1 p2 etc Task-specific parameters (See list below)

The additional parameters required (p1 p2 etc) will depend on the type of task you are requesting; For example, if you are requesting a call to be made to deliver a message, the parameters will include the phone number to call, who to ask for, and the message to be dictated by the assistant.

There is complete list of available tasks, and their required parameters below.

* Geographical context is an optional, but highly recommended parameter which will give the assistant working on your task a geographical context in which to work; If known, you should pass the location of the user requesting the task as a textual string, for example "London, UK". This helps the assistant to find relevant information; For example, if you requested a hotel in Cambridge, the geographical context would confirm whether this was Cambridge UK, or Cambridge Massachusetts, based on the geographical context of the user asking for the reservation.

* Sub User account is an optional, but highly recommended parameter which allows you to specify a unique username to be matched with the request. This enables HumanAPI to group together tasks from the same person, making it easy for the assistant to check the task history in case of a follow-up task, for example a QUESTION task of: "What time is breakfast at my hotel?" - would require the assistant to look back through the task history to locate the hotel where the user is staying.

Example API Call to schedule a new task

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=CALL&
PHONE=447785123456&ASKFOR=John+Smith&MESSAGE=Your+car+is+now+ready.+Please+call+
in+to+collect+it.

Response to a task request

HumanAPI will respond to your HTTP request with an HTTP response containing a ticket number for your new task, as shown in the example below:

Example HTTP(S) response to a "newtask" request:

HTTP/1.1 200 OK
Date: Sun, 06 Jul 2008 23:16:06 GMT
Server: Apache/1.3.34 (Debian) mod_gzip/1.3.26.1a PHP/4.4.4-8+etch6 DAV/1.0.3
Connection: close
Content-Type: text/plain; charset=iso-8859-1

OK ID 28378912378

When HumanAPI makes a callback to update you on the progress of the task, this ticket number will be passed as the "taskid" parameter by the HumanAPI server in order to identify the task being updated. See the section below, entitled "Updated on status of a task" for more information.

Updates on status of a task

Introduction

When a task has been completed, or has failed, HumanAPI will make a call to a pre-defined address on your server with an update on the status of the task. You will need to specify the location of this URL on your server when setting up your HumanAPI account.

Report Parameters

HumanAPI will provide the following parameters:

Parameter Meaning taskid A unique ID / tracking number for the task taskstatus Current status of task: either 'COMPLETED' or 'INAPPROPRIATE' ... Additional parameters depending on type of task

Task Status / Inappropriate Tasks

A task status of 'COMPLETED' indicates that the task was either completed successfully, or that work was performed on the task to follow it to the best possible conclusion (for example a call may have been made, but the person may not have been available). The 'Additional Parameters' should indicate more details on the success of the task performed. A 'COMPLETED' response simply indicates that work was performed on the task, and no further work will be performed on it.

If a task is deemed by our virtual assistants to be inappropriate (illegal, bad language, nonsense, or in any way an inappropriate request) they will mark the task as inappropriate and you will receive taskstatus=INAPPROPRIATE. If you account generates a large volume of inappropriate requests, we may, at our discretion add a small processing fee for each inappropriate task to cover the time of our virtual assistance in identifying these.

Additional Parameters

The additional parameters provided will depend on the type of task requested, and the type of information generated by forming such a task. For example, if the task was to transcribe an audio file into text, one of the parameters will include the text.

There is complete list of available tasks, and their response parameters below.

Available Task types and Parameters

Task Type: 'BUY' - Buy Something

Description: Buy Something via an online store or telephone

Request Parameters:

Example Request for Task 'BUY':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=BUY&I
TEM=1+Small+bag+of+lemons&BILLING=Card+123456789012+Exp+08%2F20+CVV212+Mr+Bob+Jo
nes+12+Mr+Street%2C+Anytown&BUDGET=GBP10&VENDOR=Tesco&DELIVERYTO=%2212+Long+Gard
ens%2C+Bournemouth+BH1+1AA%22&EXTRAINFO=Leave+on+doorstep+if+I'm+not+home

Example Response Callback for Task 'BUY':

https://your.server.com/human-response.php?taskid=278372819&ITEMFOUND=1&CARDACCE
PTED=1&COMPLETE=1&VENDORUSED=Tesco&AMOUNTSPENT=GBP+8.50&NOTES=Should+be+delivere
d+before+5PM

Task Type: 'CALL' - Call with message

Description: Call someone to pass on a message

Request Parameters:

Example Request for Task 'CALL':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=CALL&
PHONE=447785123456&ASKFOR=John+Smith&ONBEHALF=Peter+Smith+of+Acme+Widgets+Inc&ME
SSAGE=Your+car+is+now+ready.+Please+call+in+to+collect+it.

Example Response Callback for Task 'CALL':

https://your.server.com/human-response.php?taskid=278372819&CONNECTED=1&AVAILABL
E=1&SPOKETO=1&VOICEMAIL=1&RESPONSE=He+said+see+you+at+2PM

Task Type: 'CALLINFO' - Call for info

Description: Call someone to collect information

Request Parameters:

Example Request for Task 'CALLINFO':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=CALLI
NFO&PHONE=447785123456&ASKFOR=John+Smith&MESSAGE=%22Hi%2C+This+is+%85.+Calling+f
rom+the+flower+shop+to+get+your+card+info%22&QUESTION1=Can+I+take+the+main+card+
number%3F&QUESTION2=Can+I+take+the+expiration+date+(MM%2FYY)&QUESTION3=And+what+
is+the+address+where+your+card+is+registerd&QUESTION4=And+your+name+as+it+appear
s+on+the+card%3F&QUESTION5=&QUESTION6=&ENDOFCALL=Thanks+for+the+info+-+we'll+get
+your+order+processed+promptly.

Example Response Callback for Task 'CALLINFO':

https://your.server.com/human-response.php?taskid=278372819&CONNECTED=1&AVAILABL
E=1&THIRDPARTY=0&VOICEMAIL=0&ANSWER1=&ANSWER2=&ANSWER3=&ANSWER4=&ANSWER5=&ANSWER
6=&COMPLETED=&NOTES=

Task Type: 'CONTRACTOR' - Contractor

Description: Arrange a contractor to do some work

Request Parameters:

Example Request for Task 'CONTRACTOR':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=CONTR
ACTOR&ITEM=Plumber&BUDGET=GBP+100&VENDOR=Acme+Plumbing&PURPOSE=Replace+washer+on
+kitchen+sink&LOCATION=%2212+Long+Gardens%2C+Bournemouth+BH1+1AA%22&DATETIME=01%
2F01%2F2008+10%3A00&NOTES=Please+send+Gary+if+available

Example Response Callback for Task 'CONTRACTOR':

https://your.server.com/human-response.php?taskid=278372819&ITEMFOUND=1&AVAILABL
E=1&RESERVEDOK=1&VENDORUSED=Acme+Plumbing+01202+237100&CONFIRMTIME=01%2F01%2F200
8+10%3A00&BOOKINGREF=ACME123&NOTES=May+arrive+10AM+-+2PM"E=100GBP+per+hour

Task Type: 'COURIER' - Courier Pickup

Description: Arrange a courier package pickup

Request Parameters:

Example Request for Task 'COURIER':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=COURI
ER&BILLING=&BUDGET=&COURIER=UPS&PICKUP=01%2F01%2F2008+12%3A34&FROM=%2212+Long+Ga
rdens%2C+Bournemouth+BH1+1AA%22&TO=%2234+Short+Walk%2C+Poole+BH18+1AA%22&WEIGHT=
3KG&DIMENSIONS=12cmx12cmx19cm&NOTES=Insure+for+GBP200.00

Example Response Callback for Task 'COURIER':

https://your.server.com/human-response.php?taskid=278372819&COURIERFOUND=0&CARDA
CCEPTED=0&COURIERUSED=UPS&COMPLETE=1&DEPART=%2212+Long+Gardens%2C+before+5PM%22&
BOOKINGREF=1Z0010001002938273&NOTES=Please+have+account+details+ready+for+driver

Task Type: 'DIRECTORY' - Look up a phone number/address

Description: Look up a phone number/address

Request Parameters:

Example Request for Task 'DIRECTORY':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=DIREC
TORY&NAME=John+Smith&LOCATION=Bournemouth%2C+UK&EXTRAINFO=Lives+on+Exeter+Rd

Example Response Callback for Task 'DIRECTORY':

https://your.server.com/human-response.php?taskid=278372819&FOUND=1&PHONENUMBER=
01202237100&ADDRESS=99910+Exeter+Road%2C+Bournemouth+BH1+1AA

Task Type: 'DOCUMENT' - DOCUMENT

Description: Print and Mail a Document

Request Parameters:

Example Request for Task 'DOCUMENT':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=DOCUM
ENT&CONTENT=&MAILTO=Mr+John+Smith%2C+12+Brookwood+Court%2C+Bournemouth%2C+UK+BH2
+5RR

Example Response Callback for Task 'DOCUMENT':

https://your.server.com/human-response.php?taskid=278372819&PRINTED=&NAMESENT=Mr
+John+Smith&ADDRSENT=12+Brookwood+Court

Task Type: 'FAXDOC' - FAXDOC

Description: Fax a document

Request Parameters:

Example Request for Task 'FAXDOC':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=FAXDO
C&FAXTO=447785123456&NAME=Mr+Dave+Peters%2C+CEO&PDFDOC=http%3A%2F%2Fwww.myserver
.com%2Ffax.pdf

Example Response Callback for Task 'FAXDOC':

https://your.server.com/human-response.php?taskid=278372819&SENTOK=&SENTTO=01202
237101&NOTES=Sent+on+second+attempt

Task Type: 'HOTEL' - Hotel Reservation

Description: Arrange a hotel reservation

Request Parameters:

Example Request for Task 'HOTEL':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=HOTEL
&BILLING=&BUDGET=GBP+200&HOTEL=Durley+Towers&LOCATION=Bournemouth+UK&ARRIVAL=01%
2F01%2F2008+Early+Evening&NIGHTS=3&ROOMS=2&GUESTS=6&CHILDREN=2&NOTES=Prefer+a+ho
tel+with+a+pool

Example Response Callback for Task 'HOTEL':

https://your.server.com/human-response.php?taskid=278372819&HOTELFOUND=1&CARDACC
EPTED=1&COMPLETE=1&HOTELBOOKED=%22Durley+Towers%2C+1+Short+Pier%2C+Bournemouth+B
H1+1AA%22&DATES=01%2F01%2F2008+-+03%2F01%2F2008&TOTALCOST=159+GBP&BOOKINGREF=273
1723987&NOTES=Please+check+in+before+11PM

Task Type: 'MEETING' - Meeting/Party

Description: Arrange a meeting or schedule party

Request Parameters:

Example Request for Task 'MEETING':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=MEETI
NG&ATTENDEES=%22John+Smith+(01202+237100)%2C+Mary+Smith+(01202+237101)%2C+Petal+
Flower+(01202+237100)%22&PURPOSE=Meeting+to+discuss+sales+budget&LOCATION=Holida
y+Inn%2C+Bournemouth&RESERVEVENUE=1&CALLATTENDEES=1&DATETIME=01%2F01%2F2008+10%3
A30&NOTES=Please+bring+recent+sales+reports&FALLBACKDATETIME=01%2F01%2F2008+16%3
A00

Example Response Callback for Task 'MEETING':

https://your.server.com/human-response.php?taskid=278372819&RESERVED=1&EVENTLOCA
TION=%22Mc+Haggis+Suite%2C+01202+237100%22&EVENTDATETIME=01%2F01%2F2008+10%3A30&
NOTES=Please+check+in+at+front+desk

Task Type: 'QUESTION' - Question

Description: Answer a question

Request Parameters:

Example Request for Task 'QUESTION':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=QUEST
ION&QUESTION=How+many+legs+does+a+spider+have%3F

Example Response Callback for Task 'QUESTION':

https://your.server.com/human-response.php?taskid=278372819&RESPONSE=A+spider+ha
s+8+legs+-+unless+it+has+undergone+a+trauma&FOUND=1

Task Type: 'QUESTION45P' - Question - 45p Bonus Question

Description: Answer a question - 45p Bonus Question

Request Parameters:

Example Request for Task 'QUESTION45P':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=QUEST
ION45P&QUESTION=How+many+legs+does+a+spider+have%3F

Example Response Callback for Task 'QUESTION45P':

https://your.server.com/human-response.php?taskid=278372819&RESPONSE=A+spider+ha
s+8+legs+-+unless+it+has+undergone+a+trauma&FOUND=1

Task Type: 'RESERVATION' - Reserve venue/event

Description: Make a reservation at venue/event

Request Parameters:

Example Request for Task 'RESERVATION':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=RESER
VATION&ITEM=%22Harry+Potter+at+Odeon+Cinema%2C+Poole%22&GUESTS=3+-+Smith&BILLING
=&BUDGET=GBP+40&NOTES=%22Seat+near+the+back%2C+centre%22

Example Response Callback for Task 'RESERVATION':

https://your.server.com/human-response.php?taskid=278372819&FOUND=0&RESERVED=1&L
OCATION=%22Odeoen+Poole%2C+01202+237100%22&TIME=01%2F01%2F2008+20%3A35&BOOKINGRE
F=Smith&TOTALCOST=GBP+38&NOTES=Pick+up+tickets+at+machine+using+credit+card

Task Type: 'TRANSCRIBE' - Transcribe a recorded message into text

Description: Transcribe audio to text

Request Parameters:

Example Request for Task 'TRANSCRIBE':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=TRANS
CRIBE&URL=http%3A%2F%2Fwww.myWebSite.com%2Fvoicemail1234.mp3&FIELD1=&FIELD2=&FIE
LD3=&FIELD4=&FIELD5=&FIELD6=

Example Response Callback for Task 'TRANSCRIBE':

https://your.server.com/human-response.php?taskid=278372819&DATA1=&DATA2=&DATA3=
&DATA4=&DATA5=&DATA6=&PLAYEDOK=0&UNDERSTOOD=0&COMPLETEDOK=1

Task Type: 'TRAVEL' - Travel Booking

Description: Arrange a travel reservation

Request Parameters:

Example Request for Task 'TRAVEL':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=TRAVE
L&BILLING=&BUDGET=GBP2000&TRAVEL=Flight&CARRIER=US+AIRWAYS&DEPART=01%2F01%2F2008
&FROM=London+Gatwick&TO=Charlotte+USA&PASSENGERS=2&EMAIL=john%40smith.net&NAMES=
%22MR+John+Smith%2C+MRS+Mary+Smith%22&CHILDREN=0&NOTES=Please+book+window%2Faisl
e+seat

Example Response Callback for Task 'TRAVEL':

https://your.server.com/human-response.php?taskid=278372819&TRAVELFOUND=1&CARDAC
CEPTED=0&COMPLETE=1&TOTALCOST=GBP+1677&TRAVELNO=US+Flight+733&DEPART=01%2F01%2F2
008+10%3A30&DEPARTFROM=London+Gatwick+South+Terminal&BOOKINGREF=FJKFIEJA&NOTES=%
22Seats+11A%2C11B%22

Task Type: 'TRIALQUESTION' - Question

Description: Answer a question

Request Parameters:

Example Request for Task 'TRIALQUESTION':

https://secure.comcetera.com/humanpi?user=xxx&pass=yyy&action=newtask&task=TRIAL
QUESTION&QUESTION=How+many+legs+does+a+spider+have%3F

Example Response Callback for Task 'TRIALQUESTION':

https://your.server.com/human-response.php?taskid=278372819&RESPONSE=A+spider+ha
s+8+legs+-+unless+it+has+undergone+a+trauma&FOUND=1