These docs are for v2.5. Click to read the latest docs for v3.0.

Rental Recognition

You can now retrieve, create and delete rental recognition records for users using the Moneyhub API.

What is Rental Recognition

Rental recognition allows individuals to boost their credit score and have regular payments for their rent recognised to facilitate applications for further credit. It was launched by the government in 2017 as detailed by their new story FinTech to help renters get on the housing ladder

Moneyhub partners with the Credit Reference Agency to submit statements of rental agreements based on Open Banking connections.

Rental records are created by associating information from the tenancy agreement with a regular transaction series containing rental transactions. Please refer to Regular Transactions page for more information.

📘

Prerequisites:

  • To retrieve rental records, the rental_records:read scope is required
  • To create or delete the rental_records:write scope is required
  • The user must have no existing rental records
  • A valid transaction series ID is required to create a rental record

Endpoints

GET /rental-records

This endpoint retrieves the rental record for the user.

The consentApprovedAt property on the rental record indicates if the user has consented to submit the record.

The lastSubmittedAt property is a date when the service last submitted the record.

POST /rental-records

This endpoint creates a rental record for the user.

The tenancyStartDate is the start date of the tenancy agreement; this is likely the day the individual moved into the property. It must be before the second payment in the associated regular series.

This endpoint will return an error if the user has an existing rental record.

🚧

Rental amount

The rentalAmount.value should be less than or equal to the sum of recurring transactions for the rentalFrequency, e.g. monthly. If the rental amount is more than the regular series, the service will mark the rent as unpaid. For example, if a user creates a rental record for £500pcm and the regular series was £499.99pcm, the service would not recognise the rent as paid.

DELETE /rental-records/{rentalId}

This endpoint deletes a rental record. It returns an empty body.

Consent flow

Once a rental record exists for a user, that user will need to consent to submit this data. The consent flow for rent recognition differs slightly from other consent flows such as banking connections. Once the user has provided consent, the service will update the rental record, and the user will be redirected straight back to the client redirect URL. The process is as follows:

1. Create an authorisation URL for the user

An authorisation URL needs to be created with the id:experian scope. This identifies the authorisation as being for rental recognition consent. An example URL to trigger this consent process can be found below:

http://identity.moneyhub.co.uk/oidc/auth?client_id=client-id&scope=id%3Aexperian%20openid&response_type=code&redirect_uri=http%3A%2F%2Fclient-redirect-url.com&state=foo&nonce=bar&prompt=consent&request=jwt.request.object

Notice in the above URL that the scope parameter includes the id:experian scope. The redirect_uri must be the one registered on the API client. The request query parameter is a JSON web token that contains information about the request. An OpenID Connect library can generate this; however, the simplest way is to use the Moneyhub API client (Node.js). An example for this is below:

const url = await moneyhub.getAuthorizeUrlForCreatedUser({
	userId: user_id,
  state: "foo",
  bankId: "experian",
  nonce: "bar",
})

For more information on how to use the getAuthorizeUrlForCreatedUser method, see the API client documentation.

Please see Authentication page for more information on the consent flow process.

2. User consents

The user is presented with a consent screen (below) that they need to approve.

564

A screenshot showing an exemplar rental consent screen

3. User is redirected to Client redirect URL

Once approved, the user redirected to the client redirect URL with the state and rentalId of the rental that was consented, e.g. https://redirect-url?state=state&rentalId=rental-id

Submission to credit reference agencies

Currently, rental agreements are only submitted to Experian as part of The Rental Exchange. Moneyhub is looking to partner with other organisations that recognise rent. If you need to submit rental records to a specific organisation, please reach out to discuss.

Experian Rental Exchange

Unlike landlords, letting agencies and housing associations, Moneyhub uses Open banking to derive confidence in the rental agreement's validity and its current state of arrears. We, therefore, use the requirements of Open banking based recognition.

Submission

The submission is directly provided to Experian through their secure file sharing portal. The name of the submitting organisation is agreed upon before the clients first submission, and the service will make no submissions until it is agreed.

📘

Submission to Experian

If you want to submit a rental record directly to Experian, you will need to enter into a bilateral agreement with Experian.

Processing

On the 6th of each month, the service parses all rental records creating a report detailing the state of each record. Using both Moneyhub's and Experian's requirements, a record will be assigned one of six statuses for that month:

  • Not finalised
    When a user has not consented for the details of the rental agreement and their transactions to be shared
  • Tenancy start date not before the snapshot date
  • Fewer than 6 payments in the regular series
    Six payments are required in the series that underlays the rental record. If there are fewer than six, the record is not submitted to Experian.
  • Transactions did not sum to the expected minimum
    Using all the transactions that occurred in the month before the snapshot, it would appear that the agreement is currently in arrears.
  • Transactions did not sum to the expected minimum - more transactions were available
    To account for non-working days, we select the number of transactions expected for the period (one for monthly, four for weekly etc.) If more transactions within the period were excluded from this filter, this status allows review before submission.
  • Submitted
    The rental agreement currently has no arrears and is part of the submission for that month.

Further validation

The report and the extract are reviewed and validated before submission. Considerations are given for over 75 data quality checks and 20 legitimacy checks to ensure submissions are true and accurate. If a record does not satisfy further validation, the service will withhold the record from submission.

Impact on the user's credit file

Data is only considered when the individual signs up and not historical it can take six months to achieve the highest benefit.

The individual's credit history will improve after two months of sharing data but will reach the maximum benefit at six months.

Rent isn’t taken into account at the moment for Experian product ‘Boost’.