Notes

Creating a Note

To create a note, we need a few things. First the comment and the user, user_id, who wrote the note. In addition to this you need to pass in listing_ids and, optionally, tags, whilst similar they have different uses.

The listing_ids parameter is an array of listings ids within the chain that you would like to associate the note with, so that it can appear inside the includes (we'll explain that in the Getting Notes section below). We recommend that you pass in all listing ids on a chain, so that should a chain change for any reason you won't have lost your notes.

The tags parameter is an array of listing ids that you would like a note to be explicitly linked to, it may be that the note you are creating is not about your listing but a different listing, or listings, in the chain, maybe one listing has asked for additional information on another and you would like to make a note about it and tag the listings involved.

Let's run through an example of this:

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -X POST -d { \
    "comment": "Mr and Mrs Smith have still not received the contract", \
    "user_id": 1, \
    "listing_ids": [1, 2, 3, 4], \
    "tags": [2, 3] } \
  https://developers.viewmychain.com/api/v1/note

Here we created a note by user 1 that says Mr and Mrs Smith have still not received the contract, and we have attached all 4 listing ids in the chain in the listing_ids parameter. Additionally, we have tagged the note with listing 2 and 3. If successful, you will receive a response like this:

{
  "data": {
    "id": "1",
    "type": "note",
    "attributes": {
      "created_at": 1485517053,
      "comment": "Mr and Mrs Smith have still not received the contract",
      "user_id": 1,
      "tags": ["2 High Street", "27 Boundary Avenue"],
      "created_by": "John Doe",
      "updated_at": 1485517053,
      "deleted_at": null
    }
  }
}

In the response you will notice that the tags are presented to you with the street addresses as opposed to the listing_ids. Additionally, the response also contains the users name, created_by, as well as the user_id. This is to save you having to make multiple requests for presentation data.

API Reference https://developers.viewmychain.com/api/v1/note

Getting Notes

You can get all notes you or your team members have created by using the note index end point, which is relatively straight forward, however it is probably not very useful, you probably want to get notes on a listing basis. You can do that too! Use the get listing endpoint and include the notes like so:

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

{
  "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": {
      "notes":{
        "data": [{
          "type": "note",
          "id": 1
        },{
          "type": "note",
          "id": 2
        }]
      }
    }
  },
  "included": {
    "data": [{
      "type": "note",
      "id": "1",
      "attributes": {
        "comment": "Example comment 1",
        "user_id": 1,
        "tags": [
          "1 Sample Street"
        ],
        "created_by": "John Doe",
        "created_at": 1485517053,
        "updated_at": 1485517053,
        "deleted_at": null
      }
    },
    {
      "type": "note",
      "id": "2",
      "attributes": {
        "comment": "Example comment 2",
        "user_id": 1,
        "tags": [
          "1 Sample Street",
          "2 High Street"
        ],
        "created_by": "John Doe",
        "created_at": 1485772031,
        "updated_at": 1485517053,
        "deleted_at": null
      }
    }]
  }
}

You can only retrieve notes by users in the same branch(es) as you.

API References https://developers.viewmychain.com/api/v1/note https://developers.viewmychain.com/api/v1/listing/{listing}