Chaining improved

This approach uses your listing as an anchor to carry out tasks on a chain. Adding to a chain is easier, checking a chain is easier, there's now no need for you to store anything other than the View My Chain listing id. The original methods as documented below are still valid; the only action that cannot be carried out this way is breaking a chain, View My Chain still needs to know which two listings it is breaking apart.

Checking a chain

To check or uncheck the top or bottom of a chain it is as simple as hitting one of 4 endpoints:

Action Endpoint
Check Top https://developers.viewmychain.com/api/v1/listing/chain/{listing}/check/top
Check Bottom https://developers.viewmychain.com/api/v1/listing/chain/{listing}/check/bottom
Uncheck Top https://developers.viewmychain.com/api/v1/listing/chain/{listing}/uncheck/top
Uncheck Bottom https://developers.viewmychain.com/api/v1/listing/chain/{listing}/uncheck/bottom

Adding to a chain

You can add to the top and the bottom fo a chain, the first listing id is yours, this represents the chain your listing is in. The second listing id the id of the listing you want to add to the chain. Finally, you need to decide if you're adding to the top or bottom of the chain:

Action Endpoint
Top https://developers.viewmychain.com/api/v1/listing/chain/{listing}/add/top/{listing_link_id}
Bottom https://developers.viewmychain.com/api/v1/listing/chain/{listing}/add/bottom/{listing_link_id}

The response

If any of the above are successful, the response you get is a simple success response, because you no longer need to care about the chain_link_id, it is unnessecary to have a response sent back to you with all the new information, you already have all the information you need to represent your chain, and there is no new information. In light of this we recommend that when you are retrieving chain information, you use opt to include chained_listings with your listing get request.

Chains

Chaining Listings

View My Chain wouldn't be View My Chain if you couldn't create and manage chains. We'll begin with chaining one listing to another. First, make sure both the listings exist and if not create them. If you're unsure how to do this go back to the Creating a Listing tutorial. Chaining two listings together is very easy, of the two listings identify which one is buying the other, that one becomes the buyer and the other the seller; the buyer buys from the seller, and the seller sells to the buyer. Now its a case of making a simple request passing in the buyer and seller. The attributes you supply are the listing id's.

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X POST -d '{"seller": 1, "buyer": 2}' \
  https://developers.viewmychain.com/api/v1/chain/add/link

If successful, you will receive a response with both the listings objects. Notice that the chain_link_id has been updated, and each listings chain_link_id matches, this is because they are now part of the same chain.

Note: You can save the chain_link_id against your own data if you want to, but because other agents may interact with the chain, this could change as each break and addition can form a new chain with a new chain_link_id; we suggest you save the listing id, and retrieve the listing from View My Chain, and then use the chain_link_id in the response for future API calls.

This endpoint will only fail if you provide listing ids that do not exist, or the buyer or seller has a respecive seller or buyer. You can check whether a listing has a buyer or seller by retrieving the listing and including the buyer and/or seller:

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X GET https://developers.viewmychain.com/api/v1/listing/1?includes=buyer,seller

The response will look something like this:

{
  "data": {
    "id": 1,
    "type": "listing",
    "attributes": {
      "address_id": 12345678,
      "branch_id": 1,
      "price": 100000,
      "chain_link_id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
      "is_locked": false,
      "full_address": "1 Sample Street, Sample Town, AB12 3CD",
      "address_street_name": "1 Sample Street",
      "address_area": "Sample Town",
      "address_postal_code": "AB12 3CD",
      "created_at": 1511264955,
      "updated_at": 1511264955
    },
    "relationships": {
      "buyer":{
        "data": {
          "type": "buyer",
          "id": 2
        }
      },
      "seller": {
        "data": {
          "type": "seller",
          "id": 3
        }
      }
    }
  },
  "included": {
    "data": [{
      "id": 2,
      "type": "buyer",
      "attributes": {
        "address_id": 7345872548,
        "branch_id": 35439,
        "price": 100000,
        "chain_link_id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
        "is_locked": false,
        "full_address": "2 Fake  Road, Fake Town, DC12 3AB",
        "address_street_name": "2 Fake Road",
        "address_area": "Fake Town",
        "address_postal_code": "DC12 3AB",
        "created_at": 1511264955,
        "updated_at": 1511264955
      }
    }, {
      "id": 3,
      "type": "seller",
      "attributes": {
        "address_id": 35478873,
        "branch_id": 5678,
        "price": 100000,
        "chain_link_id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
        "is_locked": false,
        "full_address": "3 High  Street, Some Where, TH12 3LO",
        "address_street_name": "3 High Street",
        "address_area": "Some Where",
        "address_postal_code": "TH12 3LO",
        "created_at": 1511264955,
        "updated_at": 1511264955
      },
    }]
  }
}

If either the buyer or seller relation exists they will be present in the response.

The order of the includes can change depending on what includes you ask for.

As stated before, you will only be able to get a listing if it belongs to you, so if you want to add a link to a chain, that involves two listings that do not belong to your branch, you won't be able to check before hand. Also, you won't be able to create or break chains if one of your listings is not involved.

We have shown you how you can check before hand whether your listing has a buyer or seller, however, it may be just as quick to make the link request, and let the validation take over; the error message returned will tell you which listing of the link failed, and you can action accordingly. See the API reference for more information on the errors returned.

API Reference https://developers.viewmychain.com/api/v1/chain/add/link https://developers.viewmychain.com/api/v1/listing/1

Breaking Chains

Breaking a chain link is as simple a request as adding a chain link, you pass in the buyer and seller listing ids:

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X POST -d '{"seller": 1, "buyer": 2}' \
  https://developers.viewmychain.com/api/v1/chain/remove/link

If successful, the response will be a simple success response:

{
  "message": "success",
  "success": true,
  "data": [],
  "errors": []
}

API References https://developers.viewmychain.com/api/v1/chain/remove/link

Checking Chains

Again, checking chains is quite simple. You need three parameters, the chain_link_id, whether you're checking the top or bottom of the chain, and the reason for doing so.

You can get the chain_link_id from the listing, so make a call to get a listing of the chain you want to check, and then grab the chain_link_id. Then you set top to true or false, true if checking the top, false if you want to check the bottom. Then finally the reason for checking, currently there is only one reason Checked. So now we have our attributes its time to make the request:

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X POST -d '{"reason": "Checked", "top": true}' \
  https://developers.viewmychain.com/api/v1/chain/DFAD3925-0322-49F4-8F14-BF516CE96097/check

If successful you will get a simple success response:

{
  "message": "success",
  "success": true,
  "data": [],
  "errors": []
}

If you would like to uncheck a chain, then the request is very similar, the only difference is the reasons available to you:

Reason
Unspecified
Not EOC
Dont Know If EOC

EOC stands for End of Chain

The request will look something like this:

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X POST -d '{"reason": "Not EOC", "top": true}' \
  https://developers.viewmychain.com/api/v1/chain/DFAD3925-0322-49F4-8F14-BF516CE96097/uncheck

If successful you will get a simple success response:

{
  "message": "success",
  "success": true,
  "data": [],
  "errors": []
}

API References https://developers.viewmychain.com/api/v1/chain/{chain_link_id}/check https://developers.viewmychain.com/api/v1/chain/{chain_link_id}/uncheck

Retrieving a Chain

As part of your integration you will may like to display the chain in full, you can do this by using the chain listings endpoint:

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X GET https://developers.viewmychain.com/api/v1/chain/DFAD3925-0322-49F4-8F14-BF516CE96097/listings

This will return to you all listing objects within the given chain. The listings will be in order from bottom to top of chain.

View My Chain displays a chain mini map on our application and that is achieved by returning chain data. Chain data is a few statistics about the chain from a given listings perspective, here's a breakdown of what's included:

Attribute Example Explanation
id DFAD3925-0322-49F4-8F14-BF516CE96097 This is the chain link id of the chain, it's what groups the listings together in chain
length 4 This is the number of listings in a chain
position 2 This attribute is 0 indexed, so 0 would be the first property, in this exmaple 2 is the third property. This matches common array indexing
top_checked true Whether the top of the chain is checked
bottom_checked false Whether the bottom of the chain is checked

To get the chain data, you need to include it as part of the listing get request:

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X GET https://developers.viewmychain.com/api/v1/listing/1?includes=chain_data

The response will look something like this:

{
  "data": {
    "id": 1,
    "type": "listing",
    "attributes": {
      "address_id": 12345678,
      "branch_id": 1,
      "price": 100000,
      "chain_link_id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
      "is_locked": false,
      "full_address": "1 Sample Street, Sample Town, AB12 3CD",
      "address_street_name": "1 Sample Street",
      "address_area": "Sample Town",
      "address_postal_code": "AB12 3CD",
      "created_at": 1511264955,
      "updated_at": 1511264955
    },
    "relationships": {
      "chain_data":{
        "data": {
          "type": "chain_data",
          "id": "DFAD3925-0322-49F4-8F14-BF516CE96097"
        }
      }
    }
  },
  "included": {
    "data": [{
      "id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
      "type": "chain_data",
      "attributes": {
        "length": 4,
        "position": 2,
        "top_checked": true,
        "bottom_checked": false
      }
    }]
  }
}

Alternatively, a quicker method is to include the chained listings from the get listing endpoint.

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X GET https://developers.viewmychain.com/api/v1/listing/1?includes=chained_listings

This will return the usual listing response, however, within the included attribute, you will now have the listings in the same chain as the given one. It will also include the given listing, and the listings will be in chain order from bottom of the chain to the top:

{
  "data": {
    "id": 1,
    "type": "listing",
    "attributes": {
      "address_id": 12345678,
      "branch_id": 1,
      "price": 100000,
      "chain_link_id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
      "is_locked": false,
      "full_address": "1 Sample Street, Sample Town, AB12 3CD",
      "address_street_name": "1 Sample Street",
      "address_area": "Sample Town",
      "address_postal_code": "AB12 3CD",
      "created_at": 1511264955,
      "updated_at": 1511264955
    },
    "relationships": {
      "chained_listings":{
        "data": [
          {
            "type": "chained_listing",
            "id": 2
          },
          {
            "type": "chained_listing",
            "id": 1
          },
          {
            "type": "chained_listing",
            "id": 3
        ]
      }
    }
  },
  "included": {
    "data": [{
      "id": 2,
      "type": "chained_listing",
      "attributes": {
        "address_id": 7345872548,
        "branch_id": 35439,
        "price": 100000,
        "chain_link_id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
        "is_locked": false,
        "full_address": "2 Fake  Road, Fake Town, DC12 3AB",
        "address_street_name": "2 Fake Road",
        "address_area": "Fake Town",
        "address_postal_code": "DC12 3AB",
        "created_at": 1511264955,
        "updated_at": 1511264955
      }
    }, {
      "id": 1,
      "type": "listing",
      "attributes": {
        "address_id": 12345678,
        "branch_id": 1,
        "price": 100000,
        "chain_link_id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
        "is_locked": false,
        "full_address": "1 Sample Street, Sample Town, AB12 3CD",
        "address_street_name": "1 Sample Street",
        "address_area": "Sample Town",
        "address_postal_code": "AB12 3CD",
        "created_at": 1511264955,
        "updated_at": 1511264955
      }
    }, {
      "id": 3,
      "type": "chained_listing",
      "attributes": {
        "address_id": 35478873,
        "branch_id": 5678,
        "price": 100000,
        "chain_link_id": "DFAD3925-0322-49F4-8F14-BF516CE96097",
        "is_locked": false,
        "full_address": "3 High  Street, Some Where, TH12 3LO",
        "address_street_name": "3 High Street",
        "address_area": "Some Where",
        "address_postal_code": "TH12 3LO",
        "created_at": 1511264955,
        "updated_at": 1511264955
      },
    }]
  }
}

API References https://developers.viewmychain.com/api/v1/chain/{chain_link_id}/listings https://developers.viewmychain.com/api/v1/listing/1