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.
When a tenant's referencing requires a guarantor (for example because they don't meet the standard income affordability threshold), you can signal this to Goodlord by setting a guarantorCollection on the applicant subject. Goodlord will trigger the guarantor collection workflow: a recommendation is added to the applicant, and a "guarantor required" email is sent to the tenant inviting them to provide guarantor details. The guarantor subject is then created either by the tenant via the bot journey, or by you via a follow-up Create Subject call.
This is distinct from Guarantor only referencing (see the Getting Started tab), where the entire reference is for the guarantor and the tenant is a "shell" with product: None. The guarantor collection flow is for the standard case where Goodlord references both the tenant and the guarantor.
Set guarantorCollection.required = true on the applicant subject when:
Include guarantorCollection inside context when calling Create Subject for the applicant:
{
"type": "applicant",
"attachedSubjects": [],
"context": {
"firstName": "Sarah",
"lastName": "Hughes",
"mobile": "07123456789",
"email": "sarah.hughes@test.com",
"product": "Pro",
"guarantorCollection": {
"required": true,
"product": "Pro",
"affordabilityRatio": 3.0
}
},
"rentalDetails": {
"priceShare": 1200,
"affordabilityRatio": 2.5
}
}
After this request:
Pending SubmissionThe guarantor subject itself is created later, either when the tenant submits guarantor details via the bot journey or when you make a follow-up Create Subject call with type: guarantor linking to the applicant.
To add or change a guarantor requirement on an applicant that already exists, use Patch Subject:
{
"context": {
"guarantorCollection": {
"required": true,
"product": "Pro",
"affordabilityRatio": 3.0
}
}
}
PATCH replaces the entire stored guarantorCollection. Every field is overwritten with what you supply; there is no partial merging. The three fields (required, product, affordabilityRatio) must always be supplied together.
If a tenant no longer needs a guarantor, PATCH the applicant with required: false:
{
"context": {
"guarantorCollection": {
"required": false,
"product": "Pro",
"affordabilityRatio": 3.0
}
}
}
This expires any active guarantor recommendations on the applicant and stops further "guarantor required" reminders. Existing guarantor subjects already on the application are not affected by this change. To remove an existing guarantor subject, delete it directly via Delete Subject.
| Field | Type | Required | Notes |
|---|---|---|---|
required |
boolean | Yes | true to require a guarantor; false to remove the requirement |
product |
string | Yes | The referencing product the guarantor will go through. One of Pro, Essential, Priority, Corporate |
affordabilityRatio |
number | Yes (>= 1) | Minimum income-to-rent multiplier the guarantor's income must satisfy. Typically 3.0 |
All three fields are required whenever you provide a guarantorCollection. The guarantorCollection object itself is optional on the applicant. Omit it if no guarantor is needed.
API consumers always operate within a company that has a pre-configured guarantor affordability ratio (GuarantorAffordabilityRatio) registered with Goodlord. That configured value will silently replace the affordabilityRatio you supply in guarantorCollection before storage. The supplied value is accepted (the request returns 200) but the company-configured value is what drives the actual referencing decision and is what you'll see returned on subsequent GET requests for the subject.
The same applies to the tenant's own rentalDetails.affordabilityRatio: the company's pre-configured TenantAffordabilityRatio will replace any value you supply.
If you see a different affordabilityRatio on the stored subject than what you sent, this is the reason. To confirm or change your company's configured value, contact your Goodlord account manager.
guarantorCollection can only be set on subjects with type: applicant. Sending it on a guarantor subject returns a 400 Bad Request.required, product, affordabilityRatio) must be supplied together when guarantorCollection is present.affordabilityRatio must be >= 1. Values below 1 are rejected with a 400.product must be one of the four publicly supported guarantor products: Pro, Essential, Priority, Corporate.product: None)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
}
}
After the subject (the tenant or guarantor) has completed their initial referencing submission, they will move into one of the following states in Subject.Outcome.
These are:
Please note: a subject can move between these depending on the information they have provided. They go from in.review and then awaiting.response, when the referencing team require further details.
For an example Get Subject response in each outcome, including conditional passes, see Sandbox Test Responses.
Referencing reports will show as a pass, a conditional pass, or a fail. For some situations, a Conditional Pass can be updated to a Conditions Met. We’ll cover that in the second part of this guide. If a report is a conditional pass, Goodlord recommends that the tenant pays the rent upfront, secures a suitable guarantor, or is not liable for the rent (i.e permitted occupier). There are several reasons why a report might be a conditional pass.
An ID check will come back as a conditional pass if:
The full list of acceptable, Right to Rent-compliant documents can be found at gov.uk.
The condition of the ID section will always be to review the ID in person and to update the platform. Once you have seen the ID in person to corroborate that it belongs to the person who is being referenced, you are able to have the report section updated to show as Conditions Met.
A credit check will come back as a conditional pass if:
If a tenant cannot be located on the electoral roll or lives outside of the UK, you can confirm the credit check by looking at documents that show proof of address (e.g. a bank or utility statement). Once you have seen suitable proof of address, you are able to have the Credit section updated to show as Conditions Met, with confirmedProofOfAddress. This doesn't change the Residential section.
Proof of address can't meet the condition for a CCJ, bankruptcy or IVA. Those need a guarantor, or the tenant not being liable for the rent, and the API refuses proof of address when the subject has adverse credit. To tell the cases apart from Get Subject, offer proof of address only when all of these hold:
Conditional Pass;context.credit.confirmations.confirmationStatus is NotConfirmed, meaning the credit file confirmed neither the tenant's identity nor their residency;context.credit.adverseCreditList.An income check will come back as a conditional pass if:
The conditions that might be applied to the financial section of referencing include the tenant being required to have a guarantor, the tenant not being liable for rent or the combined affordability for the remaining tenants meeting the overall cost of the rent for the tenancy. Once these conditions have been met, there is no need to notify us of this on the Goodlord platform. The reference report will remain with an overall conditional pass.
A residential check will come back as a conditional pass if:
Find out more about our referencing process from our criteria-related articles. The possible conditions for the residential section include adding a guarantor to the tenants or the tenant not being liable for the rent (Added as a permitted occupier rather than a tenant). Once the condition has been met, you do not need to notify us of this. The reference report will remain with an overall conditional pass.
Once the conditions for ID and Credit have been met, the public API has the capability for a user to inform Goodlord, at which point a report for that particular tenant or guarantor will be updated, and the new report sent back to you. This is explained in the Patch-Subject-Outcome-Conditions sections
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 createdAt field is an ISO 8601 timestamp in UTC (e.g. 2024-10-01T14:35:12.189Z). The Z suffix indicates Coordinated Universal Time (UTC).
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"
}
]
The way in which Touchpoints differ from Milestones is that:
Touchpoints act as internal notes and communications to provide additional context around certain stages of the applicants referencing.Milestones are timestamps of different points in the applicant's referencing journey, from the subject's creation, to the completion of each section and the entire referencing journey.Example - Subject Created
{
"type": "event",
"event": "subject.created",
"createdAt": "2026-01-01T09:00:00.000Z",
"updatedAt": "2026-01-01T09:00:00.000Z",
}
Example - Subject began referencing
{
"type": "event",
"event": "subject.startedApplication",
"createdAt": "2026-01-01T09:10:00.000Z",
"updatedAt": "2026-01-01T09:10:00.000Z",
}
Example - Subject finished providing proof of identity
{
"type": "event",
"event": "subject.section.identity.completed",
"createdAt": "2026-01-01T09:15:00.000Z",
"updatedAt": "2026-01-01T09:15:00.000Z",
}
Example - Subject completed entire bot journey
{
"type": "event",
"event": "subject.journey.complete",
"createdAt": "2026-01-01T09:20:00.000Z",
"updatedAt": "2026-01-01T09:20:00.000Z",
}
Example - Subject's outcome was determined as Accepted
{
"type": "FinalOutcome",
"event": "subject.accepted",
"createdAt": "2026-01-01T09:30:00.000Z",
"updatedAt": "2026-01-01T09:30:00.000Z",
}
An applicant may receive emails from Goodlord under various circumstances.
These can be overridden when creating a subject by managing Subject.Context.CommunicationPreferences.
The default communications happen when:
sendInitialTenantEmail is set to true)sendInitialTenantEmail is set to true)The list of emails sent to each applicant can be retrieved by calling /referencing/subject/{subjectId}/emails.
The date field in each email record is an ISO 8601 timestamp in UTC (e.g. 2025-10-01T12:34:56.789Z). The Z suffix indicates Coordinated Universal Time (UTC).
Note: emails to referees. Emails sent to a referee (an employer, accountant or landlord giving a reference) are recorded against the referee, not the applicant, so they don't appear in the applicant's list. To see them, take the referee's id from the applicant's Get Subject response (context.incomes[].referee.id, or context.addresses[].referee.id for a landlord) and call Get Subject Emails with that id.
To stop the reminders, delete the applicant with Delete Subject. Do this whenever an applicant won't go ahead: the tenancy fell through, they withdrew, or they were added by mistake or twice. Their outcome becomes Cancelled, and the reminders to them and to their referees stop. To cancel a whole tenancy, use Delete Application, which cancels every tenant and guarantor on it.
Deleting a tenant doesn't cancel their guarantor, so delete the guarantor too. Setting sendInitialTenantEmail to false turns off only the first email, not the reminders.
Deleting applicants who won't go ahead is a requirement for going live, and we check it with you during UAT. We don't send reminders to tenants or guarantors in the Sandbox, so check there that the deleted subject's outcome is Cancelled.
There are different types of documents used to reference an individual.
Documents are stored in Subject.Context.Documents.
The available document types and the category each relates to are in the following table:
| Document Type | Category | Additional Info |
|---|---|---|
| Passport | Identity | Government-issued passport confirming identity and nationality. |
| Driving license | Identity | Driving licence used as proof of identity. |
| Student ID | Identity | Educational institution–issued ID confirming student status. |
| Identity card | Identity | General identity card used to verify personal identity. |
| UK Home Office Registration Cert | Identity | Official UK Home Office document confirming immigration and/or residency status. |
| UK Immigration Status Document | Identity | Document evidencing an individual’s legal immigration status in the UK. |
| EU Identity card | Identity | National identity card issued by an EU member state. |
| Selfie | Identity | Live facial image used for identity verification and fraud prevention. |
| Other identity document | Identity | Alternative identity document not covered by standard identity types. |
| Credas Report | Identity | Third-party identity and credit verification report from Credas. |
| Credas PEPs and Sanctions Report | Identity | Credas report checking politically exposed persons and sanctions lists. |
| additionalidentitydocument | Identity | Supplementary identity documentation provided when standard documents are insufficient. |
| taxReturn | Income | Official tax return showing declared income for a given period. |
| bankStatement | Income | Bank statement used to evidence income. |
| payslip | Income | Payslip confirming salary payments. |
| signedContractOfEmployment | Income | Signed employment contract confirming role, salary, and employment terms. |
| awardDocument | Income | Documentation evidencing awarded income, such as grants or stipends. |
| AdditionalIncomeDocument | Income | Supplementary documentation supporting additional income sources. |
| Proof of Address | Residential | Document confirming an individual’s residential address. |
| additionalresidentialdocument | Residential | Supplementary residential documentation supporting proof of address. |
| additionalCreditdocument | Credit | Supplementary credit-related documentation provided to support a credit assessment. |
| additionalDocument | Other | Additional supporting document not covered by a specific category. |
| Other | Other | Catch-all document type for uncategorised or miscellaneous files. |
| Individual Report | Output Report | Individual assessment or output report generated during processing. |
| Landlord Report | Output Report | Report generated for landlords summarising referencing outcomes. |
| Reference Report | Output Report | Report containing reference checks and verification results. |
No real checks take place in the Sandbox, so a test applicant only reaches an outcome when Goodlord sets one. You don't have to wait for that to build and test your integration. The API reference has an example response for each outcome below, taken from Sandbox applicants and anonymised. You can read them in the docs, or serve them from a mock API on your own machine.
Open Get Subject and pick one from the Response Example list.
| Example | outcome.status |
Sections that aren't Accepted | What to look at |
|---|---|---|---|
| Outcome - Accepted | Accepted | None | The last milestone is the final outcome. |
| Outcome - Accepted with Income Conditional Pass | Accepted | Income: Conditional Pass | context.incomeSummary.meetsAffordability is false, and a guarantor is in attachedSubjects. |
| Outcome - Accepted with Credit Conditional Pass (proof of address) | Accepted | Credit: Conditional Pass | context.credit.confirmations.confirmationStatus is NotConfirmed and there's no adverseCreditList, so proof of address can meet the condition. |
| Outcome - Accepted with Credit Conditional Pass (CCJ) | Accepted | Credit: Conditional Pass | A satisfied CCJ in context.credit.adverseCreditList. Proof of address can't meet this condition. |
| Outcome - Accepted with Identity Conditions Met | Accepted | Identity: Conditions Met | The agent confirmed they'd seen the ID in person. |
| Outcome - Accepted after Open Banking request | Accepted | Credit: Conditional Pass | A completed openBankingRequest in recommendations. Its touchpoints are the Get Subject Touchpoints example. |
| Outcome - Rejected (adverse credit) | Rejected | Income: Conditional Pass, Credit: Rejected | An active CCJ in context.credit.adverseCreditList, and a guarantor in attachedSubjects. |
| Outcome - Rejected (inconsistencies) | Rejected | All four: Rejected | Each section's reason is in its touchpoint. |
| Outcome - Cancelled | Cancelled | No sections | The applicant was deleted before starting their form: outcome.sections is empty and the last milestone is subject.cancelled. |
| Outcome - Guarantor Accepted | Accepted | Credit: Conditional Pass | type is guarantor. It's the guarantor of the Income Conditional Pass example, which is in its attachedSubjects. |
| Outcome - Guarantor Rejected | Rejected | Identity and Income: Rejected | The guarantor of the Rejected (adverse credit) example. |
The examples are trimmed for reading. Milestones run to the applicant completing their form, then show only the latest final outcome, so a real subject can have more.
Get Subject Touchpoints has one example from a Sandbox applicant, Example 3 - Sections and an Open Banking request. It shows touchpoints newest first and a message for each section. It also shows both kinds of author: system, and a person (with an id) asking for an Open Banking connection, followed by the system message once income was confirmed. The messages are for people to read, so show them as they are. Base your logic on outcome.sections in Get Subject.
To call these examples from your own code, run Prism against the Sandbox API definition. It needs Node.js.
npx @stoplight/prism-cli@5.16.0 mock "https://portal.goodlord.co/portal/catalogue-products/referencing-product-1/dHlrL3Byb2Qtc2FuZGJveC1yZWZlcmVuY2luZy1hcGk/docs/download"
The mock listens on http://127.0.0.1:4010. Choose a response by sending the example's name in a Prefer header:
curl http://127.0.0.1:4010/referencing/subject/00000000-0000-0000-0000-000000000000 \
-H "Authorization: Bearer test-token" \
-H "Company-ID: 00000000-0000-0000-0000-000000000000" \
-H "Prefer: example=Outcome - Accepted with Income Conditional Pass"
The mock checks requests against the API definition, so send an Authorization header and a Company-ID that's a UUID. If either is missing or invalid, you get the 400 example (PropertyIsInvalid) instead. Without a Prefer header the mock returns the endpoint's first example.
The mock returns examples only. It accepts any token and subject ID, keeps no state between calls, and sends no webhooks. Before you go live, test the full flow in the Sandbox: create applicants, complete their forms, and send us their subject IDs with the outcome you'd like each to have.