How to use the API

Before you begin

Register your application

For security purposes, our API uses a "consumer key" and "consumer secret", a bit like Oauth. To get a key and secret for your application, you need to register your application.

Once you've done that, you are ready to start integrating your application with our API.

Request and response

Our API uses a RESTful architecture. You make http requests, and the responses are in the JSON format. Our request examples below are in the Ruby language, but you won't find it hard to translate them to another web language.

Some supporting functions

For the examples below, it's helpful if you have the following already in place:

require 'net/http'

def get_consumer_key
  return "YOUR_CONSUMER_KEY"
end

def get_consumer_secret
  return "YOUR_CONSUMER_SECRET"
end

def http_get(domain,path,params)
  return Net::HTTP.get(domain, "#{path}?".concat(params.collect { |k,v| "#{k}=#{CGI::escape(v.to_s)}" }.join('&'))) if not params.nil?
  return Net::HTTP.get(domain, path)
end

We've broken this documentation into the two most likely processes that you will be doing: finding suppliers for your buyers, and finding buyers for your suppliers.

Finding suppliers for your buyers

The scenario: a buyer in your application has inidcated that they want something, and you want to reach suppliers beyond those registered in your application in order to fulfil it.

Jump to: create request | get request | message off-system supplier | message on-system supplier | update request | set request status | delete request

Register your buyer's need with us (create request - POST request)

To register a buyer's need, you need to create a request:

Request:

url = URI.parse("http://www.intently.co/requests")
req = Net::HTTP::Post.new(url.path)

req.set_form_data({"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret(), "what" => "Honda Car Service", "_when" => "This weekend", "_where" => "Perth Australia", "other" => "Hi there,\n\nMy 2004 Honda Civic needs a service this weekend. Can you help?\n\nThanks,\n\nGreg."}, ";")

res = Net::HTTP.new(url.host).start {|http| http.request(req) })
return res.body

About the attributes:

  • what: What or who you are looking for. For best results, keep this short and sweet, e.g. "hire marquee".
  • _where: This is the text of a location. For best results, ensure that the location is as unambiguous as possible, e.g. Birmingham, United States. When specifying a country, it's best to use its full name as opposed to an abbreviation and to precede it with a comma and a space (e.g. "Kidderminster, United Kingdom"). Finally, it's best to avoid using UK post codes as these don't tend to produce optimal results.
  • _when: This is just free text and is presented to on-system suppliers for information only.
  • other: This is the fuller description of what you want. Ideally, it should read like a friendly message, including a greeting (e.g. "Hi there!"), a body (e.g. "I am seeking a ..."), and a signature (e.g. "Many thanks, Steve."). You can use \n for carriage returns.

Response:

{
    "request": {
        "request_id": "550",
        "created_at": "2012-09-28 18:52:23 UTC",
        "status": "open",
        "broadcast_status": "getting off-system suppliers",
        "auto broadcast": "",
        "what": "Honda Car Service",
        "when": "This weekend",
        "where": "Perth Australia",
        "other": "Hi there,

My 2004 Honda Civic needs a service this weekend. Can you help?

Thanks,

Greg.",
        "on-system suppliers": {
        }
        "off-system suppliers": {
        }
    }
}

Note the request_id in the response. This is your request's unique identifier and you will need it for subsequent API calls.

On creating a request, any on-system suppliers will automatically be notified if they offer a service which matches the text of the request. We will also automatically seek off-system suppliers who can help. In addition, your request may be syndicated to a number of online services (e.g. Twitter) in order to ensure that it is proactively broadcasted to interested parties.

Note the "status" field in the response. This tells you if we have finished finding off-system suppliers. "getting off-system suppliers" means we're still finding them; "got off-system suppliers" means the list is complete; "message sent to all off-system suppliers" means that we have broadcast the request to all off-system suppliers; "sending to all off-system suppliers" means that we are currently finding off-system suppliers and contacting them automatically ("fire and forget" mode).

Wait 60 seconds for us to find relevant off-system suppliers, and then get your request (get request - GET request)

It takes us around 60 seconds for us to find relevant off-system suppliers for a request. You will need to wait for this process to complete before you can see the full list of everyone we have found. After 60 seconds, get your request so you can see who the off-system suppliers are:

Request:

return http_get("www.intently.co", "/requests/550", {"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret()}

Note that 550 is the request_id returned in the previous "create request" request.

Response:

{
    "request": {
        "request_id": "550",
        "created_at": "2012-09-28 18:52:23 UTC",
        "status": "open",
        "broadcast_status": "got off-system suppliers",
        "auto broadcast": "",
        "what": "Honda Car Service",
        "when": "This weekend",
        "where": "Perth Australia",
        "other": "Hi there,

My 2004 Honda Civic needs a service this weekend. Can you help?

Thanks,

Greg.",
        "on-system suppliers": {
            "on-system supplier": {
                "watchresult_id": "999",
                "visible name": "Dean Motors",
                "website": "www.deanmotorsservices.com.au",
                "email": "dean.blendley@deanms.com",
                "phone": "0123456 837546 328",
                "company": "Dean Motors Servicing",
                "about": "We have been established for 56 years, and can service all types of car, including Opel, Hyundai and Honda.",
                "messages": {
                    "message": {
                        "message type": "incoming",
                        "created_at": "2012-05-17 11:55:34 UTC",
                        "message text": "Hi Greg,

We can provide a car service, but we're fully booked until February. Let me know if that's ok.

Regards

Dean",
                    }
                    "message": {
                        "message type": "outgoing",
                        "created_at": "2012-05-17 12:35:23 UTC",
                        "message text": "Hi Dean,

Thanks for the reply. I'm going to give this a miss as it's really quite urgent.

Thanks again,

Greg.",
                    }
                }
            }
        }
        "off-system suppliers": {
            "off-system supplier": {
                "website": "www.carservice.com.au",
                "email addresses": {
                    "email address": {
                    "email address": "servicecentres@carservice.com.au",
                        "email_id": "9765",
                        "messages": {
                            "message:" {
                                "message type": "outgoing",
                                "created_at": "2012-05-17 09:52:51 UTC",
                                "message text": "Hi there,

My 2004 Honda Civic needs a service this weekend. Can you help?

Thanks,

Greg."
                            }
                            "message:" {
                                "message type": "incoming",
                                "created_at": "2012-05-17 11:50:57 UTC",
                                "message text": "Hi Greg! We'd be happy to assist. We have slots at 9am and 11am on Sat. Just drop me a line if you want to take one of these. Cheers, Gavin"
                            }
                        }
                    }
                }
            }
            "off-system supplier": {
                "website": "www.perthnow.com.au",
                "email addresses": {
                    "email address": {
                        "email address": "news@perthnow.com.au",
                        "email_id": "9759",
                        "messages": {
                        }
                    }
                    "email address": {
                        "email address": "news@perthnow.newsltd.com.au",
                        "email_id": "9760",
                        "messages": {
                        }
                    }
                }
            }
            "off-system supplier": {
                "website": "www.peelhonda.com.au",
                "email addresses": {
                    "email address": {
                        "email address": "sales@peelhonda.com.au",
                        "email_id": "9766",
                        "messages": {
                        }
                    }
                }
            }
        }
    }
}

Tell our off-system suppliers about your request (message off-system supplier - POST request)

We do not tell our off-system suppliers about a request automatically - you need to send them a message to alert them. To send a message to an individual off-system supplier, do this:

Request:

url = URI.parse("http://www.intently.co/replies")
req = Net::HTTP::Post.new(url.path)

req.set_form_data({"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret(), "email_id" => "9669", "subject" => "Honda service", "text" => "Hi there,\n\nMy 2004 Honda Civic needs a service this weekend. Can you help?\n\nThanks,\n\nGreg."}, ";")

res = Net::HTTP.new(url.host).start {|http| http.request(req)}
return res.body

You can use \n for carriage returns in the message text.

You are advised to make your message friendly and personal, as tests have shown that this has a very positive impact on response rates. Greet the supplier ("Hi there!"), include a body ("I want to rent a ..."), and sign off with the buyer's name ("Best regards, Dave").

Response:

message sent

Alternatively, you can send a message to all off-system suppliers in one go using:

Request:

url = URI.parse("http://www.intently.co/messages")
req = Net::HTTP::Post.new(url.path)

req.set_form_data({"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret(), "request_id" => "546", "subject" => "Honda service", "text" => "Hi there,\n\nMy 2004 Honda Civic needs a service this weekend. Can you help?\n\nThanks,\n\nGreg."}, ";")

res = Net::HTTP.new(url.host).start {|http| http.request(req) }
return res.body

Response:

messages sent

Each off-system supplier is sent a separate message so they do not have sight of who else was contacted.

And last but not least, you can create a request and have it broadcast automatically to all off-system suppliers if you wish. This is "fire and forget" if you like (the message text will be taken from the request's "other" field). All you need to do after this, is check for replies occasionally using the get request. To create a request and broadcast it to all suppliers automatically, do this:

Request:

url = URI.parse("http://www.intently.co/requests")
req = Net::HTTP::Post.new(url.path)

req.set_form_data({"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret(), "what" => "Family Photographer", "_when" => "April", "_where" => "Dublin Ireland", "other" => "Hi there,\n\nWe're looking for a family photographer for a session some time in April. It will be myself, my wife Angela and my two kids (both boys, 4 and 7). Can you help? If so, please let me know your prices!\n\nThanks,\n\nNathan.", "auto_broadcast" => "yes"}, ";")

res = Net::HTTP.new(url.host).start {|http| http.request(req) }
return res.body

Response:

{
    "request": {
        "request_id": "550",
        "created_at": "2012-09-28 18:52:23 UTC",
        "status": "open",
        "broadcast_status": "sending to all off-system suppliers",
        "auto broadcast": "yes",
        "what": "Honda Car Service",
        "when": "This weekend",
        "where": "Perth Australia",
        "other": "Hi there,

My 2004 Honda Civic needs a service this weekend. Can you help?

Thanks,

Greg.",
        "on-system suppliers": {
        }
        "off-system suppliers": {
        }
    }
}

Once again, each off-system supplier is sent a separate message so they do not have sight of who else was contacted.

Poll us regularly to check for responses from on-system and off-system suppliers

Your application needs to check back regularly (e.g. every 10 minutes) to see if you have new responses from any of our suppliers. To do this, simply get your request and check the "messages" sections for replies from on-system and off-system suppliers. We may enhance the API later on to notify your application when responses arrive.

Send message to on-system supplier (POST request)

When you create a request, relevant on-system suppliers will be automatically notified. If an on-system supplier sends a message to your buyer, then you will probably want to end a message back to them from your buyer. You can do that like this:

Request:

url = URI.parse("http://www.intently.co/replies")
req = Net::HTTP::Post.new(url.path)

req.set_form_data({:consumer_key => get_consumer_key(), :consumer_secret => get_consumer_secret(), "watchresult_id" => "1028", "text" => "Hi Anthony,\n\nThanks for your reply. How much do you charge for kitchen design?\n\nBest regards,\n\nHelen."}, ";")

res = Net::HTTP.new(url.host).start {|http| http.request(req) }
return res.body

Response:

message sent

Continue the conversation with our suppliers

To continue the conversation, it's more of the same. Just use the above get and send requests.

Update request - PUT request

You may want to update the attributes of a request. Do this using the following:

Request:

url = URI.parse("http://www.intently.co/requests/510")
req = Net::HTTP::Put.new(url.path)

req.set_form_data({"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret(), "what" => "Honda Car Service and Valet", "_when" => "This weekend", "_where" => "Perth Australia", "other" => "Hi there,\n\nMy 2004 Honda Civic needs a service and valet this weekend. Can you help?\n\nThanks,\n\nGreg."}, ";")

res = Net::HTTP.new(url.host).start {|http| http.request(req) }
return res.body

Response:

request updated

When you update a request, we will automatically notify any new on-system suppliers whose services match the contents of the request. We will not run a new search for off-system suppliers, so if you want that to happen then you need to create a new request.

Set request status - GET request

A request can have one of the following statuses: open, closed, and supplier found. To update the status, you can make one of these requests:

Requests:

return http_get("www.intently.co", "/requests/516/reopen", {"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret()})

return http_get("www.intently.co", "/requests/516/supplierfound", {"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret()})

return http_get("www.intently.co", "/requests/516/close", {"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret()})

Responses:

request (re)opened
request set to "supplier found"
request closed

About the statuses:

  • Open: The request is open, meaning that the buyer is still inviting responses from suppliers.
  • Supplier found: The buyer can use this status to indicate that they have already found a supplier, but effectively the request is still open so that alternative suppliers can still contact the buyer and offer their services.
  • Closed: The request is closed, meaning that its lifecycle is complete (most likely the buyer has completed a transaction with a supplier, but it may also be the case that the buyer has closed the request because they don't want to continue with it for some other reason).

Delete request - DELETE request

To delete a request, do this:

Request:

http = Net::HTTP.new("www.intently.co")

request = Net::HTTP::Delete.new("/requests/512?consumer_key=" + get_consumer_key() + "&consumer_secret=" + get_consumer_secret())

res = http.request(request)
return res.body

Response:

request deleted

A deleted request will no longer be shown on intently.co. However, if the content has been syndicated to other services (e.g. Twitter) or messages have been sent to suppliers, then such information obviously cannot be withdrawn.

Finding buyers for your suppliers

The scenario: you want to find buyers for your suppliers' services.

Jump to: create service | get service | message buyer | update service | delete service

Set up a service to enable your profile to be matched with relevant buyers (create service - POST request)

You can set up mandatory and optional keywords to search on, and also set geographical locations to search in:

Request:

url = URI.parse("http://www.intently.co/services")
req = Net::HTTP::Post.new(url.path)

req.set_form_data({"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret(), "optional_keywords" => "Car Service Tyre", "mandatory_keywords" => "Honda", "locations" => "Australia"}, ";")

res = Net::HTTP.new(url.host).start {|http| http.request(req) } return res.body

Response:

{
    "watch": {
        "watch_id": "427",
        "created_at": "2012-09-28 21:20:07 UTC",
        "optional_keywords": "Car Service Tyre",
        "mandatory_keywords": "Honda",
        "locations": "Australia",
        "watchresults": {
            "watchresult": {
                "watchresult_id": "1074",
                "visible name": "Greg",
                "what": "Honda service",
                "when": "This weekend",
                "where": "Perth Australia",
                "other": "Hi there,

My 2004 Honda Civic needs a service this weekend. Can you help?

Thanks,

Greg.",
                "messages": {
                }
            }
            "watchresult": {
                "watchresult_id": "1077",
                "username": "Arun",
                "what": "Honda tyre replacement",
                "when": "ASAP",
                "where": "Rockingham Australia",
                "other": "Hi there,

I need four tyres for a Saab Vector 95 (made in 2004). Can you help?

Many thanks,

Arun.",
                "messages": {
                }
            }
        }
    }
}

In the response above, two people were found who need something related to the service created (see watchresults 1074 and 1077). Note the watch_id (427) - you will need this for subsequent API calls relating to this service.

Poll us regularly for a list of live buyer requests (get service - GET request)

Once you have set up a service, you can get it at regular intervals to see a list of buyer requests for it:

Request:

return http_get("www.intently.co", "/myservices/427", {"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret()})

Note that this request is asking for information about service 427.

Response:

{
    "watch": {
        "watch_id": "427",
        "created_at": "2012-09-28 21:20:07 UTC",
        "optional_keywords": "Car Service Tyre",
        "mandatory_keywords": "Honda",
        "locations": "Australia",
        "watchresults": {
            "watchresult": {
                "watchresult_id": "1074",
                "visible name": "Greg",
                "what": "Honda service",
                "when": "This weekend",
                "where": "Perth Australia",
                "other": "Hi there,

My 2004 Honda Civic needs a service this weekend. Can you help?

Thanks,

Greg.",
                "messages": {
                    "message": {
                        "message type": "outgoing",
                        "created_at": "2012-09-28 21:26:46 UTC",
                        "message text": "Dear Greg,

We can help you with this any time on Saturday. Please call me on 23334 3434344 to arrange a booking.

Thanks,

Lorraine",
                    }
                }
            }
            "watchresult": {
                "watchresult_id": "1077",
                "username": "Arun",
                "what": "Honda tyre replacement",
                "when": "ASAP",
                "where": "Rockingham Australia",
                "other": "Hi there,

I need four tyres for a Saab Vector 95 (made in 2004). Can you help?

Many thanks,

Arun.",
                "messages": {
                    "message": {
                        "message type": "outgoing",
                        "created_at": "2012-09-28 21:30:48 UTC",
                        "message text": "Dear Arun,

We'd be happy to help. Please can you confirm it's a standard wheel size on your Saab? We are open 7am-10pm 7 days a week.

Thanks,

Lorraine.",
                    }
                    "message": {
                        "message type": "incoming",
                        "created_at": "2012-09-28 21:31:43 UTC",
                        "message text": "Hi Lorraine. Fantastic! I'll be over this evening after work. And yes, it's standard size.",
                    }
                }
            }
        }
    }
}

Note the service returned above must have led to conversations with buyers because it has outgoing and incoming messages.

Tell your suppliers about our buyers' requests

This is something we expect you to do in your application, namely display the buyers' requests you found from us.

Send your suppliers' messages to our buyers (message buyer - POST request)

If one of your suppliers wants to send a message to one of our buyers, you can just forward the message like this:

Request:

url = URI.parse("http://www.intently.co/replies")
req = Net::HTTP::Post.new(url.path)

req.set_form_data({"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret(), "watchresult_id" => "1030", "text" => "Hi Greg!\n\nWe can certainly help with this and we have availability on Saturday morning. What model of Civic is it?\n\nBest regards,\n\nSue\nPerth Mega Motors"}, ";")

res = Net::HTTP.new(url.host).start {|http| http.request(req) }
return res.body

You can use \n for a carriage return in the message text.

Response:

message sent

Continue the conversation with our buyers

To continue the conversation, just keep sending messages as above and getting your service to check for responses.

Update service - PUT request

If you want to update the attributes of a service, do this:

Request:

url = URI.parse("http://www.intently.co/myservices/423")
req = Net::HTTP::Put.new(url.path)

req.set_form_data({"consumer_key" => get_consumer_key(), "consumer_secret" => get_consumer_secret(), "optional_keywords" => "Car Service Tyre Servicing", "mandatory_keywords" => "", "locations" => "Perth"}, ";")

res = Net::HTTP.new(url.host).start {|http| http.request(req) }
return res.body

Response:

service updated

On updating a service, we will check all open requests to see if they are a match and any new matches will be listed against the service.

Delete service - DELETE request

You can delete a service by doing this:

Request:

http = Net::HTTP.new("www.intently.co")

request = Net::HTTP::Delete.new("/myservices/423?consumer_key=" + get_consumer_key() + "&consumer_secret=" + get_consumer_secret())

res = http.request(request)
return res.body

Response:

service deleted

When a service is deleted, all pre-exisiting conversations with buyers against this service are effectively stopped (buyers will still be able to see the conversations that were held but they will not be able to send any new messages; you will have no access to the pre-existing conversations unless you have stored them somewhere in your application).

Questions and feedback

If you have any questions or feedback, please contact us using one of the methods on our Contact page.