Referral service

This service contains the following methods:

These methods allow for a direct referral to be created and to check if a referral already exists.

Create referral

There are a few ways of getting a referral to us. The first approach is to use the Quote service to create a quote. The quote will contain one or more results, from which you can choose one and refer that to us.

The second approach is implemented by this method and allows you to create a direct referral.

A direct referral is typically one where the introducer has their own portal. They will work with their own internal fee calculation (to determine the total price and can set their own referral fee). The referral can then be sent to us.

Typically, these systems may not have all the information, e.g. access details to the property may be missing. But they have the basic information in order to:

• Perform a calculation of the total fee.
• Include essential details about the property - address and property value.

It is possible to send us a lead. This is where you do not know the total price to charge. In this case we will calculate the total fee (including any fee that you specify) from our price lists.

Direct referrals will usually be put into the NEW state for a review first by TMP. When in this state TMP will review the case to determine product suitability, fees and other details (e.g. review fees). If not all property details are provided and we may need to contact the client in advance or accepting the case, e.g. to determine product suitability, i.e. we might require the property age.

Once we have reviewed the case we would Accept it. This may allow the customer to view the case via the portal and make an online payment - this is configurable in our setup of your introducer. Alternatively we would Reject the case - normally contacting the Introducer and possibly the customer (e.g. if the product isn't suitable so that the customer can ask the Introducer to create a new referral).

A typical payload for this method might look like:

{
  "cases": [
    {
      "uniqueCustomerReference": "L2-JONES1234-19881",
      "uniqueIntegrationReference": "L2-JONES1234-19881",
      "productCode": "RICSL2SURVEY",
      "totalFeeInclVAT": 750.00,
      "yourFeeInclVAT": 50.00,
      "isLead": false
    }
  ],
  "propertyValueOrPurchasePrice": 325000.00,
  "propertyValueTierCode": "300KTO350K",
  "propertyTypeCode": "DETACHED",
  "propertyAgeCode": "TENTOFIFTYYEARS",
  "yearBuilt": null,
  "propertyAddress": {
    "addressFormatCode": "DEFAULT",
    "addressLine1": "12 Spring Terrace",
    "addressLine2": "",
    "addressLine3": "Springfield",
    "addressLine4": "Springshire",
    "postcode": "SP5 1NG",
    "countryCode": "GB"
  },
  "correspondenceAddress": {
    "addressFormatCode": "DEFAULT",
    "addressLine1": "15 Summer Lane",
    "addressLine2": "",
    "addressLine3": "Summertown",
    "addressLine4": "Summerland",
    "postcode": "SU8 8ER",
    "countryCode": "GB"
  },
  "accessDetails": {
    "accessTypeCode": "VENDOR",
    "firmName": "Spring and Summer properties",
    "emailAddress": "joe@springandsummer.co.uk",
    "contactName": "Joe Autumn",
    "telephoneNumber": "01234 121212"
  },
  "customers": [
    {
      "emailAddress": "fredjones@themovingportal.dev",
      "title": "",
      "firstName": "Fred",
      "lastName": "Jones",
      "telephoneNumber": "01234 882299",
      "receiveSMS": true
    }
  ],
  "referrer": null
  }
}

The properties of this payload are:

Cases

The payload for this object is:

"cases": [
  {
    "uniqueCustomerReference": "L2-JONES1234-19881",
    "uniqueIntegrationReference": "L2-JONES1234-19881",
    "productCode": "RICSL2SURVEY",
    "totalFeeInclVAT": 750.00,
    "yourFeeInclVAT": 50.00,
    "isLead": false
  }
]

The properties of this object are:

References

The UniqueCustomerReference and UniqueIntegrationReference are references used by the Introducer to identify their cases. You do not need to provide any references to identify the case. The primary aim of this reference is to ensure that duplicate cases are not created. If you do not provide them then the referral will be created without checking and you will need to use the TMP reference to access the case. If you do provide either of them then they must be unique (for your organisation).

UniqueCustomerReference will be shown to the customer on our portal. UniqueIntegrationReference will only be shown to TMP users on our portal.

Either of these references can be used by the introducer when retrieving an instruction, with UniqueIntegrationReference taking precendence.

See Key concepts.

Validation

• Both references are optional.
• If any is provided they must be no longer than 30 characters.
• The reference must be unique amongst your cases.

Product

The ProductCode is a code for the product. You can get a list of your products from the Data service.

Validation

• The code provided must be valid and an active product for your firm.

Fees

There are two properties for the fee:

• TotalFeeInclVAT: This is the total fee that the customer is being charged and will be collected from the customer, e.g. via online payment. For Introducers who are invoiced (i.e. an introducer who collects payment themselves) this is the amount we will display. This value is required.
  
  If the isLead property is provided and set to true then TotalFeeInclVAT must not be specified (or set to null).

• YourFeeInclVAT: This is the referral fee to be paid to the Introducer. It is optional and should only be set in exceptional cases. If it is not provided (i.e. set to null) then the fee will be calculated based on the pricing for your selected product.
  
  If the isLead property is provided and set to true then any value specifed for YourFeeInclVAT will be used in the calculation of that total fee.

Validation

• TotalFeeInclVAT must be provided if IsLead is not provided or false and the value of this property must be greater than or equal to zero.
  If IsLead is true then this property must not be provided or set to null.
• If YourFeeInclVAT is provided then this value must be greater than or equal to zero.
• If IsLead is specified and set to true then TotalFeeInclVAT must not be provided or set to null.

Property attributes

These are attributes describing the property

"propertyValueOrPurchasePrice": 325000.00,
"propertyValueTierCode": "300KTO350K",
"propertyTypeCode": "DETACHED",
"propertyAgeCode": "TENTOFIFTYYEARS",
"yearBuilt": null

When creating a direct referral there is some information that is required.

To calculate the fees, we need to be able to know PropertyValueOrPurchasePrice or PropertyValueTierCode.

We do not need to know at this point the other property attributes (PropertyTypeCode, PropertyAgeCode or YearBuilt). We can determine these when we contact the customer. However, the more information we have at this point the easier it is to convert the referral into an order.

Validation

• PropertyValueOrPurchasePrice or PropertyValueTierCode is required.
• PropertyValueTierCode must be valid. See Key concepts.
• If PropertyTypeCode is provided it must be valid. If not known must be set to UNKNOWN. See Key concepts.
• If PropertyAgeCode is provided it must be valid. If not known must be set to UNKNOWN. See Key concepts.
• If PropertyAgeCode is UNKNOWN and YearBuilt is set then it will be used to determine the property age band.

Property address

The address of the property is required in order to refer a case to us.

"propertyAddress": {
  "addressFormatCode": "DEFAULT",
  "addressLine1": "12 Spring Terrace",
  "addressLine2": "",
  "addressLine3": "Springfield",
  "addressLine4": "Springshire",
  "postcode": "SP5 1NG",
  "countryCode": "GB"
}

Validation

The minimum requirements for an address is the AddressLine1 and Postcode.

See Key concepts for full validation for addresses.

Correspondence address

The correspondence address is not mandatory. We can determine this when we contact the customer. However, the more information we have at this point the easier it is to convert the referral into an order.

"correspondenceAddress": {
  "addressFormatCode": "DEFAULT",
  "addressLine1": "15 Summer Lane",
  "addressLine2": "",
  "addressLine3": "Summertown",
  "addressLine4": "Summerland",
  "postcode": "SU8 8ER",
  "countryCode": "GB"
}

Validation

If you do not have the address you can either set correspondenceAddress to null or set addressFormatCode to NONE.

If provided, the minimum requirements for an address is to provide AddressLine1 and Postcode.

See Key concepts for full validation for addresses.

Access details

The access details is not a mandatory requirements. We can determine these when we contact the customer. However, the more information we have at this point the easier it is to convert the referral into an order.

The payload for this object is:

"accessDetails": {
  "accessTypeCode": "VENDOR",
  "firmName": "Spring and Summer properties",
  "emailAddress": "joe@springandsummer.co.uk",
  "contactName": "Joe Autumn",
  "telephoneNumber": "01234 121212"
}

Validation

If access details are provided:

• AccessTypeCode can be set to VENDOR or AGENT.
• FirmName is required when access type is VENDOR and has a maximum length of 150 characters.
• EmailAddress has a maximum length of 100 characters and must be a valid email address.
• ContactName is required and has a maximum length of 150 characters.
• TelephoneNumber is required and has a maximum length of 150 characters.

Customers

At least one customer is required. This customer must have

• Person name (first name and last name).
• Email address.
• Telephone number.

{
  "emailAddress": "fredjones@themovingportal.dev",
  "title": "",
  "firstName": "Fred",
  "lastName": "Jones",
  "telephoneNumber": "01234 882299",
  "receiveSMS": true
}

It is then possible to provide named customers, which only require their name. This allows for the surveyor to add that customer name to the final report, but without needing their details.

Validation

• Up to four customers can be specified.
• The first customer must have all their details:
  • EmailAddress is required and has a maximum length of 100 characters and must be a valid email address.
  • TelephoneNumber is required, has a maximum length of 20 characters and must be a valid telephone number - using regular expression ^((\+|00)(\d){1,3})?((\s|\d|\(|\))?){8,15}$.
  • Title has a maximum length of 20 characters.
  • FirstName is required and has a maximum length of 50 characters.
  • LastName is required and has a maximum length of 50 characters.
• Subsequent customers can be specified with just FirstName and LastName.

Referrer

This is your referrer. It is where the introducer will refer cases on behalf of another party. We use this as a point of contact for TMP if there is a problem with the referral (e.g. wrong product). Providing the referrer is optional.

If you provide it, then it will be displayed to the customer in our portal when they look at the Instruction. and your firms details will not be displayed on the Instruction. (Your details will be displayed if the customer edit's their details).

You should review GDPR for more details about the impact of this.

A typical payload for the referrer is:

"referrer": {
  "companyReference": "HR627819",
  "companyName": "Mortage Brokers Limited",
  "companyTelephoneNumber": "01266 188199",
  "companyEmailAddress": "enquiries@mortgagebrokersltd.co.uk",
  "address": {
    "addressFormatCode": "DEFAULT",
    "addressLine1": "1 The Street",
    "addressLine2": "",
    "addressLine3": "Town",
    "addressLine4": "County",
    "postcode": "MO8 7RK",
    "countryCode": "GB"
  },
  "contactReference": "HR627891-1",
  "contactTitle": "Mr",
  "contactFirstName": "Joe",
  "contactFLastName": "Smith",
  "contactTelephoneNumber": "01266 188120",
  "contactMobileNumber": "07188 299191'",
  "contactEmailAddress": "joe@mortgagebrokersltd.co.uk"
}

Validation

The referrer object itself is optional.

If provided all company information and a contact name must be provided, but other contacts details are not:

• companyReference: required, up to 50 characters. This reference should be unique amongst your referrers.
• companyName: required, up to 100 characters.
• companyTelephoneNumber: required, up to 20 characters, using regular expression ^((\+|00)(\d){1,3})?((\s|\d|\(|\))?){8,15}$.
• companyEmailAddress: required, up to 100 characters and be a valid email address.
• address: required, address.AddressFormatCode must be set to DEFAULT. Address must be a valid address (see Key concepts).
• contactTitle: optional, up to 20 characters.
• contactFirstName: optional, up to 50 characters.
• contactLastName: required, up to 50 characters.
• contactTelephoneNumber: optional, up to 20 characters, using regular expression ^((\+|00)(\d){1,3})?((\s|\d|\(|\))?){8,15}$.
• contactMobileNumber: optional, up to 20 characters, using regular expression ^((\+|00)(\d){1,3})?((\s|\d|\(|\))?){8,15}$.
• contactEmailAddress: optional, up to 100 characters and be a valid email address.

A successful return from this method will be an object with the reference:

{
  "success": true,
  "reference": "TMP103814"
}

Check if a referral exists

This method will use your reference (either UniqueIntegrationReference or UniqueCustomerReference) to check if a referral exists. It would typically be used before you create a referrral to check if the referral had already been created.

If the reference exists then a 200 Ok response will be returned.

If the reference does not exist then a 404 Not Found response will be returned.

However, if there is a validation issue (e.g. no reference or reference too long) then a 400 Bad Request will be returned - but no errors will be shown (as this is a HEAD method).