Creating a Listing

Once you receive your access token, you're good to go and start creating listings. Creating a listing is very easy, the bare minimum required is an address and a branch.

Let's start with an address; first you'll need to search for your address, using the address filter endpoint, we can pass in a full_address term to find relevant addresses.

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X POST -d '{"full_address":"6 Whittle Court Knowlhill"}' \
  https://developers.viewmychain.com/api/v1/address/filter

You will receive a json response that looks something like:

{
  "data":[
    {
      "type":"address",
      "id":"123456789",
      "attributes":{
        "verified_at":null,
        "address_line_1":"6 WHITTLE COURT",
        "full_address":"6 WHITTLE COURT, KNOWLHILL, MILTON KEYNES, MK5 8FT",
        "post_town":"MILTON KEYNES",
        "postcode":"MK5 8FT",
        "is_parent":false
      }
    }],
    "meta":{
      "pagination":{
        "total":1,
        "count":1,
        "per_page":15,
        "current_page":1,
        "total_pages":1
      }
    },
    "links":{
      "self":"https://developers.viewmychain.com/api/v1/address/filterpage=1",
      "first":"https://developers.viewmychain.com/api/v1/address/filterpage=1",
      "last":"https://developers.viewmychain.com/api/v1/address/filter?page=1"
    }
  }

Because we were specific, we only received one result which is perfect for this scenario. If your search didn't return any results the data array will be empty. We'll grab the id of the address from the first object inside the data array.

Next we need the branch id; as with the address, we will filter for our branch:

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X POST -d '{"name":"view my chain milton keynes"}' \
  https://developers.viewmychain.com/api/v1/branch/filter

{
  "data":[{
    "type":"branch",
    "id":"99999",
    "attributes":{
      "created_at":1485865700,
      "updated_at":1516865947,
      "deleted_at":null,
      "brand_id":9999,
      "name":"View My Chain MILTON KEYNES MK5 8FT",
      "telephone":"01908 829400",
      "email":"",
      "website":""
    }
  }],
  "meta":{
    "pagination":{
      "total":1,
      "count":1,
      "per_page":15,
      "current_page":1,
      "total_pages":1
    }
  },
  "links":{
    "self":"https://developers.viewmychain.com/api/v1/branch/filter?query=view+my+chain+milton+keynes&page=1",
    "first":"https://developers.viewmychain.com/api/v1/branch/filter?query=view+my+chain+milton+keynes&page=1",
    "last":"https://developers.viewmychain.com/api/v1/branch/filter?query=view+my+chain+milton+keynes&page=1"
  }
}

Again, as we were specific we have one result, so lets grab that branch id from the first object inside the data array.

Now we have our address id: 123456789 and our branch id: 99999, we can create our listing:

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X POST -d '{"address_id":123456789, "branch_id": 99999}' \
  https://developers.viewmychain.com/api/v1/listing

And you should receive a json response:

{
  "data": {
    "id": 1,
    "type": "listing",
    "attributes": {
      "address_id": 123456789,
      "branch_id": 99999,
      "price": null,
      "chain_link_id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
      "is_locked": false,
      "full_address": "6 Whittle Court, Knowlhill, Milton Keynes, MK5 8FT",
      "address_street_name": "6 Whittle Court",
      "address_area": "Knowlhill",
      "address_postal_code": "MK5 8FT",
      "created_at": 1511264955,
      "updated_at": 1511264955
    }
  }
}

Success :tada:

You have now created a listing! We recommend saving the listing id from the response, so that you can use it for future actions such as chaining, and adding and upating milestones.

API Reference Links https://developers.viewmychain.com/api/v1/address/filter https://developers.viewmychain.com/api/v1/branch/filter https://developers.viewmychain.com/api/v1/listing

Finding a Listing

Creating a listing is a great start, but View My Chain already has a lot of listings available to you, so before creating one it may be worth checking if one exists first. To see if your listing already exists we can use the listings filter endpoint to search for listings with the given branch and address.

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X POST -d '{"address":123456789, "branch": 99999}' \
  https://developers.viewmychain.com/api/v1/listing/filter

If we have any listings that match, and, importantly, they are your listings i.e. they belong to the same branch as you, then you will get a response like this:

{
  "data": {
    "id": 1,
    "type": "listing",
    "attributes": {
      "address_id": 123456789,
      "branch_id": 99999,
      "price": null,
      "chain_link_id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
      "is_locked": false,
      "full_address": "6 Whittle Court, Knowlhill, Milton Keynes, MK5 8FT",
      "address_street_name": "6 Whittle Court",
      "address_area": "Knowlhill",
      "address_postal_code": "MK5 8FT",
      "created_at": 1511264955,
      "updated_at": 1511264955
    }
  }
}

This response tells us that the listing you were going to create already exists, so you can use that one, and save the listing id against your listing object for future reference. For more information about what filters are avaliable, take a look at the filter endpoint in more detail.

** However... ** What if the listing you are looking for doesn't belong to one of your branches? Well, you would use a slightly different endpoint, the exists endpoint, which does a comprehensive search of all listings inside View My Chain:

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X POST -d '{"address":123456789, "branch": 99999}' \
  https://developers.viewmychain.com/api/v1/listing/exists

The difference between the filter and exists endpoints, is the scope of listings each one searches. filter allows more filter terms to be applied to further fine tune your search, but only searches for listings that belong to your branches, the exists endpoint only accepts the branch and address parameters, and can only include the listings branch, any other includes and nested includes will be ignored on the exists endpoint. The exists endpoint is quite useful when you consider chaining listings together; you don't always need to create a listing before chaining it to one of your own.

A shortcut

Whilst both these endpoints filter and exists require an address and/or branch, you don't need to pass in the ids, you can pass in search terms and allow us to search based on those pieces of data, its not as accurate as the above method, but it will save you having to find the address and branch first, particularly if you don't have them, and if you are specific with your search terms, it is just as effective. The parameters are full_address and branch_name.

The full_address parameter is named as such as it is going to try and match against the full address of the listing, you can pass in any partial address term here, although postcode is good bet, or house number and street name, for added effect pass in the town or village as well.

The branch_name parameter again will take the term you pass here and match it against the listing's branch name, it can be a partial as well, but just so you know, and for ease, our naming convention for branches is <BRAND NAME> <LOCALITY>, so if the brand is "View My Chain and they have a branch in "Milton Keynes", you can be pretty safe passing in "View My Chain Milton Keynes" and the branch search will match all listings against the correct branch. Here's an example:

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X POST -d '{"full_address": "6 Whittle Court Knowlhill" , "branch_name": "View My Chain Milton Keynes"}' \
  https://developers.viewmychain.com/api/v1/listing/exists

Response:

{
  "data": {
    "id": 1,
    "type": "listing",
    "attributes": {
      "address_id": 123456789,
      "branch_id": 99999,
      "price": null,
      "chain_link_id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
      "is_locked": false,
      "full_address": "6 Whittle Court, Knowlhill, Milton Keynes, MK5 8FT",
      "address_street_name": "6 Whittle Court",
      "address_area": "Knowlhill",
      "address_postal_code": "MK5 8FT",
      "created_at": 1511264955,
      "updated_at": 1511264955
    }
  }
}

As you can see, if you use the search terms effectively, it can save you API requests and time. In this situation we returned the exact same results as passing in the branch and address. Ultimately, it is up to you how you implement finding a listing, if you're confident of your search terms use the shortcut, if you're not so sure try finding the branch and address separately first.

API Reference Links https://developers.viewmychain.com/api/v1/listing/filter https://developers.viewmychain.com/api/v1/listing/exists