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.

Obtaining an Access Token

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

Example Response

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

Important Notes

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.

Making API Requests

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.

Subscribing to webhooks

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.

Supported Events

Final Report is generated

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"

Reference Form 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"

Outcome Sections updated

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"

Webhook payload

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.

• Sandbox Referencing API

• Live Referencing API

Guarantor Collection

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, 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.

When to use it

Set guarantorCollection.required = true on the applicant subject when:

• The tenant's stated income may not meet the standard affordability threshold and a guarantor is needed to support the application
• Your agency requires a guarantor as standard for certain product tiers or properties
• The tenant has volunteered to provide a guarantor

Setting the collection on creation (PUT)

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:

• The applicant is created in Pending Submission
• A "guarantor required" email is sent to the tenant
• A guarantor recommendation is attached to the applicant

The 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.

Updating the collection on an existing applicant (PATCH)

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.

Removing the requirement

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 reference

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.

Affordability ratio overrides

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.

Constraints

• guarantorCollection can only be set on subjects with type: applicant. Sending it on a guarantor subject returns a 400 Bad Request.
• All three fields (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.

Related

• Guarantor only referencing - flow for guarantor-only references (tenant has product: None)
• Glossary - core concepts including Affordability Ratio and Price Share

Guarantor only referencing

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:

• Pending Submission - The applicant has not completed referencing yet.
• In Review - The application is being reviewed by one of our Referencing Executives.
• Awaiting Response - Following the completion of the applicant's bot journey, if Goodlord requires additional information from the applicant, they will be contacted and their outcome will move to this state.
• Accepted - The applicant has met our referencing criteria.
• Rejected - The applicant has not met our referencing criteria
• Cancelled - The applicant's referencing has either expired due to them being inactive or the application has been deleted.

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.

Conditional Pass and Conditions Met: Explained

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.

ID

An ID check will come back as a conditional pass if:

• The ID is not supplied or is invalid
• The ID does not comply with the right-to-rent guidelines (England only)
• There is no proof of name change
• No photo ID has been provided

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.

Credit check

A credit check will come back as a conditional pass if:

• The declared active CCJ totals less than £1,000.
• The declared satisfied CCJ totals between £1,000 to £5,000.
• The bankruptcy or IVA is satisfied within 1-6 years.
• The tenant could not be located on the electoral roll.
• The tenants live outside the UK.

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 report section updated to show as Conditions Met.

Income

An income check will come back as a conditional pass if:

• The tenant is a student.
• The tenant does not meet our affordability ratio (2.5 x the annual rent or 3.0 x for a guarantor).
• The tenant has been self-employed for fewer than twelve months and does not have a submitted tax return form.
• The tenant is unemployed.
• The employer has not verified the income.
• The tenant has not provided the necessary documents to verify their income.

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.

Residential

A residential check will come back as a conditional pass if:

• The rent was paid late
• The tenancy could not be verified
• There is minor damage to the property.

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.

Overriding a 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:

• System - Automatically generated messages by the Goodlord system
• Person - Comments made by referencing executives (internal Goodlord staff)
• Agent - Comments made by letting agents

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:

• type: The type of author (system, person, or agent) - this is the primary field
• id: Internal Goodlord identifier, only present for authors of type "person" (referencing executives)
• email: Email address, only present for authors of type "agent"

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 circustances. These can be overriden when creating a subject by managing Subject.Context.CommunicationPreferences.
The default communications happen when:

• When an applicant (tenant or guarantor) or a referee is created in our system we will send them the initial referencing email containing the link to our bot journey. (provided that sendInitialTenantEmail is set to true)
• When the applicant's email is changed, we will assume the original one was incorrect and re-send the initial referencing email (again, provided that sendInitialTenantEmail is set to true)
• If the applicant has not completed their referencing we will send them daily reminders (Monday-Friday). Daily reminders expire after 7 days as the reference will be closed as unverified.
• If one of our Referencing Executives identifies that further information is required, they will be sent an email requesting the appropriate information.

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:

  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`. <br>

These are:

• Pending Submission - The applicant has not completed referencing yet.
• In Review - The application is being reviewed by one of our Referencing Executives.
• Awaiting Response - Following the completion of the applicant's bot journey, if Goodlord requires additional information from the applicant, they will be contacted and their outcome will move to this state.
• Accepted - The applicant has met our referencing criteria.
• Rejected - The applicant has not met our referencing criteria
• Cancelled - The applicant's referencing has either expired due to them being inactive or the application has been deleted.

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.

  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:

  An applicant may receive emails from Goodlord under various circustances. 

These can be overriden when creating a subject by managing Subject.Context.CommunicationPreferences.
The default communications happen when:

• When an applicant (tenant or guarantor) or a referee is created in our system we will send them the initial referencing email containing the link to our bot journey. (provided that sendInitialTenantEmail is set to true)
• When the applicant's email is changed, we will assume the original one was incorrect and re-send the initial referencing email (again, provided that sendInitialTenantEmail is set to true)
• If the applicant has not completed their referencing we will send them daily reminders (Monday-Friday). Daily reminders expire after 7 days as the reference will be closed as unverified.
• If one of our Referencing Executives identifies that further information is required, they will be sent an email requesting the appropriate information.

The list of emails sent to each applicant can be retrieved by calling /referencing/subject/{subjectId}/emails.

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:

• System - Automatically generated messages by the Goodlord system
• Person - Comments made by referencing executives (internal Goodlord staff)
• Agent - Comments made by letting agents

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:

• type: The type of author (system, person, or agent) - this is the primary field
• id: Internal Goodlord identifier, only present for authors of type "person" (referencing executives)
• email: Email address, only present for authors of type "agent"

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