GET /v1/entity/by_supplier_id

HTTP Method: GET

Path: /v1/entity/by_supplier_id

Authentication: API Key required

Description: Fetch an single entity (business) by providing a supplier id.

NOTE: This method only works if you are a Central Index partner and have supplied data to the Central Index. If, on submission of an entity, you provide us with the id of that entity as you know it your systems, then you can retrieve it using this method and your id. Please contact us if you want to become a Central Index data partner.


parameter type description required
supplier_id string The supplier id of the entity to fetch e.g. ABC123 yes

Sample Response:

An array of entities that match the given supplier id will be returned (normally only one) with  everything that is known about the business:

    "success": true,
    "msg": "ok",
    "data": [
            "id": "591224538624000",
            "key": "enablemedia18028864",
            "value": 1,
            "doc": {
                "_id": "591224538624000",
                "_rev": "12-1792d79a2d627c3b9cb3f6dd1c4091a5",
                "type": "business",
                "when": "2014-07-29 14:58:48 +00:00",
                "country": "gb",
                "timezone": "UTC",
                "scope": "public",
                "trust": 1,
                "status": {
                    "status": "active"
                "name": {
                    "name": "R.j. Plumbing & Heating",
                    "formal_name": "",
                    "branch_name": "",
                    "stopwords": "r j plumbing heating",
                    "stemmed": "plumb heat",
                    "phonetic": "PLMB HT"
                "postal_address": {
                    "building_number": "",
                    "address1": "Myrtle Cottage",
                    "address2": "St. Johns Hill Road",
                    "address3": "",
                    "district": "",
                    "town": "Woking",
                    "county": "Surrey",
                    "province": "",
                    "postcode": "GU21 7RW",
                    "address_type": "",
                    "do_not_display": false
                "geopoint": {
                    "longitude": -0.593162,
                    "latitude": 51.3125,
                    "accuracy": 1000,
                    "wgs84": [
                    "geohash": "gcpeft0hf"

If the API had been asked to fetch a non-existent entity, then you will see this response:

    "success": false,
    "msg": "There was an error",
    "data": {
        "missing": true

Three things have happened here:

  • the API returns with HTTP 404 (instead of HTTP 200)
  • the returned json has a success of 'false'
  • the return json's data element has 'missing' set to true, meaning that this entity does not exist


Docs Navigation