Instruction notification service

Introducer Supplier

This service is used to retrieve notifications about changes or operations performed on Instructions.

The following methods are in this service:

GET /instructions/notifications
GET /instruction/{reference}/notifications
GET /instruction/{reference}/notifications?timestamp={fromTimestamp}
PUT /instruction/{reference}/processed?timestamp={toTimestamp}

A typical strategy for using this service might be:

Regularly call the method to retrieve a list of instructions with notifications GET /instructions/notifications
Loop through the instructions listed that need to be processed. Approaches might be:
- Process the first entry (see below) and then start the process again from the first step above.
- Or, add each entry to a queue that is processed by a separate process.

Polling the service

We have made a decision to not implement a webhook at this time, although we may implement this in the future. It is likely that we would implement a call to a method which triggers your process to consume the notifications as required.

The length of the polling interval would be a consideration of how many cases you are expecting and how close to the event occuring do you need to be updated. We would expect that polling every hour would meet most requirements. Polling every day to update your records may be sufficient if you are only interested in the overall status of an instruction.

A strategy to process notifications for an instruction might be:

Calling the method to retrieve the unprocessed notifications for an instruction with the method GET /instruction/{reference}/notifications
Loop through each notification for the instruction and process it. There is some rationalisation that can be done (e.g. multiple notes or updates of customer/property will require synchronising your data, so only need to be done once).
Once you have processed all the notifications call the method to mark that instruction as processed using the method PUT /instruction/{reference}/processed?timestamp={toTimestamp}

You should decide what notifications you are interested in. There may be notifications that you do not need to work with (e.g. updates to the property details).

An alternative strategy is use the method to get a list of notifications, then load each instruction and synchronise the data that you are interested in, without processing the individual notifications. For example an introducer may only be interested in

Current case status
Appointment date
Notes
Fee changes

Rather than processing the list of notifications you retrieve the full instruction, synchronsing the data that you need.

One other strategy that is in use is rather than using this service, is to use the Instructions search service on a regular poll. This will return some basic details about the instruction such as the current case status (with up to 50 results per page).

Testing

In order for you to test this service it is necessary to move an instruction through the process, e.g.

For an introducer you would create a direct referral or instruction from quote, but then the operations that need to be performed are admin ones by TMP, i.e.
- have it accepted (or rejected)
- take payment (if not being invoiced)
- have it assigned to a supplier
- book an appointment
- upload a report
For a supplier you would need a test instruction created that you can work on and assigned to you

Plus operations such as

put a case on hold and take it off
any fee changes
any change of product
cancel a case
etc.

For this reason in the TESTING environment only we have created an Integration Developer Console in our main portal. This console will allow you to process an instruction through the process.

Please see the section on Testing for more information.

New notifications

New notifications types may be added that your integration may not support (e.g. new functionality). These notifications may show as empty (i.e. have no code to identify it). Ensure that your integration takes this into account.

Deletion of notifications

Notifications will be removed three months after an instruction is completed or cancelled.

Get instructions with notifications

GET /instructions/notifications

This method will retrieve a list of instructions for which notifications are available. For each instruction the following information will be provided

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.
NumberOfNotifications	The number of notifications for this case.
FirstNotificationTimestamp	The first notification for this case.
LastNotificationTimestamp	The last notification for this case.
LatestCreatedTimestamp	The timestamp the latest notification was written. See warning below about timestamps.
OtherInformation	A dictionary of other information returned (e.g. introducer references).
HasUnreadNotes	Whether there are unread notes. See Notes service.

Timestamps

When you retrieve notifications there are two timestamps

Notification timestamp
Created timestamp

The notification timestamp is the time that the event being notified happened. The created timestamp is the time that the event being notified was stored. These should be similar (with the created timestamp after the notification timestamp). You will use the created timestamp when marking notifications having been processed. This will allow us to add notifications retrospectively (if required), e.g. if there are system issues.

A typical return from this method would be:

{
  "numberOfInstructions": 2,
  "instructions": [
    {
      "tmpReference": "TMP103718",
      "tmpCustomerReference": "TMP103718",
      "caseIndex": 1,
      "caseStatusCode": "ALLOCATED",
      "numberOfNotifications": 4,
      "firstNotificationTimestamp": "2025-02-19T15:18:57.8960592Z",
      "lastNotificationTimestamp": "2025-02-24T11:00:19.466668Z",
      "latestCreatedTimestamp": "2025-02-24T11:00:19.4685624Z",
      "otherInformation": {
        "INTRODUCERCUSTOMERREFERENCE": "TMP103718-INT-CUST",
        "INTRODUCERINTEGRATIONREFERENCE": "TMP103718-INT-INT"
      },
      "hasUnreadNotes": true
    },
    {
      "tmpReference": "TMP103785",
      "tmpCustomerReference": "TMP103785",
      "caseIndex": 1,
      "caseStatusCode": "COMPLETED",
      "numberOfNotifications": 6,
      "firstNotificationTimestamp": "2025-02-19T15:21:56.6532239Z",
      "lastNotificationTimestamp": "2025-02-19T15:24:58.2485814Z",
      "latestCreatedTimestamp": "2025-02-19T15:24:58.252094Z",
      "otherInformation": {},
      "hasUnreadNotes": false
    }
  ]
}

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.

Suppliers

SUPPLIERCUSTOMERREFERENCE - if set, the customer reference used by the supplier and will be shown to them on our portal.
SUPPLIERINTEGRATIONREFERENCE - if set, the integration reference used by the supplier. 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 ACCEPTED status.
TERMSANDCONDITIONSRECEIVED - Set to true when Terms and Conditions have been received. Is only shown when the case is at the ACCEPTED status.

Retrieve notifications for an instruction

GET /instruction/{reference}/notifications
GET /instruction/{reference}/notifications?timestamp={fromTimestamp}

This method will return unprocessed notifications for an instruction.

You can optionally specify a timestamp to retrieve all notifications after this date (but NOT including). This will include any notifications already processed.

A typical return from this method would be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "numberOfNotifications": 1,
  "firstNotificationTimestamp": "2025-02-20T09:40:03.164774Z",
  "lastNotificationTimestamp": "2025-02-20T09:40:03.164774Z",
  "latestCreatedTimestamp": "2025-02-20T09:40:03.1677126Z",
  "notifications": [
    {
      "tmpReference": "TMP103718",
      "tmpCustomerReference": "TMP103718",
      "caseIndex": 1,
      "notificationTypeCode": "CREATEDIRECTINSTRUCTION",
      "notificationTimestamp": "2025-02-20T09:40:03.164774Z",
      "createdTimestamp": "2025-02-20T09:40:03.1677126Z",
      "caseStatusCode": "REFERRED",
      "information": {},
      "timestamps": {},
      "fees": {}
    }
  ]
}

See the section below about Notifications for a breakdown of the properties returned.

Mark notifications as processed

PUT /instruction/{reference}/processed?timestamp={toTimestamp}

This method will mark all notifications as processed up to the timestamp specified. The value used for timestamp should be the latestCreatedTimestamp that is returned from the method to retrieve notifications. If you make a subsequent call to this method with a date before latestCreatedTimestamp it will have no effect.

Resetting notifications

However, if you send the date as 0001-01-01T00:00:00.000000Z it will reset all the notifications for that instruction.

Notifications

The method to retrieve notifications for an instruction GET /instruction/{reference}/notifications will return a list of notifications. A typical notification might return this:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "CREATEINSTRUCTIONFROMQUOTE",
  "notificationTimestamp": "2025-02-20T09:40:03.164774Z",
  "createdTimestamp": "2025-02-20T09:40:03.1677126Z",
  "caseStatusCode": "REFERRED",
  "information": {},
  "timestamps": {},
  "fees": {}
}

The properties of this notification object are:

Property	Description
InstructionRef	The TMP Reference of the instruction.
NotificationTypeCode	A code to identify the notification. See details below.
NotificationTimestamp	The timestamp of the notification.
CreatedTimestamp	The timestamp that the notification was saved. Should be the similar to `NotificationTimestamp` - see notes at start of this article.
CaseStatusCode	The status of the case at the point the notification was recorded.
Information	A dictionary of additional information.
Timestamps	A dictionary of any other timestamps apart from the notification timestamp, e.g. the date of the appointment
Fees	A dictionary of fee information if required, e.g. the fee the surveyor will receive when the case is offered

The properties InstructionRef, NotificationTypeCode, NotificationTimestamp and CreatedTimestamp will always be present. We aim to populate the other fields as best we can with the information - but your integration should be tolerant of missing information. For example, reasons will not always be available when an action is taken (such as an appointment being cancelled).

You should also consider how to make your integration able to reprocess the same notifications. The steps for processing an instruction are not a single transaction, but consist of the following steps:

Process each notification into your system (processing all the notifications in your system may be a single transaction).
Call the method on our system to mark the notifications as processed.

If the first part partially fails you may need to process notifications that you have already processed. Similarly, if the second part of this fails or does not take place, when you retreive future notifications they will include those that you have already processed. You could optionally store the last CreatedTimestamp with the instruction in your system and then retrieve notifications using that - although the method to retrieve a list of instructions with notifications will still return it.

Create Instruction from Quote

Introducer"notificationTypeCode": "CREATEINSTRUCTIONFROMQUOTE"

This notification will be created when an instruction is created from a quote. Beware that this referral may not have been created by your own integration - it may come from other sources. Thus, you would typically not skip this notification but check against your own records.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "CREATEINSTRUCTIONFROMQUOTE",
  "notificationTimestamp": "2025-02-20T10:06:18.5699876Z",
  "createdTimestamp": "2025-02-20T10:06:19.0718205Z",
  "caseStatusCode": "REFERRED",
  "information": {
    "PRODUCTCODE": "RICSL2SURVEY"
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
PRODUCTCODE	The code for the product. See Data service with data set code `ALLPRODUCTS`.

There will be no data in the timestamps and fees properties.

The CaseStatusCode will typically be Referred but may also be New.

Create referral

Introducer"notificationTypeCode": "CREATEREFERRAL"

This notification will be created when a direct referral is created. Beware that this referral may not have been created by your own integration - it may come from other sources. Thus, you would typically not skip this notification but check against your own records.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "CREATEREFERRAL",
  "notificationTimestamp": "2025-02-20T13:56:25.0585472Z",
  "createdTimestamp": "2025-02-20T13:56:25.0631871Z",
  "caseStatusCode": "NEW",
  "information": {
    "PRODUCTCODE": "RICSL2SURVEYVALUATION"
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
PRODUCTCODE	The code for the product. See Data service with data set code `ALLPRODUCTS`.

There will be no data in the timestamps and fees properties.

The CaseStatusCode will typically be New but may also be Referred.

Case confirmed/accepted

Introducer"notificationTypeCode": "CASECONFIRMED"

This notification will be created when a case at the New status is confirmed (or accepted) by TMP. This status is typically used for direct referrals are created, but it can also apply to instructions created from quotes.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "CASECONFIRMED",
  "notificationTimestamp": "2025-02-20T14:50:43.6564209Z",
  "createdTimestamp": "2025-02-20T14:50:43.6687384Z",
  "caseStatusCode": "REFERRED",
  "information": {},
  "timestamps": {},
  "fees": {}
}

There will be no data in the information, timestamps and fees properties.

Case rejected

Introducer"notificationTypeCode": "CASEREJECTED"

This notification will be created when a case at the New status is rejected by TMP. This status is typically used for direct referrals are created, but it can also apply to instructions created from quotes.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "CASEREJECTED",
  "notificationTimestamp": "2025-02-20T14:55:58.8559121Z",
  "createdTimestamp": "2025-02-20T14:55:58.8633348Z",
  "caseStatusCode": "REJECTED",
  "information": {
    "REASONCODE": "WRONGPRODUCT",
    "REASONDESCRIPTION": "Wrong product"
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
REASONCODE	The code for the reason. See Data service with data set code `REJECTCASEREASONS`.
REASONDESCRIPTION	Description of the reason (for display).

There will be no data in the timestamps and fees properties.

Ordered

Introducer"notificationTypeCode": "ORDERED"

This notification will be created when a case is Ordered. This can happen at the following points:

When a payment (e.g. by card) is made or recorded for a Referred Instruction.
When an introducer is configured to be invoiced for payment (i.e. the introducer is responsible for taking payment). This can be triggered at the point a quote is referred to us or a direct referral is made. When this happens the case will automatically be marked as ordered.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "ORDERED",
  "notificationTimestamp": "2025-02-21T11:15:08.6154971Z",
  "createdTimestamp": "2025-02-21T11:15:08.6159332Z",
  "caseStatusCode": "ORDERED",
  "information": {
    "PRODUCTCODE": "RICSL2SURVEY"
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
PRODUCTCODE	The code for the product. See Data service with data set code `ALLPRODUCTS`.

There will be no data in the timestamps and fees properties.

Case allocated

Supplier"notificationTypeCode": "ALLOCATED"

This notification will be created when a case has been allocated (offered) to a supplier.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "ALLOCATED",
  "notificationTimestamp": "2025-02-21T16:20:41.1141618Z",
  "createdTimestamp": "2025-02-21T16:20:41.1143249Z",
  "caseStatusCode": "OFFERED",
  "information": {},
  "timestamps": {
    "OFFEREXPIRY": "2025-02-24T10:00:00Z"
  },
  "fees": {
    "OFFERFEEINCLVAT": 400.00
  }
}

Timestamps Key	Description
OFFEREXPIRY	The timestamp that this offer expires. It may still be available for acceptance after this date.

Fees Key	Description
OFFERFEEINCLVAT	The fee that the case is offered at.

There will be no data in the information property.

Case deallocated

Supplier"notificationTypeCode": "ALLOCATED"

This notification will be created when a case has been deallocated from a supplier. This can be done when a case is allocated to another supplier or is explicitly deallocated, e.g. before a case is cancelled.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "DEALLOCATED",
  "notificationTimestamp": "2025-02-21T16:19:45.2708988Z",
  "createdTimestamp": "2025-02-21T16:19:45.2710921Z",
  "caseStatusCode": "OFFERED",
  "information": {
    "REASONCODE": "OTHER",
    "REASONDESCRIPTION": "Other"
  },
  "timestamps": {},
  "fees": {}
}

Information Key	Description
REASONCODE	The code for the reason. See Data service with data set code `DEALLOCATECASEREASONS`.
REASONDESCRIPTION	Description of the reason (for display).

There will be no data in the timestamps or fees properties.

Case declined

Supplier"notificationTypeCode": "DECLINECASE"

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "DECLINECASE",
  "notificationTimestamp": "2025-02-21T16:23:07.252787Z",
  "createdTimestamp": "2025-02-21T16:23:07.2557416Z",
  "caseStatusCode": "OFFERED",
  "information": {
    "REASONCODE": "OTHER",
    "REASONDESCRIPTION": "Other"
  },
  "timestamps": {},
  "fees": {}
}

Information Key	Description
REASONCODE	The code for the reason. See Data service with data set code `DECLINECASEREASONS`.
REASONDESCRIPTION	Description of the reason (for display).

There will be no data in the timestamps or fees properties.

Case accepted

Supplier"notificationTypeCode": "ACCEPTED"

This notification will be created when a case has been accepted by a supplier.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "ACCEPTED",
  "notificationTimestamp": "2025-02-21T15:35:24.7752519Z",
  "createdTimestamp": "2025-02-21T15:35:24.7821362Z",
  "caseStatusCode": "ACCEPTED",
  "information": {
    "PRODUCTCODE": "RICSL2SURVEYVALUATION"
  },
  "timestamps": {},
  "fees": {
    "YOURFEEINCLVAT": 407.0000
  }
}

Other Information Key	Description
PRODUCTCODE	The code for the product. See Data service with data set code `ALLPRODUCTS`.

Fees Key	Description
YOURFEEINCLVAT	The fee that the case was accepted at.

There will be no data in the fees properties.

Case assigned

Introducer"notificationTypeCode": "ASSIGNED"

This notification will be created when a case has been assigned to a supplier.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "ASSIGNED",
  "notificationTimestamp": "2025-02-20T15:33:23.7383084Z",
  "createdTimestamp": "2025-02-20T15:33:23.7407994Z",
  "caseStatusCode": "ALLOCATED",
  "information": {
    "SUPPLIER": "Abercorn Estate Agents",
    "PRODUCTCODE": "RICSL2SURVEYVALUATION"
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
SUPPLIER	The name of the supplier.
PRODUCTCODE	The code for the product. See Data service with data set code `ALLPRODUCTS`.

There will be no data in the timestamps and fees properties.

Terms and conditions sent

Introducer Supplier"notificationTypeCode": "TERMSANDCONDITIONSSENT"

This notification will be created when the terms and conditions have been sent. Use of this functionality by the supplier is optional. It will only be raised when the case is at the ACCEPTED or ASSIGNED statuses.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "TERMSANDCONDITIONSSENT",
  "notificationTimestamp": "2025-02-20T15:50:32.7246542Z",
  "createdTimestamp": "2025-02-20T15:50:32.7275645Z",
  "caseStatusCode": "ALLOCATED",
  "information": {},
  "timestamps": {},
  "fees": {}
}

There will be no data in the information, timestamps and fees properties.

New

This is new functionality being added in Q2 2025. More functionality will be added to support information about the terms and conditions (such as the date the terms and conditions where sent and received).

Terms and conditions received

Introducer Supplier"notificationTypeCode": "TERMSANDCONDITIONSRECEIVED"

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "TERMSANDCONDITIONSRECEIVED",
  "notificationTimestamp": "2025-02-20T15:50:32.7246542Z",
  "createdTimestamp": "2025-02-20T15:50:32.7275645Z",
  "caseStatusCode": "ALLOCATED",
  "information": {},
  "timestamps": {},
  "fees": {}
}

There will be no data in the information, timestamps and fees properties.

New

Appointment booked

Introducer Supplier"notificationTypeCode": "BOOKAPPOINTMENT"

This notification will be created when an appointment has been booked.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "BOOKAPPOINTMENT",
  "notificationTimestamp": "2025-02-20T15:35:41.6142738Z",
  "createdTimestamp": "2025-02-20T15:35:41.6164916Z",
  "caseStatusCode": "APPOINTMENTBOOKED",
  "information": {
    "TIMESLOTCODE": "AFTERNOON",
    "TIMESLOTCODEDESCRIPTION": "Afternoon"
  },
  "timestamps": {
    "APPOINTMENTDATE": "2025-02-23T00:00:00Z"
  },
  "fees": {}
}

Other Information Key	Description
TIMESLOTCODE	The code for the timeslot. This is optional. See Data service with data set code `APPOINTMENTTIMES`.
TIMESLOTCODEDESCRIPTION	A description for the timeslot.

Timestamps Key	Description
APPOINTMENTDATE	The date the appointment has been booked.

There will be no data in the fees property.

Appointment rebooked

Introducer Supplier"notificationTypeCode": "REBOOKAPPOINTMENT"

This notification will be created when an appointment has been re-booked.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "REBOOKAPPOINTMENT",
  "notificationTimestamp": "2025-02-20T15:39:02.5635465Z",
  "createdTimestamp": "2025-02-20T15:39:02.5637098Z",
  "caseStatusCode": "APPOINTMENTBOOKED",
  "information": {
    "REASONCODE": "CLIENTREQUESTED",
    "REASONDESCRIPTION": "Client request",
    "TIMESLOTCODE": "AFTERNOON",
    "TIMESLOTCODEDESCRIPTION": "Afternoon"
    },
  "timestamps": {
    "APPOINTMENTDATE": "2025-02-21T00:00:00Z"
  },
  "fees": {}
}

Other Information Key	Description
REASONCODE	The code for the reason. See Data service with data set code `REBOOKAPPOINTMENTREASONS`.
REASONDESCRIPTION	Description of the reason (for display).
TIMESLOTCODE	The code for the timeslot. This is optional. See Data service with data set code `APPOINTMENTTIMES`.
TIMESLOTCODEDESCRIPTION	A description for the timeslot.

Timestamps Key	Description
APPOINTMENTDATE	The date the appointment has been rebooked.

There will be no data in the fees property.

Appointment cancelled

Introducer Supplier"notificationTypeCode": "CANCELAPPOINTMENT"

This notification will be created when an appointment has been cancelled - typically in preparation for the case to be cancelled or reallocate, but also due to delays in the property chain etc.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "CANCELAPPOINTMENT",
  "notificationTimestamp": "2025-02-20T15:44:52.7792681Z",
  "createdTimestamp": "2025-02-20T15:44:52.7810763Z",
  "caseStatusCode": "ALLOCATED",
  "information": {
    "REASONCODE": "BEINGREALLOCATED",
    "REASONDESCRIPTION": "Case is being reallocated"
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
REASONCODE	The code for the reason. See Data service with data set code `CANCELAPPOINTMENTREASONS`.
REASONDESCRIPTION	Description of the reason (for display).

There will be no data in the timestamps and fees properties.

Case completed

Introducer Supplier"notificationTypeCode": "COMPLETECASE"

This notification will be created when the case is completed - typically when a report has been uploaded. If a replacement report is uploaded then a second notification would be added.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "COMPLETECASE",
  "notificationTimestamp": "2025-02-20T15:50:32.7246542Z",
  "createdTimestamp": "2025-02-20T15:50:32.7275645Z",
  "caseStatusCode": "COMPLETED",
  "information": {},
  "timestamps": {},
  "fees": {}
}

There will be no data in the information, timestamps and fees properties.

Case cancelled

Introducer Supplier"notificationTypeCode": "CANCELCASE"

This notification will be created when the case has been cancelled.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "CANCELCASE",
  "notificationTimestamp": "2025-02-21T11:41:47.0969028Z",
  "createdTimestamp": "2025-02-21T11:41:47.2047359Z",
  "caseStatusCode": "CANCELLED",
  "information": {
    "REASONCODE": "DATENOTSUITABLE",
    "REASONDESCRIPTION": "Date not suitable"
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
REASONCODE	The code for the reason. See Data service with data set code `CANCELCASEREASONS`.
REASONDESCRIPTION	Description of the reason (for display).

There will be no data in the timestamps and fees properties.

Put case on hold

Introducer Supplier"notificationTypeCode": "PUTCASEONHOLD"

This notification will be created when a case is put on hold.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "PUTCASEONHOLD",
  "notificationTimestamp": "2025-02-20T13:34:55.9769622Z",
  "createdTimestamp": "2025-02-20T13:34:55.982683Z",
  "caseStatusCode": "ORDERED",
  "information": {
    "REASONCODE": "SALEFALLENTHROUGH",
    "REASONDESCRIPTION": "Sale fallen through"
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
REASONCODE	The code for the reason. See Data service with data set code `CASEONHOLDREASONS`.
REASONDESCRIPTION	Description of the reason (for display).

There will be no data in the timestamps and fees properties.

Take case off hold

Introducer Supplier"notificationTypeCode": "TAKECASEOFFHOLD"

This notification will be created when a case is taken off hold.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "TAKECASEOFFHOLD",
  "notificationTimestamp": "2025-02-20T13:44:59.2304969Z",
  "createdTimestamp": "2025-02-20T13:44:59.2368766Z",
  "caseStatusCode": "ORDERED",
  "information": {},
  "timestamps": {},
  "fees": {}
}

There will be no data in the information, timestamps and fees properties.

New note added

Introducer Supplier"notificationTypeCode": "NEWNOTE"

This notification will be created when an explicit note is added.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "NEWNOTE",
  "notificationTimestamp": "2025-02-21T10:17:51.6892154Z",
  "createdTimestamp": "2025-02-21T10:17:51.6894592Z",
  "caseStatusCode": "ORDERED",
  "information": {
    "SEQUENCE": 4,
    "ISVISIBLETOCUSTOMER": true
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
SEQUENCE	The sequence of the note. You should load the instruction to retrieve details of the note.
ISVISIBLETOCUSTOMER	Whether the note is visible to the customer. If not present (or set to false) it is not visible.

There will be no data in the timestamps and fees properties.

Other case updates

If the details of the customers or property are changed notifications for UPDATECUSTOMERS or UPDATEPROPERTY will be created. These should always create notes of the description and you should synchronise notes. A notification for NEWNOTE will not be created in this instance.

Change product

Introducer Supplier"notificationTypeCode": "CHANGEPRODUCT"

This notification will be created when the product for the case is changed.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "CHANGEPRODUCT",
  "notificationTimestamp": "2025-02-21T12:00:50.9768069Z",
  "createdTimestamp": "2025-02-21T12:00:50.9842192Z",
  "caseStatusCode": "NEW",
  "information": {
    "REASONCODE": "CLIENTREQUEST",
    "REASONDESCRIPTION": "Client request",
    "PRODUCTCODE": "RICSL3BUILDINGSURVEY"
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
REASONCODE	The code for the reason. See Data service with data set code `CHANGECASEPRODUCTREASONS`.
REASONDESCRIPTION	Description of the reason (for display).
PRODUCTCODE	The code for the product. See Data service with data set code `ALLPRODUCTS`.

There will be no data in the timestamps and fees properties.

Change attributes

Introducer Supplier"notificationTypeCode": "CHANGEATTRIBUTES"

This notification will be created when the attributes for the products of a case are changed. Attributes allow for specific information to be tagged on the instruction, such as where a Help To Buy Valuation is a "Rewrite" (i.e. Desktop valuation).

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "CHANGEATTRIBUTES",
  "notificationTimestamp": "2025-02-21T13:19:27.7534864Z",
  "createdTimestamp": "2025-02-21T13:19:27.7535439Z",
  "caseStatusCode": "NEW",
  "information": {
    "PRODUCTCODE": "RICSL3BUILDINGSURVEY",
    "ATTRIBUTESENABLED": "L3VALUATION",
    "ATTRIBUTESDISABLED": ""
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
PRODUCTCODE	The code for the product. See Data service with data set code `ALLPRODUCTS`.
ATTRIBUTESENABLED	A comma seperate string of those attributes that have been enabled.
ATTRIBUTESDISABLED	A comma seperate string of those attributes that have been disabled.

New

This is new functionality being added in Q1 2025. More functionality will be added to support information about the attributes. The attributes that initially setup and may show are:

L3VALUATION: A valuation has been added to a L3 survey.
HTBVALUATIONREWRITE: A rewrite for a Help to Buy valuation.

There will be no data in the timestamps and fees properties.

Update customers

Introducer Supplier"notificationTypeCode": "UPDATECUSTOMERS"

This notification will be created when customers have been updated. A new note should have been added that will contain a description of the change so you should synchronise the notes.

There may also have been an email sent to interested parties informing them that a new note had been added. The TMP team can choose not send the notification. For example if tidying up details (i.e. removing capitialisation, formatting telephone numbers).

If you are interested in this detail you could synchronise the changes by loading the instruction and extracting the customer details.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "UPDATECUSTOMERS",
  "notificationTimestamp": "2025-02-20T13:44:59.2304969Z",
  "createdTimestamp": "2025-02-20T13:44:59.2368766Z",
  "caseStatusCode": "ORDERED",
  "information": {},
  "timestamps": {},
  "fees": {}
}

There will be no data in the information, timestamps and fees properties.

Customer with multiple cases

If a customer has more than one case then more than one notification may be created. One should be created for each active case.

Update property

Introducer Supplier"notificationTypeCode": "UPDATEPROPERTY"

This notification will be created when details of the property has been updated.

A new note should have been added that will contain a description of the change so you should synchronise the notes.

If you are interested in this detail you could synchronise the changes by loading the instruction and extracting the property information.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "UPDATEPROPERTY",
  "notificationTimestamp": "2025-02-20T13:44:59.2304969Z",
  "createdTimestamp": "2025-02-20T13:44:59.2368766Z",
  "caseStatusCode": "ORDERED",
  "information": {},
  "timestamps": {},
  "fees": {}
}

There will be no data in the information, timestamps and fees properties.

Change fee

Introducer Supplier"notificationTypeCode": "CHANGEFEE"

This notification will be created when a fee is changed. The return is different for Introducer and Suppliers.

Change introducer fee Introducer

The notification for a fee change for an introducer is created when either the fee the introducer will receive is changed or the total fee is changed. If the fee the introducer receives is changed it will normally be discussed in advance. If the total fee is changed this is normally due to a change in product (e.g. Level 2 survey to Level 3 or adding a valuation).

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "CHANGEFEE",
  "notificationTimestamp": "2025-02-20T16:27:09.6103146Z",
  "createdTimestamp": "2025-02-20T16:27:09.6569837Z",
  "caseStatusCode": "REFERRED",
  "information": {},
  "timestamps": {},
  "fees": {
    "PREVIOUSYOURFEEINCLVAT": 150.00,
    "PREVIOUSTOTALFEEINCLVAT": 975.00,
    "YOURFEEINCLVAT": 150.00,
    "TOTALFEEINCLVAT": 1175.00
  }
}

Fees Key	Description
PREVIOUSYOURFEEINCLVAT	The previous value of your fee including VAT.
PREVIOUSTOTALFEEINCLVAT	The previous value of the total fee including VAT.
YOURFEEINCLVAT	The value of your fee including VAT.
TOTALFEEINCLVAT	The value of the total fee including VAT.

There will be no data in the information and timestamps properties.

Change supplier fee Supplier

The notification for a fee change for a supplier is created when either the fee the supplier will receive is changed.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "CHANGEFEE",
  "notificationTimestamp": "2025-02-20T16:27:09.6103146Z",
  "createdTimestamp": "2025-02-20T16:27:09.6569837Z",
  "caseStatusCode": "REFERRED",
  "information": {},
  "timestamps": {},
  "fees": {
    "PREVIOUSYOURFEEINCLVAT": 150.00,
    "YOURFEEINCLVAT": 150.00
  }
}

Fees Key	Description
PREVIOUSYOURFEEINCLVAT	The previous value of your fee including VAT.
YOURFEEINCLVAT	The value of your fee including VAT.

There will be no data in the information and timestamps properties.

Case uncancelled

Introducer Supplier"notificationTypeCode": "UNCANCELCASE"

This notification will be created when a case is uncancelled. Our policy is to use it only for cases at the Referred status and thus should only be applicable to Introducers. However, we have retained the possiblity to use it with a case that has been ordered.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "UNCANCELCASE",
  "notificationTimestamp": "2025-02-24T09:52:43.5660034Z",
  "createdTimestamp": "2025-02-24T09:52:43.5705426Z",
  "caseStatusCode": "REFERRED",
  "information": {
    "REASONCODE": "CANCELLEDINERROR",
    "REASONDESCRIPTION": "Cancelled in error"
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
REASONCODE	The code for the reason. See Data service with data set code `UNCANCELREASONS`.
REASONDESCRIPTION	Description of the reason (for display).

There will be no data in the timestamps and fees properties.

Case reopened

Introducer Supplier"notificationTypeCode": "REOPENCASE"

There is functionality in our back end to reopen a completed case. It is used rarely as it creates other complications and our policy is not to use it. It is expected to be formally deprecated. If a case is reopened then a discussion with the parties involved would normally take place beforehand.

Typical return might be:

{
  "tmpReference": "TMP103718",
  "tmpCustomerReference": "TMP103718",
  "caseIndex": 1,
  "notificationTypeCode": "REOPENCASE",
  "notificationTimestamp": "2025-02-24T13:31:21.5704925Z",
  "createdTimestamp": "2025-02-24T13:31:21.5740478Z",
  "caseStatusCode": "APPOINTMENTBOOKED",
  "information": {
    "REASONCODE": "COMPLETEDINERROR",
    "REASONDESCRIPTION": "Completed in error"
  },
  "timestamps": {},
  "fees": {}
}

Other Information Key	Description
REASONCODE	The code for the reason. See Data service with data set code `REOPENREASONS`.
REASONDESCRIPTION	Description of the reason (for display).

There will be no data in the timestamps and fees properties.

Unimplemented notifications

Confirm case appointment completed Introducer Supplier

There is functionality available to allow a supplier to mark that an appointment has taken place. This functionality has not been enabled. When it is enabled notifications will need to be added to support this.

Supplier overdue for acceptance Supplier

When a case is offered to a supplier an expiry date for the offer is provided. It is still possible for a supplier to accept the case after this date, however they risk that the case has been offered to another supplier. An email is currently sent to the supplier about this. A notification will be added at a later date.

Payment made or due Introducer Supplier

An instruction at the New status will be reviewed by TMP for acceptance. On acceptance it will be moved to the Referred status if TMP is to collect payment. Thus at the Referred status it has not been paid and this should be fairly clear. Once payment has been made it will be recognised as an order. However it is possible for a fee change to be made (e.g. change of product) that will require additional payment. This is not recognised through the notifications (or by retrieving an Instruction) and even once an additional payment has been received there is no notification about this. The fee change notification will be modified at a later date to return this information as well as a new notification for when the payment has been made. There is a similar issue for refunds.

Note

This is as applicable to suppliers as introducers as the supplier may not be able to proceed until the additional payment is made.

Suppliers who can see some details of the Introducer Supplier

There will be some suppliers who can see details of the introducer (e.g. for certain products under certain circumstances). They should ideally see details such as the Introducer Reference (and thus notifications for when those change).

Update introducer references Introducer

When the references are set or modified a notification should be made. A notification will be added at a later date.

Update supplier references Introducer Supplier

When the references are set or modified a notification should be made. A notification will be added at a later date.

Update introducer person Introducer

When a quote or direct referral is created the person at the introduer should be assigned as "owner" of the case. If a TMP person creates a quote or referral on behalf of the introducer it may no be possible to determine who the "owner" is. There is interative functionality in the portal to change the owner of the case however no notification is created. A notification will be added at a later date as well as functionality via the API to return and change the owner.

Introducer integration for Customers Introducer

This integration does not support the model where the Introducer is completely acting on behalf of the customer. In this model the customer does not use our portal at all - they would have no logon and receive no emails or SMS. All of this functionality is performed by the Introducer. To support this model we would likely adapt the service authentication to run in the context of the customer (and not the introducer).