# Customer profile

Get the profile
Update profile
- Home ownership status
Change password
Change email
Managing favourites
Managing applications

Info

For all the endpoints related to the profile, you need to send the header Authorization with value Bearer {access_token}, otherwise an Unauthorized error message will be received.

# Get the profile

The endpoint to get the profile details is:

GET /api/rest/portal/profile

The resource will contain the following fields:

Field name	Type	Nullable	Description
`id`	number	false	Reference Id for the customer in the database
`email`	string	false	Customer email
`firstName`	string	true	Given and middle name
`lastName`	string	true	Family name
`fullName`	string	true	Concatenation of given, middle and family name
`phone`	string	true	Phone number
`dateOfBirth`	string	true	Date of birth using the format YYYY-MM-DD
`livingCircumstance`	object	true	Object with the `id` and `name` of the customer living circumstance
`homeLocalAuthority`	object	true	Object with the local authority details where the customer lives.
`homeAddress`	string	true	Address where the customer lives
`homePostcode`	string	true	Postcode where the customer lives
`workingCircumstance`	object	true	Object with the `id` and `name` of the customer working circumstance
`workLocalAuthority`	object	true	Object with the local authority details where the customer works.
`workAddress`	string	true	Address where the customer works
`workPostcode`	string	true	Postcode where the customer works
`occupation`	string	true	Occupation
`employerName`	string	true	Employer name
`annualHouseholdIncome`	number	true	Annual household income
`deposit`	number	true	Deposit or savings
`dependants`	number	true	total of dependants
`eligibleCitizen`	boolean	true	The customer has British or EU/EEA citizen
`homeOwnershipStatus`	number	true	Number from 1 to 4 with information about the home ownership status
`armedForcesMember`	boolean	true	The customer is a member of the armed forces
`hasDisability`	boolean	true	The customer has any known disability
`keyworker`	boolean	true	The customer is a key worker
`housingWaitingList`	boolean	true	The customer is in the council waiting list
`remarks`	string	true	Extra remarks
`buyingInterestPeriod`	object	true	Object with the `id` and `name` of the customer interest period to buy
`bestTimeToContactYou`	array	true	Collection of objects with `id` and `name`, referring to the best time to contact the customer
`privacyPolicyAccepted`	boolean	true	The privacy policy was accepted
`newsletterConsent`	boolean	true	The customer accepts receiving the newsletter, usually about relevant properties
`newsSurveysConsent`	boolean	true	The customer accepts receiving information relating to relevant news and surveys
`partnersOffersConsent`	boolean	true	The customer accepts receiving information and offers from chosen partners
`smsConsent`	boolean	true	The customer accepts receiving SMS
`whatsappConsent`	boolean	true	The customer accepts receiving WhatsApp messages
`updatedAt`	string	false	Date-time when the customer was updated
`createdAt`	string	false	Date-time when the customer was created

# Update profile

To update the customer profile, issue a PUT to /api/rest/portal/profile.

You can send any customer details in the payload, but you should only send the data you want to update. Fields with null or empty values will be reset to null, except firstName and lastName that are required if present.

{
  "title": "Customer title",
  "firstName": "Given names: required if present",
  "lastName": "Family name: required if present",
  "phone": "Phone number",
     
  "dateOfBirth": "Date of birth using the format YYYY-MM-DD",
  "bestTimeToContactYou": "Array of integers, matching the values in the corresponding lookup",
  "buyingInterestPeriod": "Integer matching one of the value in the corresponding lookup",

  "annualHouseholdIncome": "Annual household income",
  "deposit": "Deposit or savings",

  "livingCircumstance": "Integer matching one of the value in the corresponding lookup",
  "homePostcode": "Home post code: valid UK postcode",
  "homeAddress": "Home address",
  "dependants": "Integer indicating the total of dependants: it could be zero",

  "workingCircumstance": "Integer matching one of the value in the corresponding lookup",
  "workPostcode": "Work post code: valid UK postcode",
  "workAddress": "Work address",
  "occupation": "Occupation",
  "employerName": "Employer name",

  "armedForcesMember": "Boolean to indicate if the customer is a member of the armed forces",
  "keyworker": "Boolean to indicate if the customer is a key worker",
  "hasDisability": "Boolean to indicate if the customer has any known disability",
  "housingWaitingList": "Boolean to indicate if the customer is in the council waiting list",
  "homeOwnershipStatus": "Integer to indicate the current home ownership status. Check the possible Home ownership status valus and their meaning",
  "eligibleCitizen": "Boolean to indicate if the customer has British or EU/EEA citizen",

  "remarks": "extra remarks",
  
  "privacyPolicyAccepted": "Boolean to indicate the customer accepts the privacy policy",
  "newsletterConsent": "Boolean to indicate if the customer accepts receiving the newsletter, usually about relevant properties",
  "newsSurveysConsent": "Boolean to indicate if the customer accepts receiving information relating to relevant news and surveys",
  "partnersOffersConsent": "Boolean to indicate if the customer accepts receiving information and offers from chosen partners",
  "smsConsent": "Boolean to indicate if the customer The customer accepts receiving SMS",
  "whatsappConsent": "Boolean to indicate if the customer accepts receiving WhatsApp messages"
}

When creating new customers or when updating customers for the first time after being created by the passwordless registration process (where only the e-mail address was stored), UTM parameters can be sent in the payload to be used by the internal campaign tracking and attribution module.

{
  "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",
}

Info

Fields smsConsent and whatsappConsent are not used at all at the moment, but they are provided because it's planned to use them in the future.

# Home ownership status

There are 4 possible values for the home ownership status, which is a fixed set of values.

When sending or receiving this attribute, the numeric value is used.

value	Description label
1	The home seeker is a first time buyer
2	The home seeker doesn't own any property at the moment
3	The home seeker owns a property but it is currently in a selling process
4	The home seeker owns one or more properties

In the form presented to the home seeker to select the option, they should select the option that best fit their status.

When the selected Living circumstances has the flag owner in true, the first two 'home ownership status' options shouldn't be displayed, because they are no applicable.

# Change password

To change the customer password, issue a PATCH to /api/rest/portal/profile/change-password.

Besides the new password, the payload must contain the current password.

{
  "currentPassword": "current password",
  "newPassword": "new password"
}

# Change email

In some cases the customer would like to change the email address he is using to access his profile without losing any of his data.

To change the customer password issue a PATCH to /api/rest/portal/profile/change-email.

The payload should contain the current email, the new one and the customer password.

{
  "currentEmail": "Customer current email",
  "newEmail": "Customer new email",
  "password": "Customer password"
}

If everything was OK the API will respond with status code 200, otherwise an error message and the corresponding HTTP code will be returned.

# Managing favourites

Favourites are listings the customer could be interested on, but he doesn't want to register his interest yet. To use it, if a customer has signed in, you can display a favourite icon on the listing details page for the customer to add it to his list.

To know if a listing is in the list of customer's favourites issue a HEAD to /api/rest/portal/profile/favourites/{listing-id}. It will return HTTP code 200 if it is, otherwise it will return HTTP code 404.

To add a new listing to the collection of favourites issue a POST /api/rest/portal/profile/favourites, the payload object must contain the field listing, which is the listing reference id the customer wants to add to his favourites, example:

{
    "listing": 5353
}

If the favourite was added a HTTP code 201 will be returned, but the response body will be empty; otherwise an error message and the corresponding HTTP code will be returned.

To get the list of favourites use the following endpoint:

GET /api/rest/portal/profile/favourites

The respond will contain a unique field data, with the collection of listing details, using the same object structure as the ones returned by the search.

To remove a listing from the favourite issue a DELETE to /api/rest/portal/profile/favourites/{listing-id}.

# Managing applications

Applications are created every time a customer registers his interest for a listing, although they can come from other different sources, like external platforms and even created manually by a Housing Provider user or Estate Agent using the back-end App.

Customer should be able to manage his applications, which includes to archive them or book appointments.

To list all the customer applications send a GET to /api/rest/portal/profile/applications. This request will return the list of all the applications, no matter if they were archived or not, but this endpoints support the QueryString parameter archived, which you can use to get only archived applications, if sent with value 1 or true, or active applications, if sent with value 0 or false.

To retrieve a specific application send a GET to /api/rest/portal/profile/applications/{application-id}.

To archive an application issue a PATCH to /api/rest/portal/profile/applications/{application-id}/archive. Notice once an application has been archived, it cannot be returned to its active status.

Warning

When an application that has upcoming confirmed appointments is archived, all the appointments are automatically cancelled.

# Application fields

When requesting the list of applications, every element in the array will contain the following fields.

Field name	Type	Nullable	Description
`id`	number	false	Application reference id in the database
`available`	boolean	false	When the listing or the property is not available any more, this value will be set to false.
`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.
`additionalInfo`	string	true	Any additional information sent with the application
`eligibilityStatus`	string	false	`passed`, `considered`, `incomplete` 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.
`appointments`	array	false	Collection of appointments related to the application.
`nextAppointmentDateTime`	string	false	Date-time of the next upcoming appointment, if any.
`updatedAt`	string	false	Date-time when the application was updated
`createdAt`	string	false	Date-time when the application was created

Warning

This resource is similar to the one returned when registering interest, except that this one doesn't contain the details of the customer, because it's on the scope of a particular customer. Although, when requesting a single application it does contain that field.

# Update an application

Applications can be updated by issuing a PUT to /api/rest/portal/profile/applications/{application-id}.

You can send any customer field in the payload, but notice that the data you send will update the customer profile record.

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, although the eligibility is always going to be checked using the fields provided or the customer profile if any of the required fields are absent.

The payload is basically the same used to update the profile, but you can include the field additionalInfo is needed.

Warning

UTM parameters can also be sent, but they are only be stored if all UTM fields in the application record are empty.

{
  "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
}

The response will contain the application resource, the same way that when an application is created through the register interest process.

# Appointments

Next step after registering interest on properties, is booking an appointment for a viewing.

Viewings can be in-person, virtual or as part of an open day. The first two can be creating from the back-end by an agent, but if there are available open days, customers can book one of the available slot.

The normal flow should be to redirect customers to the available open days when they register interest on a property, for them to book a viewing, but they should also be able to cancel or re-book an appointment at any moment.

To get all the available appointments for an application make a request to:

GET to /api/rest/portal/profile/applications/{application-id}/available-appointments

The response will contain a collection of objects, any of them containing two fields:

date: The date of the open days
slots: All available slots, where every slot is composed by an id, a slotTime and a slotDurationMin.

This response usually contains none or a single entry, but several entries is also possible.

Example:

{
    "data": [
        {
            "date": "2021-03-03",
            "slots": [
                {
                    "id": 174,
                    "slotTime": "10:00",
                    "slotDurationMin": 30
                },
                {
                    "id": 951,
                    "slotTime": "12:00",
                    "slotDurationMin": 30
                },
                {
                    "id": 2076,
                    "slotTime": "15:00",
                    "slotDurationMin": 30
                },
                {
                    "id": 2417,
                    "slotTime": "15:30",
                    "slotDurationMin": 30
                }
            ]
        }
    ]
}

Once the customer has picked on slot, issue a POST to /api/rest/portal/profile/applications/{application-id}/appointments to book the appointment.

The payload must contain the slot id (slot) and if necessary a remark (remarks) from the customer. Notice it's not mandatory to send the field remarks.

{
    "slot": 2417,
    "remarks": "Anything the customer needs to tell"
}

If the appointment was booked, a HTTP code 201 will be returned and a resource with the new appointment. Notice that if the customer has an upcoming confirmed appointment for an application, he cannot book a new appointment, he need to change the appointment or cancel it first.

Field name	Type	Nullable	Description
`id`	number	false	Appointment reference id in the database
`type`	string	false	`in-person`, `virtual` or `open-day`
`dateTime`	string	false	Date-time of the appointment
`durationMin`	number	false	The estimated duration in minutes
`status`	string	false	`confirmed` or `cancelled`
`remarks`	string	true	Remarks
`updatedAt`	string	false	Date-time when the application was updated
`createdAt`	string	false	Date-time when the application was created

# Get application appointments

To get all the appointments for a specific application send a GET to /api/rest/portal/profile/applications/{application-id}/appointments.

# Get all customer appointments

To get all the appointment for the customer send GET to /api/rest/portal/profile/appointments. Notice that in this case, as you are getting appointments off the scope of an application, items will include the field application with the details of the application.

This endpoint supports the QueryString parameters upcoming. When sending with value 1 or true, the response will only contain upcoming and confirmed applications. When sending with value 0 or false, the response will only contain past and confirmed applications. When the parameter is not sent, all applications are returned, including the cancelled ones.

# Change an appointment slot

To change the slot of an appointment issue a PUT to /api/rest/portal/profile/appointments/{appointment-id}. Notice that you should display all the available appointment first, for the customer to pick one of the available slots.

The payload is similar to the one use when booking a new appointment:

{
    "slot": 2076,
    "remarks": "Anything the customer needs to tell"
}

If the appointment was successfully updated, a HTTP code 200 will be returned.

# Cancel an appointment

To cancel an appointment issue a PATCH to /api/rest/portal/profile/appointments/{appointment-id}/cancel. Notice once an application was cancelled, it cannot be reverted, the customer will need to book a new appointment.

← Sign up and Sign in Search listings →