Classified ads in UK
Hallo Classifieds Ads

Current Location

Distance

Hallo - API Developers Guide


Manage your classifed ads feeds from your own applications.

Get Started

Today information is consumed at such a pace, across such a breadth of media that syndication of data, and the accessibility of that data has become even more important for users, businesses and developers. Hallo is one of the UK's leading classifieds websites and a growing platform for sales and outreach. We're now inviting developers to dive in new opportunities and make their products, properties and ads available quickly and easily.

To start using Hallo API, developers will require an API key. Such is available on request through the Profile Setting in your Hallo account. Keys are normally issued within 24 hours of request and subject to our Terms of Use.

The Basics

Hallo API supports json and xml formats in responce communication. The format can be specified through the optional .format parameter, and if this optional parameter is missed, the API will default results to json.

Every request is passed to method url together with parameters specific for the method, described below in this documentation.

Example Method URL:
https://api.hallo.co.uk/adverts/categories{.format}?key={key}

parameter description
.format Specifies optionally data format for responce. If option is not passed, will default to json.
key Specifies user's API key, required for all requests.

NOTE These default parameters will be excluded in method descriptions below, unless are the only parameters of the method.


Get Categories List

Returns information about the category tree.

Method URL (GET):
https://api.hallo.co.uk/adverts/categories{.format}?key={key}

parameter description
.format Specifies optionally data format for responce. If option is not passed, will default to json.
key Specifies user's API key, required for all requests.

Response Fields
List of fields returned by the request, excluding header fields.

field description
category_id Unique category id
category The main category name or combined name for main and sub-category. Use to pass back to API category by name.
category_parent_id Unique owner category id

Get Advert Details

Returns all available information for an advert.

Method URL (GET):
https://api.hallo.co.uk/adverts/{hallo_ref}{.format}?key={key}

parameter description
hallo_ref Advert reference ID

Response Fields
List of fields returned by the request, excluding header fields.

field description
hallo_ref Unique advert id
external_ref External reference, if provided with posting
category Contains category elements containing category ids and categories names.
title Advert title
text Text of advert including HTML
time_posted Time of posting in Unix time
time_expires Time the advert will expire in Unix time
addr_line1 Advert's address element
addr_line2 Advert's address element, always optional
addr_pcode Address postcode element
addr_town Address town element
addr_county Address county element
addr_region Address country element
phone Telephone number for contact
email Email for advert communication
price This field represent value of Price, Sallary, Rent, etc, depending on category section
price_type Returns price deratives of pcm, per week, annum, total, etc.
visits Number of unique visits the advert had on the all active web channel.
images Includes an array of images with elements image_id - unique identifier, image_label - description if provided, image_url - location uri.
fields An array of additional fields derived from category type in pairs of fid - unique field identificator and its value. See Get Advert Specification for resolving field IDs into text.

Get Advert Specification

This method returns a template of all available fields for an advert based on category_id of posting. Adverts in different categories will require different set of details. The spec includes as well indication for required fields.

Method URL (GET):
https://api.hallo.co.uk/adverts/specification/{category_id}{.format}?key={key}

parameter description
category_id Specify which category the advert(s) will be posted in

Response Fields
Field and requirements may vary depending on category and their type.

field required description
category true Main category id
sub_category true Sub-category id
title true Advert title
text true Text of advert including HTML
time_posted true Time of posting in Unix time
time_expires true Time the advert will expire in Unix time
phone false Telephone number for contact
email true Email for advert communication
price true This field represent value of Price, Sallary, Rent, etc, depending on category section
price_type true Returns price deratives of pcm, per week, annum, total, etc.
image false Holds the name of the default image for the advert
addr_town true Address town element
addr_county true Address county element
addr_region true Address country element
addr_line1 false Advert's address element
addr_line2 false Advert's address element, always optional
addr_pcode false Address postcode elements
external_ref false Optional external reference of product or service. Available with My Adverts List as search parameter.
duration true Duration of adverts in days
fields
(array)
false Array of additional fields describing the item: extra_field_id - field id, extra_field_name - field name, extra_field_type - field data type, field_values, extra_field_required - required field indicator

Get My Adverts List

Returns list of own adverts as per search parameters.

Method URL (GET):
https://api.hallo.co.uk/adverts/mylist{.format}?key={key}

parameter description
category_id Search by category ID
category Search by category name. If sub-category provided, should be passed as "Main Category > Sub Category"
place Search by place - town, county or region.
postcode Exact search by postcode.
tags Search by tag names separated by comma. Tags list codes:
featured
, urgent, new, reduced, onsale, limitedstock, homemade, personalised, freedelivery, madeinuk, specialoffer, freegift, 241, freequote, sameday
with_image Filter by image, values true or false.
min_price Lower budget boundary, number
max_price Upper budget boundary, number.
search Search keywords applied on Title of the advert
page Specified page number to returned
page_items Specifies how many items per page to returned

Response Fields
List of fields returned by the request, excluding header fields.

field description
hallo_ref Unique advert id
external_ref External reference, if provided with posting
category Contains category elements containing category ids and category names
title Advert title
text Text of advert, some HTML tags are allowed
time_posted Time of posting in Unix time
time_expires Time the advert will expire in Unix time
addr_line1 Advert's address element
addr_line2 Advert's address element, always optional
addr_pcode Address postcode element
addr_town Address town element
addr_county Address county element
addr_region Address country element
phone Telephone number for contact
email Email for advert communication
price This field represent value of Price, Sallary, Rent, etc, depending on category section
price_type Returns price deratives of pcm, per week, annum, total, etc.
visits Number of unique visits the advert had on the all active web channel.
images Includes an array of images with elements image_id - unique identifier, image_label - description if provided, image_url - location uri.
fields An array of additional fields derived from category type in pairs of fid - unique field identificator and its value. See Get Advert Specification for resolving field IDs into text.

Post Advert by XML / JSON

Posts a structured json or xml formatted stream for submission. For complete fields list and structure for specific category see Get Advert Specification.

Use preferred image upload method after advert ref is returned to upload image(s) associated to this advert.

Method URL (POST):
https://api.hallo.co.uk/adverts/add{.format}?key={key}

parameter description
hallo_ref If value is passed, import will create or update an advert
external_ref External reference, optional
category_id Category id as per category tree list
title Advert title
text Text of advert, some HTML tags are allowed
duration Duration of the advert in days, values accepted - 3, 7, 14, 30
addr_line1 Advert's address element
addr_line2 Advert's address element, always optional
addr_pcode Address postcode element
phone Telephone number for contact
email Email for advert communication
price Representation value of Price / Sallary / Rent, etc, depending on category section
price_type Accepted values: total - for items and services; ph - per hour, pw - per week, pcm - per month, pa - per annum
image_id ID of the image from My Images List to be linked to this advert, optional
fields Collection of extra fields shown below
fields | extra_field_id ID of the additional field to be passed, as per Advert Specification for a category
fields | extra_field_value Value of the additional field to be passed, as per Advert Specification for a category

Response Fields
List of fields returned by the request, excluding header fields.

field description
status Returns 1 for successful post or 0 for failed posting
hallo_ref If, status is 1, will contain the new advert reference
result Returns API response message

Post Advert by Form

Submits advert fields as Form elements or pair-value array. Upload form requires enctype="multipart/form-data". For complete fields list and structure for specific category see Get Advert Specification.

Use preferred image upload method after advert ref is returned to upload image(s) associated to this advert.

Method URL:
https://api.hallo.co.uk/adverts/request/add{.format}?key={key}

parameter description
hallo_ref If value is passed, import will create or update an advert
external_ref External reference, optional
category_id Category id as per category tree list
title Advert title
text Text of advert, some HTML tags are allowed
duration Duration of the advert in days, values accepted - 3, 7, 14, 30
addr_line1 Advert's address element
addr_line2 Advert's address element, always optional
addr_pcode Address postcode element
phone Telephone number for contact
email Email for advert communication
price Representation value of Price / Sallary / Rent, depending on category section
price_type Accepted values: total - for items and services; ph - per hour, pw - per week, pcm - per month, pa - per annum
extra_field_id ID of the additional field to be passed, as per Advert Specification for a category
extra_field_value Value of the additional field to be passed, as per Advert Specification for a category
image_id ID of the image from My Images List to be linked to this advert, optional

Response Fields
List of fields returned by the request, excluding header fields.

field description
status Returns 1 for successful post or 0 for failed posting
hallo_ref If, status is 1, will contain the new advert reference
result Returns API response message

Delete Advert

Returns the heirarchy of the categories tree.

Method URL:
https://api.hallo.co.uk/adverts/remove/{hallo_ref}{.format}?key={key}

parameter description
hallo_ref Specify advert ref ID for deletion

Response Fields
List of fields returned by the request, excluding header fields.

field description
status Returns 1 for successful post or 0 for failed posting.

Performs a search and returns summarised information about advert available on Hallo's live index.

Method URL:
https://api.hallo.co.uk/adverts/search{.format}?key={key}&par1=value&par2=value

parameter description
.format Specifies optionally data format for responce. If option is not passed, will default to json.
key Specifies user's API key, required for all requests.
category_id Search by category ID
category Search by category name. If sub-category provided, should be passed as "Main Categery > Sub Category"
place Search by place - town, county or region.
postcode Exact search by postcode.
tags Search by tag names separated by comma. Tags list codes:
featured
, urgent, new, reduced, onsale, limitedstock, homemade, personalised, freedelivery, madeinuk, specialoffer, freegift, 241, freequote, sameday
with_image Filter by image, values true or false.
min_price Lower budget boundary, number
max_price Upper budget boundary, number.
search Search keywords applied on Title of the advert
page Specified page number to returned
page_items Specifies how many items per page to returned

Response Fields
List of fields returned by the request, excluding header fields.

field description
hallo_ref Unique advert id
category Array with all category elements
title Advert title
time_posted Time of posting in Unix time
time_expires Time the advert will expire in Unix time
addr_line1 Advert's address element
addr_line2 Advert's address element, always optional
addr_pcode Address postcode element
addr_town Address town element
addr_county Address county element
addr_region Address country element
price This field represent value of Price, Sallary, Rent, etc, depending on category section
price_type Returns price deratives of pcm, per week, annum, total, etc.
image Image URL, if available.

Get My Images List

Returns list of my images.

Method URL:
https://api.hallo.co.uk/files/list{.format}?key={key}

parameter description
.format Specifies optionally data format for responce. If option is not passed, will default to json.
key Specifies user's API key, required for all requests.
limit Maximum number of records to return.

Response Fields
List of fields returned by the request, excluding header fields.

field description
id Unique file id
file_name Image name
file_label Image desciption

Upload Image by Post

Upload image from Post request.

Method URL:
https://api.hallo.co.uk/files/post{.format}?key={key}

parameter description
hallo_ref Advert reference
file_name File for upload
file_label File description

Response Fields
List of fields returned by the request, excluding header fields.

field description
status Returns 1 for successful post or 0 for failed posting
hallo_ref Returns the image id on success

Upload Image from URL

Uploads an image, which is available on provided URL.

Method URL:
https://api.hallo.co.uk/files/post/url{.format}?key={key}

parameter description
hallo_ref Advert reference
url Image URL
file_label File description

Response Fields
List of fields returned by the request, excluding header fields.

field description
status Returns 1 for successful post or 0 for failed posting
hallo_ref Returns the image id on success

Delete Image

Deletes an image from "My Images" and removes association from adverts. Please note, if this is the default image, all other images will be removed as well.

Method URL:
https://api.hallo.co.uk/files/remove/{hallo_ref}{.format}?key={key}

parameter description
hallo_ref Specifies image id for deletion

Response Fields
List of fields returned by the request, excluding header fields.

field description
status Returns 1 for success or 0 for failure

Links an image from "My Images" to an existing advert.

Method URL:
https://api.hallo.co.uk/adverts/link/file{.format}?key={key}&hallo_ref=value&file_id=value

parameter description
hallo_ref Specifies advert reference
file_id Specifies image reference

Response Fields
List of fields returned by the request, excluding header fields.

field description
status Returns 1 for success or 0 for failure

Get My Profile Settings

Returns some user profile settings.

Method URL:
https://api.hallo.co.uk/user/details{.format}?key={key}

parameter description
.format Specifies optionally data format for responce. If option is not passed, will default to json.
key Specifies user's API key, required for all requests.

Response Fields
List of fields returned by the request, excluding header fields.

field description
first_name Unique category id
last_name The main category name or combined name for main and sub-category. Use to pass back to API category by name.
company_name Unique owner category id
email Unique owner category id
addr_line1 Advert's address element
addr_line2 Advert's address element, always optional
addr_pcode Address postcode element
addr_town Address town element
addr_county Address county element
addr_region Address country element

Import Tool for CSV & Excel

For bulk upload of products, properties and jobs, an import tool is available from My Adverts section in your Hallo account.

A benefit of the the tool is that it allows only certian fields to be imported by selecting the source columns from an existing source file. Some fields will be picked directly from the user's profile (like contact details) and others can be prefilled on screen with particular for the import preferences.

Although is the quickest solution for bulk upload we can think of, this import tool does not allow upload of images, so they have to be uploaded after the import.

The import makes use of the "external_ref" field, which the user can submit as their own reference number for the classifieds listing. Adverts re-posted later with the same "external_ref" code, will updated and bumped-up, instead of being duplicated.

All new adverts imported by the tool will be first held under review with status message showing in your adverts list as "108 Imported Product Waiting Approval". Once an advert is approved and "external_ref" is matched on next import, the advert will be released without moderation.


API Terms of Use

This API is available under following terms, which extend Hallo's main Terms & Conditions and our Advertising Guidelines.

Thank you for using the Hallo API.

This API is owned and operated by Increate Ltd under the trading names of “Hallo”, “Hallo UK”, “Hallo.co.uk” or in the contents of these terms as “We” and Registered in England and Wales under company number 05965686 with registered address is 125 Claremont Road, NW2 1AH, London.

By accessing and using the Hallo API (the "API"), you or the identity you represent (the “3rd party”, “you”) explicitly agree to comply with and be bound by the following Terms and Conditions (“Terms”, “Terms of Use”, “Terms and Conditions”, “Agreement”), which We reserve the right to change at any time, with or without notice, in our sole and absolute discretion. Please, make sure that you regularly make yourself familiar with the current terms of use and you are conforming to the most recent version of these terms.

1. The Content

The API is a service that offers content programming tools, enabling third parties to create applications or websites that display certain content (“the Content”) that “Hallo” offer by way of output from the API and update from time to time, subject to these Terms. The Content includes, but is not limited to, the output of the API methods as listed in each of the sections of the API Documentation, located at https://www.hallo.co.uk/api_docs, including agent property listings and proprietary data around property values.

2. Access To The API

Access to the API is subject to approval by “Hallo” and a developer key which is required to be able to make calls to the API and retrieve the content. You may only access the Content using a single and unique key supplied by “Hallo” as an approved licensee. It is possible that you are required to apply for separate keys in order to access the Content from different API methods. The key is confidential and neither the key nor the Content may be sold, leased, transferred or sublicensed to any other party whether for commercial or person purpose, without written permission from "Hallo".

By making use of the API, you agree to “Hallo” accessing your application and/or other materials related to your use of the API as reasonably requested by us to verify your compliance with these Terms. You agree that we may crawl or monitor applications using Content from “Hallo” and you agree not to block or interfere with such efforts.

Every new key is initially issued under a three month free license. This enables “Hallo” to review our basic terms of use are in effect or follow up cases where additional terms need to be agreed. Although each key is limited to 200 calls per hour, we're happy to hear why you need more so email us on . "Hallo" may approve higher daily call limits at our own discretion or may enforce lower daily limits if necessary.

3. Use of Content

The API cannot be used to disintermediate standard “Hallo” business practices. For example, you cannot use “Hallo” Content as a standalone method of generating appraisal commercial leads to without there being commercial benefit to “Hallo”, either in the form of a pre-agreed commercial licence of the appropriate API calls to facilitate this, or through an affiliate commission model whereby the application is providing additional reach for “Hallo” lead generation. We will disable any API key related to applications that contravene this clause with immediate effect.

If the web address or application cannot be viewed publicly, a test environment or screengrabs will need to be provided unless specific approval has been given otherwise. If you are unable to demonstrate how you are using “Hallo” data we will be forced to disable the key until such time that you can. To request approval in such instances, please contact

4. Displaying the Content

Any Content delivered by “Hallo” channels including this API, cannot be re-distributed at any time without requesting written permission from “Hallo”.

The raw output from any API method cannot be modified by the 3rd party without prior permission. This does not include re-styling from the perspective of colour & font.

You may not retain any copies of the “Hallo” API output data. Your license to “Hallo” data via the API is limited to displaying classifieds ads and directing the user to the “Hallo” site from which the user can view the complete data on “Hallo.co.uk” or to contact the relevant supplier of the information via “Hallo.co.uk”.
You must not use the API Content to offer or promote services that compete with “Hallo”.

Content from this API output cannot be used to send leads or traffic directly to suppliers and users of “Hallo”, but must direct only to “Hallo.co.uk”.
“Hallo.co.uk” reserves the right, without notice and in our sole discretion, to terminate the 3rd party’s API license and give immediate notice to the 3rd party to destroy all versions of the API data on the 3rd parties application or website. For example, if the content of your website or application is of an offensive or unsavoury nature, or if the "Hallo" data is published in an a manner or context that could, in our reasonable opinion, cause harm to our goodwill, conflict with our values and the objectives of our paying customers or bring our brand into disrepute, we will disable the relevant API key(s).

In the instance of the listings API, unless we have given immediate notice on usage of the content and have terminated the API license and access, the 3rd party is allowed to maintain a listing without it being updated, for 72 hours, in the instance of technical complications with the output. Where updated content is available (usually daily), the 3rd party is obliged to replace the previous listing with the new listing data.

In cases where listings are on a 3rd party website, the content must link through to the original listing page on “Hallo” and it is the 3rd party's responsibility to implement the “nofollow” HTML attribute to content and on these links.

In addition to a link back to the original content, any references to "Hallo" content as obtained via the API must include a link or reference with text "Powered by Hallo.co.uk".

Listings  must be accompanied by "Marketed by" data I.e agent name, logo and phone number. API developers are not permitted to publish or pass off any advertisement assets whether current or expired, without the expressed permission of the listing agent and provided in writing to api@zpg.co.uk

You may not use the Hallo API content for any offline marketing without crediting “Hallo UK” and in accordance with our general attribution rules.

You agree not to use “Hallo” Content or branding in any way that is unlawful, or harms “Hallo”, its service providers, its agents, suppliers, your end users, or any other person. Hallo reserve the right to revoke you license to use the Hallo API, Hallo Data and Hallo Brand if and when Hallo deem your usage to be damaging or inappropriate.

5. Limited Relationship

Nothing within these terms should constitute relationship, partnership, or a joint venture between “Hallo” and the 3rd party. You may publicly refer to your use of our API, but you agree not make any other public statements that assert or imply any other relationship with “Hallo”, unless our prior written approval.

6. Indemnity

You agree to hold harmless and indemnify “Hallo”, its subsidiaries, affiliates, officers, agents, employees, and suppliers, from and against any 3rd party claim arising from or in any way related to your or your users' use of the “Hallo” API or “Hallo” data, use of “Hallo” brand & links other than as set out in the “Hallo” documentation and guidelines.  Violation of these Terms other actions connected with use of “Hallo” services, including any liability or expense arising from all claims, losses, damages (actual and consequential), suits, judgments, litigation costs and attorneys' fees, of every kind and nature. In such a case, “Hallo” will provide you with written notice of such claim, suit or action.

7. No warranties

This API including the content and service (including reliability) are provided on an as is basis without any warranties either explicit or implicit. You expressly agree that the use of this site and the API, including all content or data distribute by or downloaded from the service, is at your sole risk. We disclaim all warranties, explicit or implicit, including but not limited to implied warranties or merchantability fitness for a particular purpose, title and non-infringement as to the information, materials, and content on the site. We do not represent or warrant that materials in this site are accurate, complete, reliable, current, or error-free.

8. Liability limitation

In no event shall Increate Ltd t/a “Hallo”, its officers, directors, agents, partners, employees, advertisers, or data providers be liable for any indirect, special , incidental, consequential or punitive damages (including but not limited to loss of use, loss of profits, or loss of data) whether in an action in contract, tort, (including but not limited to negligence), equity or otherwise, arising out of or in any way connected with the use of the “Hallo” API or “Hallo” data or services. Some jurisdictions do not allow the exclusion or limitation of liability so the above limitations may not apply to you.

Version Log

Latest version of the API is [1.0]. History of changes can be found in list below.

  • Version 1.0 Change Log:
    • Methods Added:
      • Get Categories List
      • Get Advert Details
      • Get Advert Specification
      • Get My Adverts
      • Post Advert by JSON / XML
      • Post Advert by Form
      • Delete Advert
      • Index Search
      • Get My Images List
      • Upload Image by Post
      • Upload Image by URL
      • Delete Image
      • Get My Profile Details