Goodlord
Goodlord Referencing API

Goodlord's public Referencing API — the production surface of the Referencing Product listed in the public catalogue of the Goodlord Developer Portal. It lets a lettings agency's own system create rental applications, add and assess Applicants and Guarantors (plus Employer, Accountant and Landlord referees) through the referencing process, patch outcome conditions, read touchpoints and emails, and retrieve generated documents. Authentication is OAuth 2.0 machine-to-machine client_credentials against /auth/token, returning a one-hour JWT bearer token; every call additionally carries an issued Company-ID header. Three webhook events are documented (V2.subject.report.generated, V2.subject.reference.form.generated, V2.subject.outcome.updated) but subscriptions are configured by Goodlord on request, not self-serve. The OpenAPI 3.1.0 document was fetched anonymously; credentials are issued only through a Goodlord account manager.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.1.0",
  "info": {
    "title": "Referencing API",
    "description": "Here you can find the Public API information of the Goodlord Referencing product. This API will allow you to create rental applications, assess Applicants and Guarantors through the rental process and manage them along the way.",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "email": "devs@vouch.co.uk",
      "name": "Goodlord"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0.0"
  },
  "externalDocs": {
    "description": "Understanding Goodlord's Referencing API",
    "url": "https://portal.goodlord.co/blog/2024/8/20/getting-started-with-goodlord-referencing-api"
  },
  "servers": [
    {
      "url": "https://api.goodoverlord.com",
      "description": "Live Server"
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Authentication operations"
    },
    {
      "name": "Application",
      "description": "An application contains rental information and all of the applicants/guarantors which are applying for a tenancy.",
      "externalDocs": {
        "description": "What's an Application?",
        "url": "https://portal.goodlord.co/blog/2024/8/20/getting-started-with-goodlord-referencing-api#applications"
      }
    },
    {
      "name": "Subject",
      "description": "A person who exists on an application.",
      "externalDocs": {
        "description": "What's a Subject?",
        "url": "https://portal.goodlord.co/blog/2024/8/20/getting-started-with-goodlord-referencing-api#subjects"
      }
    },
    {
      "name": "Media",
      "description": "Operations which are concerned around retrieving files"
    }
  ],
  "paths": {
    "/auth/token": {
      "post": {
        "security": [],
        "tags": [
          "Authentication"
        ],
        "summary": "Obtain a JWT token",
        "description": "Obtain a JWT token to authenticate your requests.\nThe `access_token` property of the response contains the Bearer token that should be included in the Authorization header of all requests to the API.\nIt is recommended to use the `expires_in` property to determine when the token will expire and to request a new token before it expires.",
        "operationId": "getAuthToken",
        "requestBody": {
          "description": "Client credentials to obtain a JWT token",
          "content": {
            "application/json": {
              "schema": {
                "title": "Token Request",
                "type": "object",
                "properties": {
                  "client_id": {
                    "type": "string",
                    "example": "example-client-id"
                  },
                  "client_secret": {
                    "type": "string",
                    "example": "example-client-secret"
                  },
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "client_credentials"
                    ]
                  }
                },
                "required": [
                  "client_id",
                  "client_secret",
                  "grant_type"
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "title": "Token Response",
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "type": "string",
                      "example": "your_jwt_access_token"
                    },
                    "scope": {
                      "type": "string",
                      "example": "some_scope some_other_scope"
                    },
                    "expires_in": {
                      "type": "number",
                      "example": 86400
                    },
                    "token_type": {
                      "type": "string",
                      "example": "Bearer"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "parameters": []
    },
    "/referencing/application": {
      "post": {
        "externalDocs": {
          "description": "Find out more about Applications",
          "url": "https://portal.goodlord.co/blog/2024/8/20/getting-started-with-goodlord-referencing-api#applications"
        },
        "tags": [
          "Application"
        ],
        "summary": "Create a new application",
        "description": "Create a new rental application to reference tenants and guarantors",
        "operationId": "createApplication",
        "requestBody": {
          "description": "Application object that needs to be created",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateApplicationRequest"
              },
              "examples": {
                "Example 1 - Create a 12 month tenancy": {
                  "value": {
                    "tenancy": {
                      "moveInDate": "2024-10-01",
                      "term": 12,
                      "monthlyCost": 1000,
                      "address": {
                        "line1": "22 Street",
                        "city": "Sheffield",
                        "postcode": "S6 3GJ",
                        "country": "Wales"
                      }
                    },
                    "agency": {
                      "companyName": "John Smith Lettings",
                      "agentName": "John Smith",
                      "agentMobile": "07293838394",
                      "agentEmail": "john.smith@example.com"
                    }
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Application"
                },
                "examples": {
                  "Example 1 - Create a 12 month tenancy": {
                    "value": {
                      "id": "644e4a2b-e2cc-4269-9022-91eaada1592e",
                      "subjects": [],
                      "createdAt": "2025-07-22T14:35:12.1893525+00:00",
                      "tenancy": {
                        "moveInDate": "2024-10-01",
                        "monthlyCost": 1000,
                        "term": 12,
                        "address": {
                          "id": "01dad872-3428-4dc1-b911-3a0da3bbc1fc",
                          "line1": "22 Street",
                          "line2": null,
                          "city": "Sheffield",
                          "postcode": "S6 3GJ",
                          "country": "Wales"
                        }
                      },
                      "agency": {
                        "companyName": "John Smith Lettings",
                        "agentName": "John Smith",
                        "agentMobile": "07293838394",
                        "agentEmail": "john.smith@example.com"
                      },
                      "status": "Active",
                      "documents": []
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiMessageResponse"
                }
              }
            }
          }
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyId"
        }
      ]
    },
    "/referencing/application/{applicationId}": {
      "get": {
        "externalDocs": {
          "description": "Find out more about Applications",
          "url": "https://portal.goodlord.co/blog/2024/8/20/getting-started-with-goodlord-referencing-api#applications"
        },
        "tags": [
          "Application"
        ],
        "summary": "Get Application",
        "description": "Retrieve a copy of an application which you have already created",
        "operationId": "getApplication",
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Application"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Could not find requested application {applicationId}"
                    }
                  },
                  "xml": {
                    "name": "##default"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiMessageResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "externalDocs": {
          "description": "Find out more about Applications",
          "url": "https://portal.goodlord.co/blog/2024/8/20/getting-started-with-goodlord-referencing-api#application"
        },
        "tags": [
          "Application"
        ],
        "summary": "Patch Application",
        "description": "Patch an application which you have previously created",
        "operationId": "patchApplication",
        "requestBody": {
          "description": "Properties which need to be patched on the application",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchApplicationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Application"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Could not find requested application {applicationId}"
                    }
                  },
                  "xml": {
                    "name": "##default"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiMessageResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "externalDocs": {
          "description": "Find out more about Applications",
          "url": "https://portal.goodlord.co/blog/2024/8/20/getting-started-with-goodlord-referencing-api#application"
        },
        "tags": [
          "Application"
        ],
        "summary": "Delete Application",
        "description": "Delete an application which you have already created",
        "operationId": "deleteApplication",
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Application"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Could not find requested application {applicationId}"
                    }
                  },
                  "xml": {
                    "name": "##default"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiMessageResponse"
                }
              }
            }
          }
        }
      },
      "parameters": [
        {
          "name": "applicationId",
          "in": "path",
          "description": "The applicationId of the application you wish to retrieve",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "$ref": "#/components/parameters/CompanyId"
        }
      ]
    },
    "/referencing/subject/{subjectId}/auth/token": {
      "get": {
        "externalDocs": {
          "description": "Find out more about Subjects",
          "url": "https://portal.goodlord.co/blog/2024/8/20/getting-started-with-goodlord-referencing-api#subjects"
        },
        "tags": [
          "Subject"
        ],
        "summary": "Get Bot JWT Token",
        "description": "Deprecated: Use the POST method on this endpoint instead.\n\nGenerate a new JWT token, which can be used as a redirect URL to send your user down the bot flow.",
        "operationId": "getBotToken",
        "deprecated": true,
        "parameters": [
          {
            "name": "subjectId",
            "in": "path",
            "description": "SubjectId you wish to generate a token for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "A JWT encoded secret you can return to your clients",
                      "example": "secretsecretsecret"
                    },
                    "url": {
                      "type": "string",
                      "description": "A fully qualified URL to the referencing bot with the token included, ready to redirect your user to",
                      "example": "https://bot.references.goodlord.co?token={token}"
                    }
                  },
                  "xml": {
                    "name": "##default"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Could not find requested subject {subjectId}"
                    }
                  },
                  "xml": {
                    "name": "##default"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "An unknown error occurred when trying to generate token for {subjectId}"
                    }
                  },
                  "xml": {
                    "name": "##default"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "externalDocs": {
          "description": "Find out more about Subjects",
          "url": "https://portal.goodlord.co/blog/2024/8/20/getting-started-with-goodlord-referencing-api#subjects"
        },
        "tags": [
          "Subject"
        ],
        "summary": "Create Bot JWT Token",
        "description": "Generate a new JWT token, which can be used as a redirect URL to send your user down the bot flow.\nThis endpoint replaces the deprecated GET method on the same path.",
        "operationId": "createBotToken",
        "parameters": [
          {
            "name": "subjectId",
            "in": "path",
            "description": "SubjectId you wish to generate a token for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Optional request body to specify who is going to use the bot",
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "authorType": {
                    "type": "string",
                    "description": "The type of user requesting the token. When set to a value other than 'Applicant', the `requestedBy` and `requestedByEmail` fields are included in the generated token.",
                    "enum": [
                      "Applicant",
                      "Agent"
                    ],
                    "example": "Agent"
                  },
                  "requestedBy": {
                    "type": "string",
                    "description": "The name of the person who is going to use the bot. Only used when `authorType` is not 'Applicant'.",
                    "example": "Jane Smith"
                  },
                  "requestedByEmail": {
                    "type": "string",
                    "description": "The email of the person who is going to use the bot. Only used when `authorType` is not 'Applicant'.",
                    "example": "jane.smith@example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "A JWT encoded secret you can return to your clients",
                      "example": "secretsecretsecret"
                    },
                    "url": {
                      "type": "string",
                      "description": "A fully qualified URL to the referencing bot with the token included, ready to redirect your user to",
                      "example": "https://bot.references.goodlord.co?token={token}"
                    }
                  },
                  "xml": {
                    "name": "##default"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Could not find requested subject {subjectId}"
                    }
                  },
                  "xml": {
                    "name": "##default"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "An unknown error occurred when trying to generate token for {subjectId}"
                    }
                  },
                  "xml": {
                    "name": "##default"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/referencing/subject/{subjectId}": {
      "get": {
        "externalDocs": {
          "description": "Find out more about Subjects",
          "url": "https://portal.goodlord.co/blog/2024/8/20/getting-started-with-goodlord-referencing-api#subjects"
        },
        "tags": [
          "Subject"
        ],
        "summary": "Get Subject",
        "description": "Retrieve a created subject",
        "operationId": "getSubject",
        "parameters": [
          {
            "name": "subjectId",
            "in": "path",
            "description": "SubjectId you wish to generate a token for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Subject"
                },
                "examples": {
                  "Example 1 - Applicant": {
                    "value": {
                      "externalId": "1234",
                      "rentalDetails": {
                        "priceShare": 1000,
                        "affordabilityRatio": 2.5
                      },
                      "context": {
                        "name": "John Smith",
                        "firstName": "John",
                        "lastName": "Smith",
                        "email": "john@smith.com",
                        "mobile": "07912345678",
                        "redirectUrlOnJourneyComplete": "https://www.myapp.com/complete",
                        "tenancyRenewal": false,
                        "product": "Pro",
                        "addresses": [
                          {
                            "id": "1234",
                            "addressType": "current",
                            "bedroomIdentifier": "Room A",
                            "name": "22",
                            "startDate": "2024-10-01",
                            "status": "Renting",
                            "line1": "Street",
                            "normalizedLine1": "22 Street",
                            "line2": "Crookesmoore",
                            "city": "Sheffield",
                            "county": null,
                            "postcode": "S1 123",
                            "country": "England",
                            "countryCodeAlpha2": "GB",
                            "referee": {
                              "id": "1234",
                              "name": "Jane Smith",
                              "email": "jane@smith.com",
                              "mobile": "07912345678",
                              "createdAt": "2024-10-01"
                            }
                          }
                        ],
                        "incomes": [
                          {
                            "company": "Tesco",
                            "position": "Manager",
                            "contractType": "Permanent",
                            "contractSchedule": "Full Time",
                            "guaranteedBonus": null,
                            "startDate": "2024-10-01",
                            "endDate": null,
                            "address": {
                              "id": null,
                              "addressType": "string",
                              "name": null,
                              "startDate": null,
                              "status": null,
                              "line1": "string",
                              "normalizedLine1": "string",
                              "line2": "string",
                              "line3": null,
                              "city": "string",
                              "county": null,
                              "postcode": "string",
                              "country": "string",
                              "countryCodeAlpha2": null
                            },
                            "referee": {
                              "id": "1234",
                              "name": "Jane Smith",
                              "email": "jane@smith.com",
                              "mobile": "07912345678",
                              "createdAt": "2024-10-01"
                            },
                            "type": "string",
                            "evidenceType": "Open Banking",
                            "income": {
                              "value": 0,
                              "currency": "string",
                              "frequency": "string"
                            },
                            "id": "string"
                          }
                        ],
                        "incomeSummary": {
                          "totalVerifiedIncome": 1000,
                          "maximumAffordabilityPercentage": 123
                        },
                        "credit": {
                          "hasAdverseCredit": false,
                          "adverseCreditDeclared": false
                        },
                        "documents": [
                          {
                            "id": "1234",
                            "fileName": "file.pdf",
                            "thumbnail": "file.png",
                            "documentType": "Proof of Address"
                          }
                        ],
                        "identity": {
                          "nationality": "UK",
                          "nationalInsuranceNumber": "AB123456C",
                          "r2rShareCode": "A12B3DEFG",
                          "idvt": {
                            "idCheckStatus": "Pass",
                            "r2rCheckStatus": "Pass"
                          },
                          "pepsSanctions": {
                            "pepsStatus": "NotFound",
                            "sanctionsStatus": "Match"
                          }
                        }
                      },
                      "outcome": {
                        "status": "Accepted",
                        "comments": "This application has been accepted",
                        "rpi": {
                          "eligibility": "eligible",
                          "comments": "This application is eligible for RPI"
                        },
                        "sections": [
                          {
                            "name": "Income",
                            "status": "Accepted"
                          }
                        ]
                      },
                      "id": "1234",
                      "type": "applicant",
                      "attachedSubjects": [
                        {
                          "id": "string",
                          "type": "string"
                        }
                      ],
                      "milestones": [
                        {
                          "type": "FinalOutcome",
                          "event": "subject.accepted",
                          "createdAt": "2024-10-01",
                          "updatedAt": "2024-10-01"
                        }
                      ],
                      "recommendations": [
                        null
                      ]
                    }
                  },
                  "Example 2 - Guarantor": {
                    "value": {
                      "rentalDetails": {
                        "priceShare": 100,
                        "affordabilityRatio": 2.5
                      },
                      "context": {
                        "name": "Brian Davies",
                        "firstName": "Brian",
                        "lastName": "Davies",
                        "email": "brian.davies@test.com",
                        "mobile": "07123456789",
                        "product": "Essential",
                        "financial": {
                          "affordability": {
                            "rent": 100,
                            "term": 12,
                            "affordabilityRatio": 2.5,
                            "affordabilityAmount": 3000
                          }
                        },
                        "documents": [],
                        "idvt": "NotRequired"
                      },
                      "outcome": {
                        "status": "Pending Submission"
                      },
                      "id": "2a44ed99-ce42-4fba-aac9-78e3123af5bf",
                      "type": "guarantor",
                      "attachedSubjects": [
                        {
                          "id": "5a697798-304f-4738-8b62-01cbbe69bad9",
                          "type": "applicant"
                        }
                      ],
                      "milestones": [
                        {
                          "type": "event",
                          "event": "subject.created",
                          "createdAt": "2025-07-22T14:41:50.7650622+00:00",
                          "updatedAt": "2025-07-22T14:41:50.7650623+00:00"
                        }
                      ],
                      "recommendations": []
                    }
                  },
                  "Example 3 - Corporate Let": {
                    "value": {
                      "rentalDetails": {
                        "priceShare": 100,
                        "affordabilityRatio": 2.5
                      },
                      "context": {
                        "name": "Rizwan Ahmed",
                        "firstName": "Rizwan",
                        "lastName": "Ahmed",
                       

# --- truncated at 32 KB (119 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/goodlord/refs/heads/main/openapi/goodlord-referencing-api-openapi.json
Goodlord Referencing API

Documentation

Specifications

Other Resources

OpenAPI Specification
