Goodlord
Goodlord Referencing API (Sandbox)

The sandbox environment of the Goodlord Referencing Product, published as a separate entry in the developer portal's public catalogue and carrying its own OpenAPI 3.1.0 document with the sandbox server and sandbox token endpoint. Operation surface is identical to the live API. Goodlord's getting-started guide states that a sandbox account is arranged by Goodlord's team during a commercial engagement and that production is enabled afterwards by an account manager, so this is a partner sandbox rather than an open trial — no self-serve key issuance exists.
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-sandbox.goodlord.co",
      "description": "Sandbox 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-sandbox-openapi.json
Goodlord Referencing API (Sandbox)

Documentation

Specifications

Other Resources

OpenAPI Specification
