Instruction service

Introducer Supplier

This service contains the following methods:

GET /instruction/{tmpReference} Introducer Supplier
GET /instruction/introducer/{reference} Introducer
GET /instruction/supplier/{reference} Supplier
GET /instruction/{tmpReference}/file/{fileName} Introducer Supplier
PUT /instruction/{tmpReference}/introducerreferences Introducer
PUT /instruction/{tmpReference}/supplierreferences Supplier

There are two methods to retrieve an instruction. The first of these will use the TMP reference to retrieve an Instruction and can be used by both Introducers and Suppliers. The second can only be used by Introducers and will use their unique references. See Instruction references for more information.

Both methods return the same results which is full details of the Instruction. This will include all milestones and notes.

Both methods will return a 404 Not Found response if the instruction does not exist or you do not have access to it.

Get Instruction

GET /instruction/{tmpReference} Introducer Supplier

This method will use the TMP reference to retrieve the Instruction.

Get Instruction using introducer reference

GET /instruction/introducer/{reference} Introducer
GET /instruction/introducer/{reference}?caseIndex={caseIndex} Introducer

This method will use the Introducer references to retrieve the Instruction. Some instructions may not have an Introducer reference. However, if they have either a IntroducerIntegrationReference or IntroducerCustomerReference this can be specified here. If you need to access a specific case index then specify it using the query string.

INFO

Multiple cases are not currently supported. Use CaseIndex=1 or do not specify.

See Key concepts for more information.

Get Instruction using supplier reference

GET /instruction/supplier/{reference} Introducer
GET /instruction/supplier/{reference}?caseIndex={caseIndex} Supplier

This method will use the Supplier references to retrieve the Instruction. Some instructions may not have an Introducer reference. However, if they have either a SupplierIntegrationReference or SupplierCustomerReference this can be specified here. If you need to access a specific case index then specify it using the query string.

INFO

Multiple cases are not currently supported. Use CaseIndex=1 or do not specify.

See Key concepts for more information.

Update Introducer References

PUT /instruction/{tmpReference}/introducerreferences Introducer

This method will allow an Introducer to specify the references used for a case. It can only be accessed using the TMP reference for the instruction.

The payload for this method is:

{
  "uniqueCustomerReference": "C-299AJJ",
  "uniqueIntegrationReference": "INT-28828"
}

It is not possible to update references for a read only case.

Update Supplier References

PUT /instruction/{tmpReference}/supplierreferences Supplier

This method will allow a Supplier to specify the references used for a case. It can only be accessed using the TMP reference for the instruction.

The payload for this method is:

{
  "uniqueCustomerReference": "F-300AUR",
  "uniqueIntegrationReference": "SUP-28828"
}

It is not possible to update references for a read only case.

See Key concepts for more information about references.

These references can be at most 30 characters long and must be unique.

Objects

Object: Instruction

An Instruction is made up of the following properties

Property	Description
TMPReference	Our reference for an Instruction. See Key concepts.
TMPCustomerReference	Our reference for an Instruction to display to customers. See Key concepts.
CaseIndex	The case index - will usually be 1. See Key concepts.
CaseStatusCode	A code for the status that the case is currently at, e.g. APPOINTMENTBOOKED or COMPLETED.
IsOnHold	Whether the case is currently On Hold. This is an indicator that the case was requested to be put On Hold, however operations can still proceed.
ProductCode	The product that this case is for.
Attributes	A dictionary of attributes (e.g. for a Help to Buy Valuation an attribute of Rewrite may be present). The value portion will be null and used in future development. Use the Data service using the data set code CASEATTRIBUTES to retrieve the meaning of the code.
SupplierName	If the case has been allocated and accepted by a supplier.
Timestamps	A dictionary of key timestamps for the case, e.g. Accepted, Appointment.
Fee	A dictionary containing fee information.
Milestones	Details of milestones for the case.
IsVisibleToCustomers	Whether the instruction is visible (online) to the customers listed.
PrimaryCustomer	Who the primary customer is. See Key concepts.
CustomerNames	A string with the customer names (for display purposes).
Customers	Who the customers are.
HasUnreadNotes	Whether there are unread notes. See Notes service.
Notes	Notes about the case.
Files	Files related to the case.
Property	Details of the Property involved with the case.
OtherInformation	Further information about the case.
AllowedOperations	A list of operations that are allowed to happen by the current user.
Configuration	Configuration to take account of when using this Instruction. See Key concepts.

Case Status Codes

For Introducers the following codes may be returned

NEW
REFERRED
ORDERED
ALLOCATED
APPOINTMENTBOOKED
APPOINTMENTCOMPLETED
COMPLETED
CANCELLED
REJECTED

For Suppliers the following codes may be returned

ALLOCATED
ACCEPTED
APPOINTMENTBOOKED
APPOINTMENTCOMPLETED
COMPLETED

Timestamps

Depending on the state of the case, the following timestamps may be available (e.g. if an APPOINTMENT hasn't been booked that date will not be available):

Name	Description	Introducer	Supplier
QUOTED	When the instruction was first quoted by the Introducer	Yes	No
CREATED	When the instruction was referred by the Introducer	Yes	No
ORDERED	When the instruction was ordered by the Introducer or Customer	Yes	No
ASSIGNED	When the instruction was assigned to the Supplier	No	Yes
OFFEREXPIRY	Only available when the instruction is assigned. Represents the date that the offer will expiry.	No	Yes
ACCEPTED	When the instruction was accepted by the Supplier	No	Yes
APPOINTMENT	When the appointment is booked for	Yes	Yes
EXPECTEDREPORTDATE	When the report is expected	Yes	Yes
COMPLETED	When the case was completed	Yes	Yes
CANCELLED	When the case was cancelled	Yes	No

INFO

When a case is cancelled the supplier no longer has access to the information.

Fee

For Introducer two fees will be listed in this Dictionary

TOTALFEEINCLVAT - The total fee charged to the customer. If this is not present then we are unable to calculate a fee (i.e. price on application). This is generally applicable for specialist reports.
YOURFEEINCLVAT - Your part of the fee.

If the fee (or portion of the fee) is still to be paid it will be listed under TOTALDUEINCLVAT. This value will not be present for cases at the New status.

For Suppliers only YOURFEEINCLVAT will be provided.

Other information

The following information may be available for Introducers:

Name	Description
INTRODUCERCUSTOMERREFERENCE	The code presented to the customer by the introducer. See Key concepts
INTRODUCERINTEGRATIONREFERENCE	The code used for integration by the introducer. See Key concepts
ISPRICEONAPPLICATION	Set to `true` when we are unable to automatically calculate a fee.
TERMSANDCONDITIONSSENT	Set to `true` when Terms and Conditions have been sent and the supplier is awaiting their return. Is only shown when the case is at the ALLOCATED status.
TERMSANDCONDITIONSRECEIVED	Set to `true` when Terms and Conditions have been received. Is only shown when the case is at the ALLOCATED status.
READONLY	Set to `true` if the case is read only. It is only shown when the case is Read Only.

The following information may be available for Suppliers:

Name	Description
SUPPLIERCUSTOMERREFERENCE	The code presented to the customer by the supplier. See Key concepts
SUPPLIERINTEGRATIONREFERENCE	The code used for integration by the supplier. See Key concepts
TERMSANDCONDITIONSSENT	Set to `true` when Terms and Conditions have been sent and the supplier is awaiting their return. Is only shown when at the ACCEPTED status.
TERMSANDCONDITIONSRECEIVED	Set to `true` when Terms and Conditions have been received. Is only shown when at the ACCEPTED status.
READONLY	Set to `true` if the case is read only. It is only shown when the case is Read Only.

Allowed operations

The following codes for operations may be returned. These will be dependent on the status of the instruction and configuration of the introducer, supplier or user. For example an Introducer cannot Book an Appointment but the case may be in a status that the Supplier can.

ACCEPT Supplier
DECLINE Supplier
BOOKAPPOINTMENT Supplier
REBOOKAPPOINTMENT Supplier
CONFIRMAPPOINTMENTCOMPLETED Supplier
CONFIRMAPPOINTMENTUNCOMPLETED Supplier
UPLOADREPORT Supplier
REPLACEREPORT Supplier
- This depends on configuration and if allowed can only be done within a short time interval after the original upload.
DOWNLOADREPORT Introducer Supplier
- Not all Introducers will be able to download a report.
COMPLETECASE Supplier
- It may not be required to upload a report to complete a case.
ADDNOTE Introducer Supplier
MARKNOTESASREAD Introducer Supplier

Object: InstructionMilestone

The Milestones property is a list of this object.

Property	Description
MilestoneCode	The milestone, e.g. APPOINTMENT
CompletedTimestamp	When the milestone was completed. Set to `null` if not completed.
OrganisationTypeCode	The type of organisation who completed the milestone, usually TMP or Supplier, but future changes might also include Introducer or Customer.
OrganisationName	Name of organisation who completed the milestone.
PersonName	Name of the person who completed the milestone. Will not be set for TMP.
CurrentState	Description of the current state.
ExpectedTimestamp	When the milestone was or is expected to be completed.
Data	Dictionary containing additional data.

The milestones returned for each type of user are listed below.

Milestone - ASSIGNED Supplier

Property	Description
MilestoneCode	ASSIGNED
CompletedTimestamp	This is the timestamp it was assigned and this milestone is complete when it is assigned.
OrganisationTypeCode	Will be set to TMP.
OrganisationName	Will be set to "The Moving Portal" or "IMyHome".
PersonName	Empty
CurrentState	Will be set to WAITING when the supplier has still to accept OVERDUE when the supplier has still to accept and it beyond the expected timestamp ACCEPTED when the supplier has accepted
ExpectedTimestamp	When the case is offered to - after which it may be reallocated.
Data	None.

This milestone will always have data and always be marked as complete - it is the first milestone that makes the instruction visible to the Supplier.

Milestone - ACCEPTED Supplier

Property	Description
MilestoneCode	ACCEPTED
CompletedTimestamp	The timestamp of when the case was Accepted - if accepted, otherwise `null`.
OrganisationTypeCode	Type of user who Accepted the case, either Supplier or TMP.
OrganisationName	Name of the organisation who accepted the case.
PersonName	For TMP this will be empty otherwise name of the person at the Supplier who accepted the case.
CurrentState	Set to COMPLETED when the case has been accepted.
ExpectedTimestamp	Whilst the case has not been accepted will have the timestamp of when the case is offered to - after which it may be reallocated. After acceptance it will be `null`.
Data	YourFeeInclVAT containing your fee that the case was accepted at.

Milestone - APPOINTMENT Supplier

Property	Description
MilestoneCode	APPOINTMENT
CompletedTimestamp	The timestamp of when the appointment has booked - if booked, otherwise `null`.
OrganisationTypeCode	Type of user who Accepted the case, either Supplier or TMP.
OrganisationName	Name of the organisation who booked the appointment.
PersonName	For TMP this will be empty otherwise name of the person at the Supplier who booked the appointment.
CurrentState	Set to BOOKED when the appointment has been booked, CONFIRMCOMPLETED if the appointment was subsequently marked as being completed, COMPLETED if the case has been completed.
ExpectedTimestamp	When the appointment was booked for.
Data	TIMESLOTCODE will have the code for when (i.e. Morning or Afternoon) if available. Use the Data service using the data set code APPOINTMENTTIMES to retrieve the meaning of the code. If the appointment was marked as being completed the following may be set: ActualAppointmentDate will be if the date differs from the original appointment date ExpectedReportDate will contain the date that the report should be available

Milestone - COMPLETED Supplier

Property	Description
MilestoneCode	COMPLETED
CompletedTimestamp	The timestamp of when the case was Completed - if complete, otherwise `null`.
OrganisationTypeCode	Type of user who Completed the case, either Supplier or TMP.
OrganisationName	Name of the organisation who completed the case.
PersonName	For TMP this will be empty otherwise name of the person at the Supplier who completed the case.
CurrentState	Set to COMPLETED when the case has been completed. If the appointment has been confirmed completed will be set to APPOINTMENTCONFIRMEDCOMPLETED.
ExpectedTimestamp	If the appointment has been confirmed completed will be set to the date the report is expected, otherwise `null`.
Data	None.

Milestone - ALLOCATED Introducer

Property	Description
MilestoneCode	ALLOCATED
CompletedTimestamp	The timestamp of when the case was allocated to a supplier - otherwise `null`.
OrganisationTypeCode	Empty.
OrganisationName	Empty.
PersonName	Empty.
CurrentState	Empty.
ExpectedTimestamp	`null`
Data	SupplierName name of the supplier.

Milestone - APPOINTMENT Introducer

Property	Description
MilestoneCode	APPOINTMENT
CompletedTimestamp	The timestamp of when the appointment has booked - if booked, otherwise `null`.
OrganisationTypeCode	Type of user who Accepted the case, either Supplier or TMP.
OrganisationName	Name of the organisation who booked the appointment.
PersonName	For TMP this will be empty otherwise name of the person at the Supplier who booked the appointment.
CurrentState	Set to BOOKED when the appointment has been booked, CONFIRMCOMPLETED if the appointment was subsequently marked as being completed, COMPLETED if the case has been completed.
ExpectedTimestamp	When the appointment was booked for.
Data	TIMESLOTCODE will have the code for when (i.e. Morning or Afternoon) if available. Use the Data service using the data set code APPOINTMENTTIMES to retrieve the meaning of the code. If the appointment was marked as being completed the following may be set: ActualAppointmentDate will be if the date differs from the original appointment date ExpectedReportDate will contain the date that the report should be available

Milestone - COMPLETED Introducer

If the case has been Cancelled then this milestone will not appear.

Property	Description
MilestoneCode	COMPLETED
CompletedTimestamp	The timestamp of when the case was Completed - if complete, otherwise `null`.
OrganisationTypeCode	Type of user who Completed the case, either Supplier or TMP.
OrganisationName	Name of the organisation who completed the case.
PersonName	For TMP this will be empty otherwise name of the person at the Supplier who completed the case.
CurrentState	Set to COMPLETED when the case has been completed. If the appointment has been confirmed completed will be set to APPOINTMENTCONFIRMEDCOMPLETED.
ExpectedTimestamp	If the appointment has been confirmed completed will be set to the date the report is expected, otherwise `null`.
Data	None.

Milestone - CANCELLED Introducer

If the case has been Completed then this milestone will not appear.

Property	Description
MilestoneCode	CANCELLED
CompletedTimestamp	The timestamp of when the case was Cancelled.
OrganisationTypeCode	Type of user who Completed the case - TMP.
OrganisationName	Name of the organisation who completed the case The Moving Portal or IMyHome.
PersonName	Empty.
CurrentState	Empty
ExpectedTimestamp	`null`
Data	ReasonCode and if using Other reason also OtherReason. Lookup data set CancelCaseReasons for values.

Object: Customer

These are the customers for the Instruction. Please review details about the Primary customer when the customers listed in this object are the clients of the primary customer. This is typically when the Primary customer is a lender who has instructed a survey for their customers.

Property	Description
EmailAddress	The email address of the customer. This will not always be populated.
Title	The title of the customer, e.g. Mr, Mrs, Miss etc
FirstName	The first name of the customer
LastName	The last name of the customer
TelephoneNumber	The telephone number of the customer
ReceiveSMS	Whether the customer may receive SMS notifications. Note that even if this is set, the customer may not receive SMS messages

INFO

At least one customer should have an email address.

Object: InstructionNote

The InstructionNote object contains details of Notes that have been made visible to the user.

Property	Description
CaseNoteReference	For a note created by your party this is your reference. It will be empty for other parties.
CreateByOrganisationName	The organiation name of who created the Note.
CreateByOrganisationTypeCode	Set to TMP, Supplier, Introducer or Customer.
PersonName	Who created the Note. Notes created by TMP will not have this information.
VisibleTo	List of parties the note is visible to. Possible vaules are Supplier, Introducer or Customer. TMP will note be listed.
ReadTimestamps	Dictionary of when the notes have been read by the parties. If a party has not read the note then they will not be in this property.
ReadTimestamp	Has the note been read by the current organisation. Will be set to `null` if it hasn't been read.
NoteBody	The note.
IsVisibleToCustomer	Whether the note created is visible to the Customer.
Sequence	The sequence of the note. These numbers should be used to order the notes, but they will not be consecutive (i.e. their may be gaps)

INFO

Notes created by Introducers are not normally visible to Suppliers.

Notes created by Suppliers are not normally visible to Introducers.

Setting for Introducer notes visible.

Object: InstructionFile

The InstructionFile object contains details of each file stored against the Instruction.

Property	Description
FileTypeCode	The type of file.
FileFormatCode	The format of the file. Only valid value is currently `PDF`.
FileReference	A reference for the file.
CreatedTimestamp	Then the file was created.

Valid values for FileTypeCode are:

Type	Description
InstructionReportFromSupplier	A report from a supplier.

INFO

Files may not be available to the Introducer. This is dependant on configuration setup for each firm or per instruction. Please check the configuration property of the instruction for the CanViewReport item.

Object: InstructionProperty

The InstructionProperty object returned here contains both the codes used when creating a quote/referral (by Introducers) and their descriptions. It also contains the elements of addresses and access details as well their descriptions. This allows them to be displayed without you needing to write code.

Property	Description
PropertyValueOrPurchasePrice	The property value or purchase price.
PropertyValueTierCode	The code used for the property value tier, e.g. 650KTO700K
PropertyValueTierDescription	A description of the property value tier, e.g. to £700,000
PropertyTypeCode	The code used for the type of property, e.g. FLAT
PropertyTypeDescription	The description for the type of property, e.g. Flat
PropertyAgeCode	A code used for the age of the property, e.g. TENTOFIFTYYEARS
PropertyAgeDescription	The description for the type of property, e.g. 10 to 50 years
PropertyAddressDescription	A description of the property address
PropertyAddress	The property address in it's elements
CorrespondenceAddressDescription	A description of the correspondence address
CorrespondenceAddress	The correspondence address in it's elements
AccessDetailsDescription	A description of the Access Details
AccessDetails	The access details in it's elements

Get File

GET /instruction/{tmpReference}/file/{fileName} Introducer

This method will use the TMP reference and fileName to retrieve the relevant file. The filename can be found by retrieving the instruction and using the files property.

If the file does not exist or you do not have access to it you will receive a 404 Not Found response.

The file is downloaded as a byte array. Typical code to retrieve the file might be:

C#
var httpClient = httpClientFactory.Create();
// Add headers for authentication
var url = "URL HERE";

using var response = await httpClient.GetAsync(url);
if (response.StatusCode == System.Net.HttpStatusCode.OK)
{
    var file = await response.Content.ReadAsByteArrayAsync();
    var savedFileNameName = "downloaded.pdf";
    File.WriteAllBytes(savedFileName, file);
}
else
{
    Console.WriteLine("Failed to retrieve file");
    Console.WriteLine($"Response Status Code {response.StatusCode}");
    var errors = await response.Content.ReadAsStringAsync();
    Console.WriteLine($"Errors: {errors}");
}

Example Instruction object

An example of a returned instruction is below:

TODO

Needs updating with final version

{
  "tmpReference": "TMP102852",
  "tmpCustomerReference": "TMP102852",
  "caseIndex": 1,
  "caseStatusCode": "CANCELLED",
  "isOnHold": false,
  "productCode": "RICSL2SURVEY",
  "supplierName": null,
  "timestamps": {
    "QUOTED": "2023-06-23T09:14:35.2473801Z",
    "CREATED": "2023-06-23T09:17:07.3838175Z",
    "ORDERED": "2023-06-23T09:18:47.2238795Z",
    "CANCELLED": "2023-07-03T13:04:37.6330035Z"
  },
  "fee": {
    "TOTALFEEINCLVAT": 885.00,
    "YOURFEEINCLVAT": 125.00
  },
  "milestones": [
    {
      "milestoneCode": "ALLOCATED",
      "completedTimestamp": null,
      "organisationTypeCode": null,
      "organisationName": null,
      "personName": null,
      "currentState": null,
      "expectedTimestamp": null,
      "data": {}
    },
    {
      "milestoneCode": "APPOINTMENT",
      "completedTimestamp": null,
      "organisationTypeCode": null,
      "organisationName": null,
      "personName": null,
      "currentState": null,
      "expectedTimestamp": null,
      "data": {}
    },
    {
      "milestoneCode": "CANCELLED",
      "completedTimestamp": "2023-07-03T13:04:37.6330035Z",
      "organisationTypeCode": "TMP",
      "organisationName": "The Moving Portal",
      "personName": "",
      "currentState": "",
      "expectedTimestamp": null,
      "data": {
        "ReasonCode": "DATENOTSUITABLE"
      }
    }
  ],
  "isVisibleToCustomers": true,
  "primaryCustomer": {},
  "customerNames": "Colin Montgomery",
  "customers": [
    {
      "emailAddress": "colinmontgomery@themovingportal.dev",
      "title": "",
      "firstName": "Colin",
      "lastName": "Montgomery",
      "telephoneNumber": "01234 121212",
      "receiveSMS": false
    }
  ],
  "hasUnreadNotes": true,
  "notes": [
    {
      "caseNoteReference": null,
      "createdTimestamp": "2023-06-23T09:19:20.024475Z",
      "createdByOrganisationName": "TMP Customers",
      "createdByOrganisationTypeCode": "CustomerProxy",
      "personName": "Colin Montgomery",
      "readTimestamp": null,
      "visibleTo": [
        "Customer",
        "Introducer"
      ],
      "readTimestamps": {},
      "noteBody": "Test"
    }
  ],
  "files": [],
  "property": {
    "propertyValueOrPurchasePrice": 389000.00,
    "propertyValueTierCode": "350KTO400K",
    "propertyValueTierDescription": "to £400,000",
    "propertyTypeCode": "TERRACED",
    "propertyTypeDescription": "Terraced",
    "propertyAgeCode": "LESSTHANTENYEARS",
    "propertyAgeDescription": "Less than 10 years",
    "propertyAddressDescription": "32 Watermarque, 100 Browning Street, Birmingham, West Midlands, B16 8GY, England",
    "propertyAddress": {
      "addressFormatCode": "DEFAULT",
      "addressLine1": "32 Watermarque",
      "addressLine2": "100 Browning Street",
      "addressLine3": "Birmingham",
      "addressLine4": "West Midlands",
      "postcode": "B16 8GY",
      "countryCode": "GB"
    },
    "correspondenceAddressDescription": "32 Watermarque, 100 Browning Street, Birmingham, West Midlands, B16 8GY, England",
    "correspondenceAddress": {
      "addressFormatCode": "DEFAULT",
      "addressLine1": "32 Watermarque",
      "addressLine2": "100 Browning Street",
      "addressLine3": "Birmingham",
      "addressLine4": "West Midlands",
      "postcode": "B16 8GY",
      "countryCode": "GB"
    },
    "accessDetailsDescription": "Vendor: Lucy Day (01421282811 - lucyday@veritas.co.uk)",
    "accessDetails": {
      "accessTypeCode": "VENDOR",
      "firmName": "N/A",
      "emailAddress": "lucyday@veritas.co.uk",
      "contactName": "Lucy Day",
      "telephoneNumber": "01421282811"
    }
  },
  "otherInformation": {},
  "allowedOperations": [
    "ADDNOTE",
    "MARKNOTESASREAD"
  ],
  "configuration": {
    "CanViewReport": true
  }
}