Allows you to access our Referencing API to create and manage your references.
Read Getting Started with Goodlord's Referencing API for a quick walkthrough to get started with our Referencing API.
Read Understanding Goodlord's Referencing API for information about the various terms in the Referencing API.
Goodlord's APIs use OAuth 2.0 Machine-to-Machine (M2M) authentication to ensure secure access. This process involves your client application (the machine) authenticating with Goodlord's authorization server using a Client ID and Client Secret to obtain an access token. Once obtained, this token must be included with each API request to access Goodlord's resources. The resource server will validate the token, ensuring that only legitimate requests are granted access, maintaining secure and authorised interactions.
To retrieve an access token, send a POST request to Goodlord's auth/token endpoint. Below is an example request using curl to Goodlord's sandbox environment:
curl --location 'https://api-sandbox.goodlord.co/auth/token' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "<<Your Client ID>>",
"client_secret": "<<Your Client Secret>>",
"grant_type": "client_credentials"
}
Upon a successful request, the authorization server will respond with a JSON object containing the access token and additional metadata:
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "<<Your access token>>",
"scope": "free_plan referencing_product"</pre>
}
Token Expiration: The access token is valid for 3600 seconds (1 hour). Once expired, you will need to request a new token by repeating the authentication process.
Token Format: The access token is issued in JWT (JSON Web Token) format.
After obtaining the access token, include it in the
Authorization header for subsequent API requests. You should also include the Company ID that was issued to you in the Company-ID header. For example, to
call the referencing/application endpoint:
curl --location 'https://api-sandbox.goodlord.co/referencing/application' \
--header 'Authorization: Bearer <<Your access token>>' \
--header 'Company-ID: <<Your Company ID>>' \
--header 'Content-Type: application/json' \
--data '{}'
Ensure that the access token is properly included in the
Authorization header for all API requests to authenticate and
authorise your actions.
Goodlord supports webhook notifications to keep you informed of important events related to an individual subject's referencing process.
Please contact us if you would like to subscribe to webhook events.
When requesting access to an account, you must let us know which events you wish to subscribe to and what endpoints you would like us to call when the event happens within our system.
This event is triggered when a final report has been generated for the applicant or guarantor. In this case, you can assume the referencing decision is final. You could use this event to notify your system when everything is completed.
Represented by event.name of "V2.subject.report.generated"
This event is triggered when the reference form has been generated. This form is a document which represents some basic information which the applicant has provided and is created at the point they complete the referencing journey.
Represented by event.name of
"V2.subject.reference.form.generated"
This event is triggered whenever an outcome.section changes its status. If you needed to know when a section moves to Accepted/Rejected, then this would be the event you hook into.
Represented by event.name of "V2.subject.outcome.updated"
The webhook payload will look like the below:
{
"referer": "111",
"context": {
"source": {
"name": "vouch",
"version": "2"
},
"event": {
"name": ""V2.subject.outcome.updated",
"version": "1",
"timestamp": "1623316665"
}
},
"data": {
"customerId": "<guid>",
"applicationId": "<guid>",
"subjectId": "<guid>",
"type": "guarantor"
}
The customerId, applicationId and
subjectId within the data object will allow you to then make
requests for this specific Subject to any API endpoints you require, in
response to receiving the webhook back from us.
With the Goodlord Referencing API we support guarantor only referencing.
When creating guarantors using the Goodlord Referencing API we require that a guarantor is always associated with a tenant.
This makes the guarantor only referencing journey slightly unusual as it requires sending details about a tenant that we will not be referencing. We refer to this type of tenant as the 'shell'.
In order for us to know that this tenant should not be referenced we require the tenant's product to be set to a value of None (see full example tenant subject below).
In this use case, despite the reference being for the guarantor, we require you to create a tenant 'shell' that represent who the guarantor is responsible for. This tenant 'shell' will only require you to provide the most basic details (required fields are detailed below). When you create the guarantor you wish to send to referencing you will then need to link the guarantor to the tenant using the relatedSubjects field.
The linking of a tenant to guarantor is the same process you would use if you were following the more typical guarantor & tenant referencing use case.
Goodlord will NOT perform a reference for this Tenant 'shell' and Goodlord will NOT send any emails to the tenant.
The guarantor will be able to follow the standard referencing journey.
The following examples for the Create Subject endpoint to support this use case.
Example 1 - Creating a tenant 'shell'
{
"type": "applicant",
"attachedSubjects": [],
"context": {
"firstName": "None",
"lastName": "Product",
"mobile": "07123456789",
"email": "test-no-product@test.com",
"product": "None" // Critical: this prevents Goodlord referencing this Tenant
},
"rentalDetails": {
"priceShare": 100,
"affordabilityRatio": 2.6
}
}
Example 2 - Subject payload to create the guarantor we should reference.
{
"type": "guarantor",
"attachedSubjects": [{
"id": "4d2d905f-8730-4d71-ae7c-xxxxxxxx", // tenant shell's subject ID
"type": "applicant"
}],
"context": {
"firstName": "Guarantor",
"lastName": "Pro",
"mobile": "07123456789",
"email": "test-pro-product@test.com",
"product": "Pro"
},
"rentalDetails": {
"priceShare": 1200,
"affordabilityRatio": 3.0
}
}
When an application is going through referencing, we provide updates for noticeable changes or advancements in the process. These are called touchpoints, and they're a valuable way of keeping you informed and making our product more self-serve. Touchpoints begin once an applicant has submitted their reference and they finish when a final outcome has been given.
With the Goodlord Referencing API you can retrieve touchpoints for a referencing applicant using the Get Subject Touchpoints endpoint.
These comments are created for each section [identity, residential, income, credit (stated as category)] of referencing and can be authored by:
Each touchpoint response includes a subjectId field which is the unique identifier for the referencing applicant.
The author object contains information about who created the touchpoint:
The following shows example responses from the Get Subject Touchpoints endpoint:
System Type Example - Automatically generated system message:
[
{
"id": "78230093-8035-4aad-81db-9221cd5019a0",
"subjectId": "a6770136-63f0-4315-9d9e-3700329a4b91",
"category": "residential",
"author": {
"type": "system"
},
"message": "We're awaiting additional information from applicant.",
"createdAt": "2024-10-01T14:35:12.189Z"
}
]
Person Type Example - Comment from a referencing executive:
[
{
"id": "6e10af0c-ae9c-4c80-ac09-aa9f253d5f97",
"subjectId": "a6770136-63f0-4315-9d9e-3700329a4b91",
"category": "income",
"author": {
"id": "df603e71-0e12-4ad3-b13b-02225563ac85",
"type": "person"
},
"message": "As the applicant has recently started employment we are not able to accept the reference on this occasion",
"createdAt": "2024-10-02T09:20:33.456Z"
}
]