Milestone States
We covered retrieving milestones when getting a listing, but often the date and type of milestone doesn't provide enough context to the end user, so we created object called milestone state. The state object comprises of 4 attributes.
State
The state of a milestone can be one of none, ok, actionable, where some action is required such as unlocking funding, or requires_attention where the listing has potentially fallen through and the milestones needs to be confirmed. In View My Chain we use the state as an idicator of the colour a milestone should be for example, a state of ok would render the milestone as green.
Concern
This is a statement or warning to explain the state a little more. This can also be null. Inside View My Chain we use as the tooltip on the milestone, and render this on the editor to give the user more information.
Heading
In the milestones current state, the name of the milestone would be more apt if it were called by this value instead such as Possible Searches instead of Searches Ordered. This can be null.
Status
The status of the milestone can be one of warning, where the milestone has changed unexpectedly, locked, where the milestone is locked pending an action, dubious, where the milestone needs to confirmed or corrected, or null. View My Chain use this to display an icon to the user to indicate that something is not right.
There are two ways to retrieve milestone state.
A Single Milestone State
If you would like to find the milestone state of a milestone for a given listing, then this is the method for you.
curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
-X POST -d '{"milestone":"sstc"}' \
https://developers.viewmychain.com/api/v1/listing/1/milestone/state
This will return the milestone state of the SSTC milestone for listing 1:
{
"message": "success",
"success": true,
"data": {
"result": {
"state": "requires_attention",
"concern": "Possible fall through has been seen",
"heading": "SSTC",
"status": "warning"
}
}
}
Here is a list of the milestone short names that you can pass in:
| Name | Short Name |
|---|---|
| SSTC | sstc |
| Draft Contracts Prepared | draft_contracts_prepared |
| Searches Ordered | searches_ordered |
| Searches Expected | searches_expected |
| Funding Applied | funding_applied |
| Proposed Exchange | proposed_exchange |
| Proposed Completion | proposed_completion |
| Enquiries Opened | enquiries_opened |
| Enquiries Closed | enquiries_closed |
| Survey Booker For | survey_booked_for |
| Survey Satisfactory | survey_satisfactory |
Getting all Milestone States
If you want to get all milestone states of a listing then you are better using the include method:
curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
-X GET https://developers.viewmychain.com/api/v1/listing/1461063?includes=milestone_states
This will return the following milestone states:
- SSTC
- Draft Contracts Prepared
- Searches Ordered
- Searches Expected
- Funding Applied
- Proposed Exchange
- Proposed Completion
- LandReg Completion 1
- Enquiries Opened
- Enquiries Closed
- Survey Booked For
- Survey Satisfactory
- LastLandRegCompletion 2
1 This milestones completion date is the date the Land Registry flagged the completion of the property.
2 This milestones completion date is the date of the completion date according the Land Registry, many of the milestones in View My Chain must be after the LastLandRegCompletion completion date.
The response will look like something this:
{
"data":{
"type":"listing",
"id":"1461063",
"attributes":{
"created_at":1502668800,
"updated_at":1513641600,
"deleted_at":null,
"status_changedate":1510185600,
"date_last_received":1516838400,
"address_id":3474354223467,
"branch_id":28744,
"price":270000,
"chain_link_id":"EA5AB156-5B06-468C-A210-8AA8570C80AE",
"is_locked":false,
"full_address":"53 HALL AVENUE, NORFOLK, NE5 5PG",
"address_street_name":"53 HALL AVENUE",
"address_area":"NORFOLK",
"address_postal_code":"NE5 5PG"
},
"relationships":{
"milestone_states":{
"data":{
"type":"milestone_states",
"id":"1461063"
}
}
}
},
"included":[{
"type":"milestone_states",
"id":"1461063",
"attributes":{
"SSTC":{
"concern":null,
"heading":null,
"status":null,
"state":"ok"
},
"Draft Contracts Prepared":{
"concern":null,
"heading":null,
"status":null,
"state":"none"
},
"Searches Ordered":{
"concern":"Check with conveyancer to confirm searches have been ordered",
"status":"warning",
"heading":"No Search Found",
"state":"requires_attention"
},
"Searches Expected":{
"concern":"Searches Ordered needs to be completed before they can be expected",
"heading":null,
"status":null,
"state":"none"
},
"Funding Applied":{
"concern":"Invite the purchaser to unlock funding information",
"status":"locked",
"state":"actionable",
"heading":null
},
"Enquiries Opened":{
"concern":null,
"heading":null,
"status":null,
"state":"none"
},
"Enquiries Closed":{
"concern":"Enquiries resolved",
"state":"ok",
"heading":null,
"status":null
},
"Proposed Completion":{
"concern":null,
"heading":null,
"status":null,
"state":"none"
},
"LandReg Completion":{
"state":"none",
"concern":null,
"heading":null,
"status":null
},
"LastLandRegCompletion":{
"concern":null,
"heading":null,
"status":null,
"state":"none"
},
"Survey Booked For":{
"state":"none",
"concern":null,
"heading":null,
"status":null
},
"Survey Satisfactory":{
"concern":null,
"heading":null,
"status":null,
"state":"none"
},
}
}]
}
API References https://developers.viewmychain.com/api/v1/listing/{listing}/milestone/state https://developers.viewmychain.com/api/v1/listing/{listing}