Instructions search service

Introducer Supplier

This service contains the following method:

GET /instructions Introducer Supplier

The aim of this method is to search the instructions primarily to display the results before extracting more information about each instruction. The amount of detail is much less than loading a full instruction, e.g. there are no notes, milestones but there is an indication of unread notes and some key dates.

Search instructions

GET /instructions Introducer Supplier

This method will search for instructions. The payload for this method is

{
  "pageNumber": 1,
  "pageSize": 10,
  "tmpReference": "",
  "productCode": "",
  "partialCustomerName": "",
  "partialPostcode": "",
  "partialCustomerName": "",
  "dateSearchCode": "Created",
  "dateFromTimestamp": null,
  "dateToTimestamp": null,
  "hasUnreadNotes": null,
  "isOnHold": null,
  "sortColumnName": "Created",
  "sortAscending": true
}

The properties of this payload are:

Property	Description
pageNumber	The page number to return. Set to 1 for first page.
pageSize	The number of results to return. From 1 to 50.
tmpReference	The TMP reference. Can be empty.
productCode	The product. Can be empty.
partialCustomerName	Part of the customer name. Can be empty.
partialPostcode	Part of postcode, typically the first 3 or 4 characters. Can be empty.
searchTypeCode	The type of search. See below.
dateSearchCode	What dates to search on. Valid values are Appoinment, ReportDue or Created.
dateFromTimestamp	Start date. Set to `null` to not specify.
dateToTimestamp	To date. Set to `null` to not specify.
isOnHold	Whether the case is on hold. Set to null to find cases both on hold and not on hold.
sortColumnName	The column to sort by. Valid values are TMPReference, Product, Created, Appointment.
sortAscending	Whether results are in ascending order of the `sortColumnName`.

Search type code

The search type can be set to the case status code or a specialised search code.

Introducers

`searchTypeCode`	Description
NEW	Cases at New status.
REFERRED	Cases at Referred status. Will include Referrals and Ordered cases before they are assigned to a surveyor.
ALLOCATED	Cases Assigned to a surveyor.
APPOINTMENTBOOKED	Cases at Appointment booked status.
APPOINTMENTCOMPLETED	Cases at Appointment completed status.
COMPLETED	Cases at Completed status.
CANCELLED	Cases at Cancelled status.

If not specified will return all active cases, i.e. not Completed or Cancelled.

Suppliers

`searchTypeCode`	Description
ALLOCATED	Cases allocated to a surveyor (but not accepted).
ACCEPTED	Cases at Accepted status.
APPOINTMENTBOOKED	Cases at Appointment booked status.
APPOINTMENTCOMPLETED	Cases at Appointment completed status.
COMPLETED	Cases at Completed status.
OVERDUEACCEPTANCE	Cases that have been allocated but are overdue for acceptance.
UNCONFIRMEDAPPOINTMENTS	Cases that have an appointment booked which should have taken place but have not been confirmed to be completed.

If not specified will return all active cases, i.e. not Completed.

Validation

pageNumber must be greater than or equal to 1. If a page number is specified for which there are no results then a validation error will not be raised. The result object will return the number of results from which you can calculate how many pages there are.
pageSize must be between 1 and 50.
tmpReference must be a valid TMP reference. Can be empty.
productCode must be a valid Product code. Can be empty.
searchTypeCode If provided must be as specified as above. Can be empty.
partialCustomerName can have a length of up to 20 characters. Can be empty.
partialPostcode can have a length of up to 8 characters. Can be empty.
dateSearchCode must be set to one of Appoinment, ReportDue or Created.
sortColumnName can be set to one of TMPReference, Product, Created, Appointment.

INFO

The following is not yet supported for instruction search

Searching by Introducer references or returning the references.
Showing to Introducers cases that have been ordered - they will currently be shown at the Referred status.
It is not possible to search by Case Index. Even if specified in the TMPReference it will be ignored. At this time, this is not an issue as each instruction only has one case.

Search results

A simple search results return could be

{
  "searchResults": [
    {
      "tmpReference": "TMP103226",
      "tmpCustomerReference": "TMP103226",
      "caseIndex": 0,
      "caseStatusCode": "COMPLETED",
      "isOnHold": false,
      "productCode": "RICSL2SURVEY",
      "supplierName": "Allcott Associates LLP",
      "hasUnreadNotes": false,
      "customerNames": "Tina Barton",
      "propertyPostcode": "B18 6EN",
      "otherInformation": {
        "INTRODUCERCUSTOMERREFERENCE": "C9019287",
        "INTRODUCERINTEGRATIONREFERENCE": "I92-1992"
      },
      "timestamps": {
        "CREATED": "2024-05-18T12:06:29.4649286Z",
        "BOOKEDAPPOINTMENT": "2024-05-19T09:00:00Z"
      }
    },
    {
      "tmpReference": "TMP103128",
      "tmpCustomerReference": "TMP103128",
      "caseIndex": 0,
      "caseStatusCode": "COMPLETED",
      "isOnHold": false,
      "productCode": "RICSL2SURVEYVALUATION",
      "supplierName": "Allcott Associates LLP",
      "hasUnreadNotes": false,
      "customerNames": "Fiona Law",
      "propertyPostcode": "B18 6EN",
      "otherInformation": {
        "INTRODUCERCUSTOMERREFERENCE": "C9019281",
        "INTRODUCERINTEGRATIONREFERENCE": "I92-1927"
      },
      "timestamps": {
        "CREATED": "2024-01-15T14:20:42.3247228Z",
        "BOOKEDAPPOINTMENT": "2024-03-22T09:00:00Z"
      }
    }
  ],
  "numberOfResults": 43,
  "pageSize": 2,
  "currentPage": 1
}

There are integer values for

currentPage - the page number being returned.
pageSize - the size of the page. Will always be the size of the page and not the number of results returned in the searchResults property.
numberOfResults - the total number of results (for all pages).

And there is a searchResults property which is a list of results, e.g.

{
  "tmpReference": "TMP103128",
  "tmpCustomerReference": "TMP103128",
  "caseIndex": 1,
  "caseStatusCode": "COMPLETED",
  "isOnHold": false,
  "productCode": "RICSL2SURVEYVALUATION",
  "supplierName": "Allcott Associates LLP",
  "hasUnreadNotes": false,
  "customerNames": "Fiona Law",
  "propertyPostcode": "B18 6EN",
  "otherInformation": {
    "INTRODUCERCUSTOMERREFERENCE": "C9019287",
    "INTRODUCERINTEGRATIONREFERENCE": "I92-1992"
  },
  "timestamps": {
    "CREATED": "2024-01-15T14:20:42.3247228Z",
    "BOOKEDAPPOINTMENT": "2024-03-22T09:00:00Z"
  }
}

The properties of this return are:

Property	Description
TMPReference	The TMP Reference. See (References)(/key-concepts#instruction-references).
TMPCustomerReference	The TMP Reference to show to customers. See (References)(/key-concepts#instruction-references).
CaseIndex	The case index - typically always 1. See (References)(/key-concepts#instruction-references).
CaseStatusCode	The status of the case. See (Introducer journey)(/key-concepts#introducer-journey) or (Supplier journey)(/key-concepts#supplier-journey).
IsOnHold	Whether the case is on hold.
ProductCode	The code for the product.
SupplierName	The name of the supplier or `null` if not set.
HasUnreadNotes	Whether the case has unread notes. You should load the instruction to get the notes then mark the notes as read.
CustomerNames	The names of the customer - for display.
PropertyPostcode	The postcode of the property - for display.
OtherInformation	A dictionary of other information returned (e.g. introducer references).
Timestamps	A dictionary of key timestamps.

Other information

The otherInformation property will have the following:

Introducers

INTRODUCERCUSTOMERREFERENCE - if set, the customer reference used by the introducer and will be shown to them on our portal.
INTRODUCERINTEGRATIONREFERENCE - if set, the integration reference used by the introducer. This is shown to TMP users only.
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.

Suppliers

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 ACCEPTED status.
TERMSANDCONDITIONSRECEIVED - Set to true when Terms and Conditions have been received. Is only shown when the case is at the ACCEPTED status.
READONLY - Set to true if the case is read only. It is only shown when the case is Read Only.

Timestamps

The timestamps property will have the following (if applicable):

Introducers

CREATED - the timestamp the instruction was created.
BOOKEDAPPOINTMENT - when then appointment is.
EXPECTEDREPORTDATE - when the report is expected.

Suppliers

ALLOCATIONEXPIRY - when the offer of the case will expire.
BOOKEDAPPOINTMENT - when then appointment is.
EXPECTEDREPORTDATE - when the report is expected.

INFO

The timestamps returned have less detail than loading the full instruction.

As an example:

for Introducer does not return when the quote was created, the order was created, when case was assigned, completed or cancelled.
for Supplier does not return when the case was accepted.