This document contains instructions on using two of VeriSmarts APIs.
The Coverage API provides information on coverage within a Postcode. It can also provide a quotation if the team in question provide this information upfront.
The Booking API allows a third-party provider to create booking requests within the covering teams Calendar. The covering team will contact the Landlord to confirm details and pricing.
Combining these two APIs will allow a third-party to provide a simple interface to their customers for booking with VeriSmart.
Using Coverage is simple, as there is no authentication required. A URL provides the data as JSON.
A Postcode is required. You can optionally include details of the requested service and property for a quotation.
https://app.verismart.co.uk/dcal/api/coverage/quote/{POSTCODE}/{BEDROOMS}/{FURNISHED}/{SERVICE}/.json
All {FIELDS} need to be URL encoded.
POSTCODE - Full postcode or Outcode. Spaces are ignored. Examples, BH1 1XX, BH11XX, BH1
BEDROOMS - Number of bedrooms, options are 1,2,3,4,5 or 6
FURNISHED - Options are FURNISHED, UNFURNISHED or PART-FURNISHED
SERVICE - Currently, options are INVENTORY, CHECK-OUT, CHECK-IN and INTERIM
A working example
https://app.verismart.co.uk/dcal/api/coverage/quote/BH1%201XX/2%20BEDROOM/UNFURNISHED/INVENTORY/.json
This returns the following JSON, an example of an area which is licensed, but the team does not provide quote prices upfront. A booking request for this team would trigger the team to contact the Landlord and quote manually.
{
"request_element": "BH1 1XX",
"description_en": "Bournemouth BH1 1XX, UK",
"latlng": {
"lat": 50.7208655,
"lng": -1.8778515
},
"licensed_area": {
"is_licensed": 1,
"teamid": "1691",
"team_name": "VeriSmart Winton",
"team_leader_name": "Rebecca Meddings",
"team_leader_email": "winton@verismartinventories.co.uk",
"team_logo_url": "http:\/\/www.inventoryclerk.org\/photographs\/logos\/1691\/thumb.png"
},
"nearest_team": null,
"quoted_price": "Quote Required"
}
This example returns a quoted price
https://app.verismart.co.uk/dcal/api/coverage/quote/NR118HJ/2/UNFURNISHED/INVENTORY/.json
This JSON is Returned
{
"request_element": "NR118HJ",
"description_en": "Gimingham, Norwich NR11 8HJ, UK",
"latlng": {
"lat": 52.8835715,
"lng": 1.4008308
},
"licensed_area": {
"is_licensed": 1,
"teamid": "1630",
"team_name": "Inventoryclerk Norfolk",
"team_leader_name": "Simon Colbourne",
"team_leader_email": "simon.colbourne@verismartinventories.co.uk",
"team_logo_url": "http:\/\/www.inventoryclerk.org\/photographs\/logos\/1630\/thumb.png"
},
"nearest_team": null,
"quoted_price": 90
}
Example of a request where the area does not have coverage within 25 miles
https://app.verismart.co.uk/dcal/api/coverage/nearest/IP1/.json
This JSON is returned
{
"request_element": "IP1",
"description_en": "Ipswich IP1, UK",
"latlng": {
"lat": 52.0744043,
"lng": 1.131861
},
"licensed_area": {
"is_licensed": 0,
"teamid": 0
},
"nearest_team": {
"within_distance": 0,
"teamid": 0
}
}
An example of a request where the area is directly covered, but the distance is within 25 miles
{
"request_element": "CM4",
"description_en": "Ingatestone CM4, UK",
"latlng": {
"lat": 51.6722402,
"lng": 0.390851
},
"licensed_area": {
"is_licensed": 0,
"teamid": 0
},
"nearest_team": {
"within_distance": 1,
"teamid": "1689",
"distance": 13.65
}
}
Apart from displaying the price and optionally the name of the team to your customer, the information you need from this call to create a booking request is "teamid", from either the "licensedarea" section or the "nearestteam" section, depending on whether it it licensed or not.
The next section demonstrates how to create a booking with this information.
All responses include a field of "response_status".
Response of 1 means the query is successful, and 0 means failure. If failed, the only other field will be "error", which contains the reason for failure.
All submitted data should be URL Encoded.
All responses will be JSON encoded.
All endpoints use SSL, and will not work over a normal http:// transport.
https://app.verismart.co.uk/dcal/api/v1/booking/
The booking API uses signed query strings to authenticate the request. The querystring will be signed using the secret, which is then appended to the URL before the GET request is made.
We will be signing just the query string, which contains the apikey and our requests and/or data.
An simple example query string, showing all bookings for today:
apikey=D15AD8F8015989F637EF53E8A1458YHR4C444B58&mode=show
Now we take that string, and and hash it with sha512 to produce our signature string.
In PHP:
$signature = hash_hmac("sha512", $query_string, $secret);
This signature can now be appended as "signature" to the url
In PHP:
$query_string = $query_string . '&signature=' . $signature;
And this URL can be used to query the API. The signature tells VeriSmart that this request is correctly authorised, and SSL ensures the request data remains private.
To start with, here are all the fields.
apikey
mode
landlord_name
landlord_email
landlord_phone
landlord_address1
landlord_address2
landlord_town
landlord_county
landlord_postcode
flat_no
house_no
address1
address2
town
postcode
bedrooms
furnishings
day
month
year
comments
tenant_name
tenant_mobile
tenant_email
assignment
quoted_price
quoted_team
service_time
This is the key apikey provided by VeriSmart, along with the secret.
The mode for landlords should always be the string "create_landlord".
All strings, to supply VeriSmart with the invoicing and delivery information needed for this landlord.If any field is unknown, can be left blank except for landlord_email and landlord_name.
The flat number of the rental property.
The house number of the rental property.
The first line of the address of the rental property.
The second line of the address of the rental property.
The town of the rental property
The postcode of the rental property. It is essential this is correct. Spaces are optional.
Numeric, eg "2", "6".
String, one of the following values "UNFURNISHED", "FURNISHED", "PART-FURNISHED"
The day to create the booking, numeric eg "1", "24"
The month to create the booking for, numeric eg 4, 12
The year to create the booking for, numeric eg 2017
Any comments you wish to add relevant to the booking, such as access requirements or meter locations.
For VeriSmart Tenant Delivery of the report, tenantname, tenantmobile and tenant_email are all required.
The type of visit being booked. Available types are INVENTORY, CHECK-OUT, INTERIM.
This is the price provided by the Coverage API. Can be 0 to prompt a quotation from the team.
This is the teamid provided by the Coverage API. Please note that bookings cannot be successfully create without a valid teamid.
We recommend that this is always set to "TBA" to allow the team to arrange the times with the landlord directly. Other options are "ANYTIME", "MORNING", "AFTERNOON" or an actual time in format HH:MM, eg "13:30".
The following is returned
{
"request_status": "1",
"taskid": 79172
}
"request_status" is 1 for success, 0 for failure. On success, "taskid" is the unique VeriSmart reference for that booking request.
$apiurl = 'https://app.verismart.co.uk/dcal/api/v1/booking/';
$apikey = 'MYAPIKEY';
$apisecret = 'MYAPISECRET';
$request_data =
array(
'apikey' => $apikey,
'mode' => 'create_landlord',
'landlord_name' => "Bobby Tables",
'landlord_email' => "landlord@verismart.co.uk",
'landlord_phone' => "07700 900000",
'landlord_address1' => "56 Landlord Lane",
'landlord_address2' => "Landlordstone Valley",
'landlord_town' => "Poole",
'landlord_county' => "Dorset",
'landlord_postcode' => "BH14 0XX",
'flat_no' => "43",
'house_no' => "",
'address1' => "Burgess House",
'address2' => "Boscombe",
'town' => "Bournemouth",
'postcode' => "BH1 1XX",
'bedrooms' => "3",
'furnishings' => "UNFURNISHED",
'day' => "1",
'month' => "4",
'year' => "2018",
'comments' => 'Access requires a key, landlord to provide.',
'tenant_name' => "John Smith",
'tenant_mobile' => "07700 900000",
'tenant_email' => "tenant@verismart.co.uk",
'assignment' => "INVENTORY",
'quoted_price' => "100",
'quoted_team' => "1506",
'service_time' => 'TBA'
);
// Now lets call it
$query_string = http_build_query($request_data);
$signature = hash_hmac("sha512", $query_string, $apisecret);
$qstring = $query_string . '&signature=' . $signature;
$result = file_get_contents($apiurl . '?' . $qstring);
$result_data = json_decode($result, TRUE);
if ($result_data['request_status'] == 1) {
echo "All worked";
} else {
echo "Not worked";
}