API for portals

# Register interest

# Getting the eligibility and priority fields

Before issuing a POST to register interest, it's advisable to determine which extra fields are required to check eligibility by sending a GET to /api/rest/portal/listings/{listing-id}/register-interest-fields.

This endpoint will return an object with two attributes: eligibilityFields and priorityFields. The first one will contain all the fields from the customer profile that are required to check the eligibility. These fields are mandatory when registering interest, otherwise the API will return a validation error. Possible values are:

  • annualHouseholdIncome
  • deposit
  • dateOfBirth
  • homePostcode
  • workPostcode
  • eligibleCitizen
  • homeOwnershipStatus

The second attribute, priorityFields, will contain all the fields from the customer profile that can be use to rank the customer when there are several applications to the same property. Unlike the eligibility fields, these fields are not mandatory but they are advisable to be send in the payload. Possible values are:

  • livingCircumstance
  • workingCircumstance
  • housingWaitingList
  • armedForcesMember
  • keyworker
  • dependants
  • hasDisability
  • homeOwnershipStatus

Example:

{
    "eligibilityFields": [
        "annualHouseholdIncome",
        "homeOwnershipStatus",
        "deposit",
        "dateOfBirth",
        "eligibleCitizen"
    ],
    "priorityFields": [
        "livingCircumstance",
        "dependants",
        "hasDisability"
    ]
}

If you want to get also the listing details in the same request, you can send a GET to /api/rest/portal/listings/{listing-id}/register-interest-full-details.

The response will contain an object with two fields: listing and registerInterestFields. The first one is object with the listing details, and the second an object with the two fields detailed above.

In the same way, if you want also get the listing details and one of its property details in the same request, you can send a GET to /api/rest/portal/listings/{listing-id}/properties/{property-id}/register-interest-full-details. In this case the response will contains, besides listing and registerInterestFields, the field property with the property details.

# Alternative endpoints

There are analogous alternative endpoints for scenarios where you use friendly urls and don't expose the id of the listings, but their slug.

To get which extra fields are required to check eligibility:

GET /api/rest/portal/listings/slug/{listing-slug}/register-interest-fields

To get also the listing details:

GET /api/rest/portal/listings/slug/{listing-slug}/register-interest-full-details

To get also the listing details and the property details:

GET /api/rest/portal/listings/slug/{listing-slug}/properties/{property-id}/register-interest-full-details

# Registering interest

To register the interest of a customer on a listing or specific property, issue a POST to /api/rest/portal/listings/{id}/register-interest.

There are basic cases when using this endpoint:

  1. The customer is already signed up (has a record in the database)
  2. The customer is not signed up (doesn't has a record in the database)

In the first case, the customer must sign in before register interest.

In the second case, you can send the email and password in the payload (password is not needed if the Portal is based on passwordless authentication), along with all the other form fields, to register the customer and at the same time, register interest on a listing or specific property.

You can send any customer field in the payload, but notice that the data you send will update the customer profile record. It's advisable to fill the form with the current customer profile data when displaying it.

Info

By default none of the fields used to check the eligibility are mandatory, unless the boolean parameter validate_eligibility is sent with value 1 or true.

In any case the eligibility is always going to be checked, but if any of the mandatory fields is not sent and the customer profile doesn't have the field either, the status will be incomplete.

The payload is basically the same used to register / update a customer, with some additional fields.

The listing id is part of the route, but if the customer is interested in a particular property, the property id must be send in the payload under the field property.

When the customer doesn't want to register interest in a specific property, you can send the field bedrooms containing an array with number of bedrooms the user is interested in, usually matching the criteria used in the search, and then when displaying the listing.

Neither the property nor the bedrooms are mandatory.

Info

UTM parameters are not mandatory, but if they are parsed from the visitor referral url, they should be passed in the payload to be used by the internal campaign tracking and attribution module.

{
  "email": "Customer email when you also want to register the customer.",
  "password": "Customer password when you also want to register the customer and password is needed to sign in.",

  "property": "Property id when the customer wants to register interest in a specific property from the listing.",
  "bedrooms": "Array with the number of bedrooms the user is interested in.",
  "additionalInfo": "Any additional information related to the application request, not to the customer.",

  "utmSource": "utm_source parameter value if applicable",
  "utmMedium": "utm_medium parameter value if applicable",
  "utmCampaign": "utm_campaign parameter value if applicable",
  "utmTerm": "utm_term parameter value if applicable",
  "utmContent": "utm_content parameter value if applicable",
  
  // PLUS, ANY OF THE CUSTOMER UPDATE FIELDS
}

Check the customer profile section to review all available fields related to the customer.

# Breaking down the process of registering interest

As by default the register interest form doesn't force to send any field, you can break down the process by sending some primary customer details and store the record; and then update the application to send more specific details.

There are two endpoints to update an application. The first one requires the customer to be previously signed-in, because it's accessible from a profile endpoint. The second one is a public endpoint (it doesn't require an authorization token), but it requires the additional field updateToken to be sent as part of the request payload. This field is returned in the response of the register interest request.

To use the second option issue a PUT to /api/rest/portal/applications/{applicationId} where applicationId is the id returned when registering interest. The request payload and additional query string parameters are the same explained in the section Update an application from the profile.

# Response

The API will respond with HTTP code 201 is the application was successfully created and the customer record was also successfully created or updated. The response will contain the application resource, that need to be interpreted to give the customer the decision of the application.

Field name Type Nullable Description
id number false Application reference id in the database
customer object false Object with the current customer details
available boolean false At this point, this will be always true, but when requesting applications in other scenarios, this could be false when the listing or the property is not available any more.
listing object false Object with the listing details, using the same object structure as the ones returned by the search.
property object true When the interest was on a specific property, an object with the property details.
enquiryDate string false Date-time when the customer requested their interest
additionalInfo string true Any additional information sent with the application
eligibilityStatus string false passed, considered, incomplete, not-checked or failed
isArchived boolean false true is the application was archived (by the customer himself or by a sales person)
decision object true When the application went through a checking process, some details about the decision. See its structure below.
appointments array false Collection of appointments related to the application.
nextAppointmentDateTime string true Date-time of the next upcoming appointment, if any.
updateToken string false Token to be used to update the application without requiring the customer to sign in first.
updatedAt string false Date-time when the application was updated for the last time
createdAt string false Date-time when the application was created in the database

# Decision

The decision object in the application has information, that could be of customer's interest. Find below its structure and some examples.

Field name Type Nullable Description
status string false Same as application eligibilityStatus
messages array false Array with all the reasons when failed. When considered or passed it can also contains descriptions about next steps.
successfulProperties array false Array with the listing properties id the customer is eligible for. When listing is single property, this collection will be always empty. Notice that when the customer registers interest for a specific property and he failed, this array can contain properties the customer is eligible for.

At this point, the eligibilityStatus will never have the value incomplete, but in some cases when the application source was not a portal, it could, and this is the same resource returned by the API to get customer applications. When incomplete, no decision was reached, because the eligibility was not checked.

Some examples:

...
"decision": {
    "status": "failed",
    "messages": [
        "Your annual household income is not enough.",
        "Your deposit is not enough."
    ],
    "successfulProperties": [
        15051,
        15054,
        15049,
        15047
    ]
},
...

...
"decision": {
    "status": "passed",
    "messages": [
        "One of our team will be in contact with you shortly."
    ],
    "successfulProperties": [
        17345,
        17349
    ]
},
...

# Validation errors

If there's any validation error, the API will respond with HTTP code 422, and an object with attributes message and errors. Message will contain a general description of the error, and errors will contain the list of errors related to each parameter.

# Duplication error

The API will prevent registering interest twice for the same property or for the same listing (if not property is specified). Although, there are some cases when it will be allowed, like for example, when the previous application failed and the new one passed. When it is considered a duplication, the API will respond with HTTP code 409, and the generic error message: 'There is already a previous application for the same property' or 'There is already a previous application for the same listing' depending on if the register interest is for a specific property or not.

It is important to deal with this case in a different way, because it is not a validation error. You can display the generic message or display a customized one, based on the fact that it is the only case when the API responds with HTTP code 409.

# Alternative endpoint

Similar to other cases, when you want to use friendly urls and don't expose the id of the listings, but their slug, you can use the endpoint:

POST /api/rest/portal/listings/slug/{listing-slug}/register-interest

GET /api/rest/portal/applications/{applicationId}/recommendations

This endpoint will return a non-paginated collection of the listings that share more similarities with the application listing and where the customer is eligible for and hasn't applied for them yet.

It allows the optional QueryString parameter size (default value is 3) to specify the maximum number of listings to return.

All responses are JSON encoded, and when the request is correct, the object will contain a unique field data, with the collection of listing details, using the same object structure as the ones returned by the search.

← Application form →