Quote service

This service contains the following methods:

Get quote

This method will use the TMP reference to retrieve a quote.

Object: Quote

A Quote is made up of the following properties

Other information

The following information may be available

Allowed operations

The following codes may be returned.

• EDITPROPERTY - Allows the property to be changed.
• REMOVEALLRESULTS - Marks all the results as removed.

Object: Quote result

When a quote is generated it will return a set of results.

Allowed operations

The following codes may be returned to allow an operation on this result:

• REQUEST - if the quote comes back as Price on Application.
• REFER - this will send the quote as a referral to us. Once done you cannot modify the details (e.g. fees or property).
• REMOVERESULT - the result will be removed. It can still be searched for.
• ADJUSTFEE - you can modify your fee, which will change the total fee.
• EMAIL - this will email the quote to the customer with the selected result, however, all results will be available to the customer. If you only wish to email this result you need to remove the other results first.

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.

Object: QuoteProperty

The QuoteProperty 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.

Get quote using introducer reference

This method will use the Introducer references to retrieve the Quote. Some instructions may not have an Introducer reference. However, if they have either a IntroducerIntegrationReference or IntroducerCustomerReference this can be specified here.

See Key concepts for more information.

Be aware that the introducer references are removed from quote once it has been instructed.

Create quote

There are a few ways of getting a referral to us. It is possible to create a direct referral using the Referral service. This requires generating your own fees - which should match the official price structure.

The alternative is to generate a quote and subsequently refer it to us. The quote will be priced using the official price lists and the quote will contain one or more results. (e.g. the quote could also contain results for other products).

A typical payload for a new quote is

{
  "cases": [
    {
      "productCode": "RICSL2SURVEY",
      "yourFeeInclVAT": 0
    }
  ],
  "propertyValueOrPurchasePrice": 280000,
  "propertyValueTierCode": "250KTO300K",
  "propertyTypeCode": "TERRACED",
  "propertyAgeCode": "LESSTHANTENYEARS",
  "yearBuilt": null,
  "propertyAddress": {
    "addressFormatCode": "DEFAULT",
    "addressLine1": "82 Fir Tree Avenue",
    "addressLine2": "",
    "addressLine3": "Wallingford",
    "addressLine4": "",
    "postcode": "OX10 0PL",
    "countryCode": "GB"
  },
  "correspondenceAddress": {
    "addressFormatCode": "DEFAULT",
    "addressLine1": "86 Fir Tree Avenue",
    "addressLine2": "",
    "addressLine3": "Wallingford",
    "addressLine4": "",
    "postcode": "OX10 0PL",
    "countryCode": "GB"
  },
  "accessDetails": {
    "accessTypeCode": "VENDOR",
    "firmName": "",
    "emailAddress": "vendor@vendor.co.uk",
    "contactName": "John Vendor",
    "telephoneNumber": "01234 121212"
  },
  "customers": [
    {
      "emailAddress": "joekennilworth@themovingportal.dev",
      "title": "",
      "firstName": "Joe",
      "lastName": "Kennilworth",
      "telephoneNumber": "01245 399999",
      "receiveSMS": false
    }
  ],
  "uniqueIntegrationReference": "EXA192884",
  "uniqueCustomerReference": "EXA192884"
}

A successful response from the service will return the Quote object (as per the Get quote method).

The payload for a new quote is very similar to that for a new referral. The only differences are in the cases object for the quote:

• You do not specify the totalFeeInclVAT. You can optionally specify yourFeeInclVAT which will be applied, otherwise it will use the value specified in the official price list.
• There is no support in quotes for your own references - these are only used for instructions/referrals. (Support will be added at a later date)

The properties of this payload are:

Cases

The payload for this object is:

"cases": [
  {
    "productCode": "RICSL2SURVEY",
    "yourFeeInclVAT": 750.00
  }
]

The properties of this object are:

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 is only a single property for the fee:

• YourFeeInclVAT: This is the referral fee to be paid to the Introducer. It is optional. If it is not provided (i.e. set to null) then the fee will be set to the value on the official price list.

Validation

If YourFeeInclVAT is provided:

• this value must be greater than or equal to zero.

Property information

These are information 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 full 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 (i.e. another company). We use this as a point of contact 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 Quote. Your firms details will not be displayed. (Your company details will only be displayed if the customer edit's their details).

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

Validation

See Referral Service for details of validation.

Quote validation

{
  "cases": [
    {
      "productCode": "RICSL2SURVEY",
      "yourFeeInclVAT": null
    }
  ],
  "propertyValueOrPurchasePrice": 280000,
  "propertyTypeCode": "UNKNOWN",
  "propertyAgeCode": "UNKNOWN",
  "propertyAddress": {
    "addressFormatCode": "DEFAULT",
    "addressLine1": "82 Fir Tree Avenue",
    "addressLine2": "",
    "addressLine3": "Wallingford",
    "addressLine4": "",
    "postcode": "OX10 0PL",
    "countryCode": "GB"
  },
  "customers": [
    {
      "emailAddress": "joekennilworth@themovingportal.dev",
      "title": "",
      "firstName": "Joe",
      "lastName": "Kennilworth",
      "telephoneNumber": "01245 399999",
      "receiveSMS": false
    }
  ]
}

Refer quote

Once you have created a quote you can use some of the other methods in this service to update the property details or your fee. However, once you call this method you can no longer do this.

When you are ready to refer the quote to TMP you will use this method. It has a very simple payload - just requiring the resultSequence to refer:

{
  "ResultSequence": 1
}

The result sequence must be provided and is valid. The quote cannot be referred if it is awaiting a price (REQUESTED), already referred/instructed (INSTRUCTED), Expired (EXPIRED) or Removed (REMOVED).

The references placed on a quote will be removed once the quote has been instructed.

Update property details

Before the quote is referred you are able to update the property details or your fee. The payload to this method to update the property details is

{
  "propertyTypeCode": "TERRACED",
  "propertyAgeCode": "LESSTHANTENYEARS",
  "yearBuilt": null,
  "propertyAddress": {
    "addressFormatCode": "DEFAULT",
    "addressLine1": "82 Fir Tree Avenue",
    "addressLine2": "",
    "addressLine3": "Wallingford",
    "addressLine4": "",
    "postcode": "OX10 0PL",
    "countryCode": "GB"
  },
  "correspondenceAddress": {
    "addressFormatCode": "DEFAULT",
    "addressLine1": "86 Fir Tree Avenue",
    "addressLine2": "",
    "addressLine3": "Wallingford",
    "addressLine4": "",
    "postcode": "OX10 0PL",
    "countryCode": "GB"
  },
  "accessDetails": {
    "accessTypeCode": "VENDOR",
    "firmName": "",
    "emailAddress": "vendor@vendor.co.uk",
    "contactName": "John Vendor",
    "telephoneNumber": "01234 121212"
  }
}

You cannot update the property details if the quote has been referred/instructed (INSTRUCTED), Expired (EXPIRED) or Removed (REMOVED).

Validation is as per creating a quote.

Email quote

When a quote is created it will not be visible to the customer. This allows the introducer to review it first and possibly amend the fees. This method will send and email to the customer(s) with the quote.

The payload for this method is

{
  "ResultSequences": [1]
}

The result sequences must be provided with at least once valid sequence number. The quote cannot be emailed if it is awaiting a price (REQUESTED), already referred/instructed (INSTRUCTED), Expired (EXPIRED) or Removed (REMOVED).

Change fee

Before the quote is referred you are able to update the porperty details and fee.

The payload to this method is

{
  "resultSequence": 1,
  "yourFeeInclVAT": 0
}

You cannot update the fee if the quote has been referred/instructed (INSTRUCTED), Expired (EXPIRED) or Removed (REMOVED).

The resultSequence must exist and yourFeeInclVAT is not optional and must be greater than or equal to 0.

The return from this method is the quote so that you can retrieve the updated totals.

Update Introducer References

This method will allow an Introducer to specify the references used for a quote. 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 quote (i.e. instructed, expired or removed).

The references placed on a quote will be removed once the quote has been instructed.

Remove quote

When this method the result sequences specified in the payload will be removed.

The payload for this method is

{
  "ResultSequences": [1]
}

The result sequences must be provided with at least once valid sequence number. The quote cannot be removed if it is already referred/instructed (INSTRUCTED) or Removed (REMOVED).

Update Owner

This method will allow an Introducer to assign a different owner to the instruction.

The owner is specified using a query string parameter

PUT https://api.themovingportal.dev/quote/TMP123456/assign?owner=joebloggs@myintroducer.com

The following values are valid for the owner

• None - Remove any owner
• IntegrationServiceAccount - Set the owner to the Integration Service Account - if one has been setup
• Owner - Email address - a valid email address of an active user at your firm. See Data service with code MYUSERS to get a list of users.

See Introducer owner for more information.

Example quote object

An example of a returned quote is below:

{
  "tmpReference": "TMP103243",
  "description": "RICS Home Survey - Level 3 (Building Survey) for Connie Booth",
  "createdTimestamp": "2024-06-21T13:03:34.0106172Z",
  "results": [
    {
      "sequence": 1,
      "quoteResultStatusCode": "SAVED",
      "productCode": "L3BUILDINGSURVEY",
      "fee": {
        "TOTALFEEINCLVAT": 735.00,
        "YOURFEEINCLVAT": 90.00
      },
      "allowedOperations": [
        "REFER",
        "REMOVERESULT",
        "ADJUSTFEE",
        "EMAIL"
      ],
      "expiryTimestamp": "2024-07-11T00:00:00Z"
    }
  ],
  "isVisibleToCustomers": false,
  "customers": [
    {
      "emailAddress": "conniebooth@themovingportal.dev",
      "title": "",
      "firstName": "Connie",
      "lastName": "Booth",
      "telephoneNumber": "07710 229 546",
      "receiveSMS": false
    }
  ],
  "property": {
    "propertyValueOrPurchasePrice": null,
    "propertyValueTierCode": "200KTO250K",
    "propertyValueTierDescription": "to £250,000",
    "propertyTypeCode": "TERRACED",
    "propertyTypeDescription": "Terraced",
    "propertyAgeCode": "FIFTYTOONEHUNDREDYEARS",
    "propertyAgeDescription": "50 to 100 years",
    "propertyAddressDescription": "No address",
    "propertyAddress": {
      "addressFormatCode": "NONE",
      "addressLine1": null,
      "addressLine2": null,
      "addressLine3": null,
      "addressLine4": null,
      "postcode": null,
      "countryCode": null
    },
    "correspondenceAddressDescription": "No address",
    "correspondenceAddress": {
      "addressFormatCode": "NONE",
      "addressLine1": null,
      "addressLine2": null,
      "addressLine3": null,
      "addressLine4": null,
      "postcode": null,
      "countryCode": null
    },
    "accessDetailsDescription": "No information",
    "accessDetails": {
      "accessTypeCode": "",
      "firmName": "",
      "emailAddress": "",
      "contactName": "",
      "telephoneNumber": ""
    }
  },
  "otherInformation": {},
  "allowedOperations": [
    "EDITPROPERTY",
    "REMOVEALLRESULTS"
  ],
  "configuration": {}
}