allAgents icon allAgents API

allAgents has introduced a RESTful API for its Premium Support Plus agents, so that they are better able to utilise the wealth of data allAgents has collected over the years.

Please find simple examples of the possible uses for the API in this section. Examples are provided in PHP using cURL, but the core concepts are the same and applicable regardless of client-side implementation. At the moment, the API outputs JSON responses only.


Where can I find my API key?

API Keys are only available to Premium Support Plus members, and can be retrieved from the firm or branch's logged-in area on allAgents. You can sign in here.

How do I use my API Key?

The API Key must be sent as an HTTP header, 'APIKEY: ...', and not as a POST variable or in the the request URL.


Important Usage Notes


  • The allAgents API will only work over the HTTPS protocol.
    Your website does not need to be using HTTPS, but calls to the API must go to https://www.allagents.co.uk/api/.... and not http://www.allagents.co.uk/api/....

  • All URLs must end with a trailing slash to receive a response.

  • allAgents enacts a rate limit in regard to requests. We will honour 200 requests per resource, per hour. There are also limits on smaller scales such that 200 requests can't be made in one minute, for example. If too many requests are made, you may receive temporary blocks to resources (after you have been notified). The reason for this is to keep the API healthy and responsive for all members.

  • It is strongly suggested that you cache our responses to avoid making unnecessary duplicate requests


  • You must link back to the original content when feeding reviews to you site, i.e. the branch or agent page from which the reviews originated. If you are allowing users to post a review from your site, it must be clear that the review is going to be submitted to allAgents, which must be linked to.

Resources


URL Description & Responses
GET
https://www.allagents.co.uk/api/v1/firms/[your-firm-link]/
Retrieve details of your firm. A 'firm' refers to an estate or letting agency 'group' as a whole, and to no particular branch.

Response Field Description
name The name of the firm.
active_branches Number of branches belonging to the firm
onlineagent This is regarded as an online agent. Returns a 1 or 0 for true or false.
fee_satisfaction Customer satisfaction with fees, expressed as a percentage.
price_satisfaction Customer satisfaction with price sold, expressed as a percentage.
rank_uk Firm's rank in the UK.
rank_sales Firm's rank in regard to sales in the UK.
rank_let Firm's rank in regard to lettings in the UK.
rating Firm's overall average rating based on all customer reviews.
rating_sales Firm's average rating based on all customer reviews pertaining to sales transactions.
rating_let Firm's average rating based on all customer reviews pertaining to lettings transactions.
votes Number of reviews received, in any capacity.
votes_sales Number of reviews received pertaining to sales transactions
votes_let Number of reviews received pertaining to lettings transactions
GET
https://www.allagents.co.uk/api/v1/firms/your-firm-link/branches/your-branch-link/
Retrieve details of your branch. A branch refers to an estate or letting agency office with a particular address. All firms have at least one branch.

Response Field Description
address Street address of the branch.
district District/Locality of the branch within its town.
town Town in which the branch is located.
county County in which the branch is located.
postcode Full postcode of the branch
tel Telephone number of the branch
faxFax number of the branch
rating The branch's overall average rating based on all customer reviews.
rating_sales Branch's average rating based on all customer reviews pertaining to sales transactions.
rating_let Branch's average rating based on all customer reviews pertaining to lettings transactions.
rank_sales Branch's rank in regard to sales in the UK.
rank_let Branch's rank in regard to lettings in the UK.
votes Number of reviews received for branch, in any capacity.
votes_sales Number of reviews for branch received pertaining to sales transactions
votes_let Number of reviews received for branch pertaining to lettings transactions
GET
https://www.allagents.co.uk/api/v1/firms/[your-firm-link]/reviews/
Retrieve the latest 20 customer reviews left for your firm, regardless of which branch was reviewed. An array of up to 20 reviews is returned, with each item containing the following.

Response Field Description
name The display name of the reviewer.
date_added The date the review was published on allAgents.
review The review content.
capacity In what capacity the reviewer used the firm's services.
rating The reviewer's rating of the firm, from 1 star to 5.
willreturn Whether the reviewer would voluntarily return to use the firm's services again.
GET
https://www.allagents.co.uk/api/v1/firms/[your-firm-link]/branches/[your-branch-link]/reviews/
Retrieve the latest 20 customer reviews left for your branch. An array of up to 20 reviews is returned, with each item containing the following.

Response Field Description
name The display name of the reviewer.
date_added The date the review was published on allAgents.
review The review content.
capacity In what capacity the reviewer used the branch's services.
rating The reviewer's rating of the branch, from 1 star to 5.
willreturn Whether the reviewer would voluntarily return to use the branch's services again.
GET
https://www.allagents.co.uk/api/v1/firms/[your-firm-link]/branches/[your-branch-link]/markup/
Retrieve schema markup, which when added to your page, can improve its appearance in Google. Add this to branch-specific pages on your website, e.g. 'Croydon Branch'. Google can use the information to provide star ratings (based on your allAgents ratings and review count) for a page in its search results and information such as address and logo for the knowledge panel. Effects are not instant, and depend on Google. Check it has been applied correctly by using the Structured Data Tester Tool

Response Field Description
Not Applicable Print the result directly to the page. The result is in JSON-LD format. It is not visible to users, it is only visible in the source, which search engines can pick up.
POST
https://www.allagents.co.uk/api/v1/firms/[your-firm-link]/branches/[your-branch-link]/reviews/
Submit a review for a branch through the API. The most pertinent use of this is to allow reviews written from your own website to go to allAgents. The following fields, most of which are required, should be addressed to successfully submit a review through the API. It is not possible to submit a review for a firm without specifying a branch.

POST Variable & Data Type Description
name
String
The display name of the reviewer. Required
firstname
String
The first name of the reviewer. This is not published. Required
lastname
String
The surname of the reviewer. This is not published. Required
email
string
The reviewer's e-mail address. This must be valid so the reviewer can activate the review. Required.
review_content
String
The actual review content. Minimum 20 words. Required
rating
int
The reviewer's rating of the firm. Minimum 1 and maximum 5. Required.
willreturn*
int
Whether the reviewer would voluntarily return to use the branch. Submit 1 to the API indicate yes, 0 to indicate no. Required.
Capacity*
int
In which capacity the reviewer used the branch. Please use the table below to submit the appropriate value to allAgents. Required.
Capacity Code Capacity Description
1 Lettings (as a Landlord)
2 Lettings (as a Tenant)
3 Sales (as a Vendor)
4 Sales (as a Buyer)
5 Surveys
6 Conveyancing
7 Lettings (Prospective customer)
8 Sales (Prospective customer)
9 They manage our building
10 They are our factor
11 They manage our estate
12 They arranged our mortgage
15 Repair/Property Management
16 Repair (tradesman)
17 Property Management
18 Admin
19 Accounts
20 Buying agent
21 Relocation agent
22 Holiday Rental
terms
int
Notifying that allAgents' terms and conditions of writing a review have been accepted. Submit 1 to the API indicate yes, 0 to indicate no. The review cannot be posted if the terms aren't accepted. Required.
newsletter
int
Whether the reviewer wishes to subscribe to allAgents' newsletter e-mails.
propname
String
The identifying address of the property on which the review is based, e.g. 34 Miller Street. This is not published.
prop_postcode
String
The postcode area of the property on which the review is based, e.g. N4. This information is published. Required.
agentfeedback
String
Feed back on how an agent can improve their service. On allAgents, this is an optional field and is only used when a review is negative and it is suggested this is the usage is maintained.
telephone
String
The reviewer's contact telephone number. This is often used for validity checks.
sold_price
int
The cost at which a property was bought or sold. Please submit without any currency symbols.
rent_pcm
int
The cost at which a property was let. Please submit without any currency symbols.
fee_satisfaction
int
Indicates whether a review was satisfied with the agent's fees. Submit 1 to the API indicate yes, 0 to indicate no.
fee_feedback
String
Positive or negative feedback on fees from reviewer.
best_price
int
The reviewer's opinion on whether the agent was accurate with their valuation. Submit 1 to the API indicate yes, 0 to indicate no.

Error Codes


Status / Error Explanation
100: An error has occurred This is the default catch-all error. If you encounter this error and are sure the request's URL is well-formed, please use your support package to submit details of your request.
101: API Key not received This error occurs when an API Key was not sent or received along with the request. The API Key must be sent as an HTTP header, in the form 'APIKEY: ####'.
102: Unable to validate API Key This error occurs when an API Key is not provided, the wrong or old key is used, or the API key is not enabled, e.g. not a premium support member. Also not that a firm's API Key is only valid for retrieving information regarding themselves.
103: Requested resource of type Firm not found The firm requested has not been found. Please check that the uRL path, in particular the reference following 'firms' corresponds to path of the firm's allAgents profile.
104: Requested resource of type Branch not found The branch requested has not been found for the firm requested. Please check that the uRL path, in particular the reference following 'branches' corresponds to path of the branch's allAgents profile.

Usage Examples


• Retrieving the average rating and number of reviews of a firm

<?php

$headers = array('APIKEY: 12c4f1b01949'); //Example API Key which must be changed.

$url = "https://www.allagents.co.uk/api/v1/firms/example-agent/"; //example-agent must be changed

$curl = curl_init(); // Initialize cURL

// Set the options for cURL
curl_setopt($curl,CURLOPT_URL, $url); //Use the request url defined
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); //We want the result variable to contain the output
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); //send custom header that has the API Key

$result = curl_exec($curl); //Make request via curl and store in $result
curl_close($curl);//close the connection

$decodedResult = (json_decode($result, true)); //Transform JSON output into associative array.
$rating = $decodedResult['rating']; //Store Rating in its own variable
$reviewCount = $decodedResult['votes']; //Store Review Count in its own variable

?>

<!-- Normal HTML content begins -->

<p> We are rated <?= $rating ?> based on <?= $reviewCount ?></p>
                    
• Retrieving a branch's average rating and rank in postcode district

<?php

$headers = array('APIKEY: 12c4f1b01949'); //Example API Key which must be changed.

$url = "https://www.allagents.co.uk/api/v1/firms/example-firm/branches/example-branch/";

$curl = curl_init(); // Initialize cURL

// Set the options
curl_setopt($curl,CURLOPT_URL, $url); //Use request url defined
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); //We want the result variable to contain the output
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); //send custom header with the API Key
$result = curl_exec($curl); //Make request via curl, keep output in result variable

curl_close($curl);//close the connection

$decodedResult = (json_decode($result, true)); //Transform JSON output into associative array.
$rating = $decodedResult['rating']; //Store rating in its own variable
$rank_postcode = $decodedResult['rank_postcode']; //Store postcode ranking in its own variable
$postcodearea = $decodedResult['postcode_area']; //Store postcode area in its own variable
?>
<!-- Normal HTML content --> <p>We are rated <?= $rating ?> and are ranked #<?= $rank_postcode ?> in <?= $postcodearea ?></p>
• Retrieving your firm's reviews

<?php

$headers = array('APIKEY: 12c4f1b01949'); //Example API Key which must be changed.

$url = "https://www.allagents.co.uk/api/v1/firms/example-firm/reviews/";

$curl = curl_init(); // Initialize cURL

// Set the options
curl_setopt($curl,CURLOPT_URL, $url); //Use request url defined
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); //We want the result variable to contain the output
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); //send custom headers, one of which is the API Key
$result = curl_exec($curl); //Make request via curl, keep output in $result variable

curl_close($curl);//close the connection

$decodedResult = (json_decode($result, true)); //Transform JSON output into associative array.
?>
                        <!-- Normal HTML content -->

<h1>Here are our latest reviews from <a href="https://www.allagents.co.uk">allAgents</a></h1>
<?php foreach ($decodedResult as $review){ $date = date_create($review['date_added']); ?> Name: <?= $review['name']; ?> <br /> Rated: <?= $review['rating']; ?> Stars<br /> Date: <?= date_format($date, "j F, Y"); ?><br /> Review: <?= $review['review']; ?> <br /><br/> <? } ?>
• Retrieving your branch's reviews

<?php

$headers = array('APIKEY: 12c4f1b01949'); //Example API Key which must be changed.

$url = "https://www.allagents.co.uk/api/v1/firms/example-firm/branches/example-branch/reviews/";

$curl = curl_init(); // Initialize cURL

// Set the options
curl_setopt($curl,CURLOPT_URL, $url); //Use request url defined
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); //We want the result variable to contain the output
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); //send custom headers, one of which is the API Key
$result = curl_exec($curl); //Make request via curl, keep output in $result variable

curl_close($curl);//close the connection

$decodedResult = (json_decode($result, true)); //Transform JSON output into associative array.
?>
                        <!-- Normal HTML content -->

<h1>Here are our latest reviews from <a href="https://www.allagents.co.uk">allAgents</a></h1>
<?php foreach ($decodedResult as $review){ $date = date_create($review['date_added']); ?> Name: <?= $review['name']; ?> <br /> Rated: <?= $review['rating']; ?> Stars<br /> Date: <?= date_format($date, "j F, Y"); ?><br /> Review: <?= $review['review']; ?> <br /><br/> <? } ?>
• Posting a review to allAgents (e.g. from an agent's website).

if (empty($_POST['action']))    /* display a very simple contact form */
{
    ?>
    <form  action="" method="POST" enctype="multipart/form-data">
        <input type="hidden" name="action" value="submit">
        Your name:<br>
        <input name="name" type="text" value="" size="30"/><br>
        Your First Name (Not published):<br>
        <input name="firstname" type="text" value="" size="30"/><br>
        Your Last  Name (Not published):<br>
        <input name="lastname" type="text" value="" size="30"/><br>
        Your email:<br>
        <input name="email" type="text" value="" size="30"/><br>
        Your telephone:<br>
        <input name="telephone" type="text" value="" size="30"/><br>
        Your review:<br>
        <textarea name="review_content" cols="25" rows="4"/></textarea><br>
        Rating: <br/>
        <select name = "rating">
            <option value="5">5 Star / Excellent</option>
            <option value="4">4 Star / Good</option>
            <option value="3">3 Star / Average</option>
            <option value="2">2 Star / Bad</option>
            <option value="1">1 Star / Terrible</option>
        </select><br/>
        Would you return/recommend?<br />
        <select name = "willreturn">
            <option value="1">Yes</option>
            <option value="0">No</option>
        </select><br/>
        Capacity<br />
        <select name="capacity">
            <option value="3">Sales (As a Vendor)</option>
            <option value="4">Sales (As a Buyer)</option>
        </select><br />
        I accept the <a href="https://www.allagents.co.uk/terms-conditions/">terms and conditions of allAgents</a><br/>
        <input type="checkbox" name="terms" value ="1">I accept<br><Br/>
        I wish to subscribe to allAgents' newsletter<br/>
        <input type="checkbox" name="newsletter" value ="1">Subscribe<br>
        Your Property Address (Not published):<br>
        <input name="propname" type="text" value="" size="30"/><br>
        Your Property Postcode Area, e.g. N1 (Published):<br>
        <input name="prop_postcode" type="text" value="" size="30"/><br>
        Property price &pound;:<br>
        <input name="sold_price" type="text" value="" size="30"/><br>
        Were you satisfied with the agent's fees?<br/>
        <select name="fee_satisfaction">
            <option value="1">Yes</option>
            <option value="0">No</option>
        </select><br />
        Was the agent's valuation accurate?<Br />
        <select name="best_price">
            <option value="1">Yes</option>
            <option value="0">No</option>
        </select><br />
        <Br/><input type="submit" value="Send email"/>
    </form>


<?php
 }
         else   /* send the submitted data */
         {
          $headers = array('APIKEY: 12c4f1b01949'); //Example API Key which must be changed.
          $form_url = "http://www.allagents.co.uk/api/v1/firms/example-firm/branches/example-branch/reviews/";

          $data_to_post = array();
          $data_to_post['name'] = $_POST['name'];
          $data_to_post['firstname'] = $_POST['firstname'];
          $data_to_post['lastname'] = $_POST['lastname'];
          $data_to_post['email'] = $_POST['email'];
          $data_to_post['telephone'] = $_POST['telephone'];
          $data_to_post['review_content'] = $_POST['review_content'];
          $data_to_post['rating'] = $_POST['rating'];
          $data_to_post['willreturn'] = $_POST['willreturn'];
          $data_to_post['capacity'] = $_POST['capacity'];
          $data_to_post['terms'] = $_POST['terms'];  //This must be set to 1 for the review to be added. No error will be provided if 0 is received.
          $data_to_post['newsletter'] = $_POST['newsletter'];
          $data_to_post['propname'] = $_POST['propname'];
          $data_to_post['prop_postcode'] = $_POST['prop_postcode'];
          $data_to_post['agentfeedback'] = $_POST['agentfeedback']; //optional field not included in example form
          $data_to_post['sold_price'] = $_POST['sold_price'];
          $data_to_post['rent_pcm'] = $_POST['rent_pcm']; // Not used, sales price in form instead.
          $data_to_post['fee_satisfaction'] = $_POST['fee_satisfaction'];
          $data_to_post['best_price'] = $_POST['best_price'];
          $data_to_post['fee_feedback'] = $_POST['fee_feedback']; //optional field not included in example form


          // Initialize cURL
          $curl = curl_init();
          // Set the options
          curl_setopt($curl,CURLOPT_URL, $form_url);
          // This sets the number of fields to post
          curl_setopt($curl,CURLOPT_POST, sizeof($data_to_post));
          // This is the fields to post in the form of an array.
          curl_setopt($curl,CURLOPT_POSTFIELDS, $data_to_post);
          // This sends the custom header containing the API key
          curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
          //execute the post
          $result = curl_exec($curl);

          //close the connection
          curl_close($curl);

          echo 'Thanks for your review!';

           }
           ?>



                
• Adding Schema Markup (e.g. For Stars in Google)
<?php
$headers = array('APIKEY: 12c4f1b01949'); //Example API Key which must be changed.

$url = "https://www.allagents.co.uk/api/v1/firms/example-firm/branches/example-branch/markup/";

$curl = curl_init(); // Initialize cURL

// Set the options
curl_setopt($curl,CURLOPT_URL, $url); //Use request url defined
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); //We want the result variable to contain the output
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); //send custom header with the API Key
$result = curl_exec($curl); //Make request via curl, keep output in result variable

curl_close($curl);//close the connection

$decodedResult = (json_decode($result, true));

echo($decodedResult); //Prints out the markup. Test page with Google Structured Data Testing Tool