Goodlord Subject API

openapi: 3.2.0
info:
  title: Goodlord Subject API
  version: 1.0.0
  contact:
    email: devs@vouch.co.uk
    name: Goodlord
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://swagger.io/terms/
  description: 'Operations tagged Subject across 2 of this provider''s published API definitions: goodlord-referencing-api-openapi.json, goodlord-referencing-api-sandbox-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.goodoverlord.com
  description: Live Server
- url: https://api-sandbox.goodlord.co
  description: Sandbox Server
security:
- OAuth2: []
tags:
- 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
paths:
  /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.


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

        This 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'
    servers:
    - url: https://api.goodoverlord.com
      description: Live Server
  /referencing/subject/{subjectId}:
    parameters:
    - $ref: '#/components/parameters/CompanyId'
    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
                      email: info@abcboatbuilding.com
                      mobile: null
                      product: Corporate
                      financial:
                        affordability:
                          rent: 100
                          term: 12
                          affordabilityRatio: 2.5
                          affordabilityAmount: 3000
                      documents: []
                      company:
                        name: Acme Corporation
                        companyNumber: '12345678'
                      idvt: NotRequired
                    outcome:
                      status: Pending Submission
                    id: e05e6416-21f2-4340-83f2-1105e902cb6b
                    type: applicant
                    attachedSubjects: []
                    milestones:
                    - type: event
                      event: subject.created
                      createdAt: '2025-07-22T14:55:16.8613265+00:00'
                      updatedAt: '2025-07-22T14:55:16.8613267+00:00'
                    recommendations: []
                Example 4 - Report Customisation:
                  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
                      communicationPreferences:
                        sendInitialTenantEmail: false
                        disableRentProtectionComms: true
                        disableTCLIComms: true
                        disableTenancyServicesComms: true
                      addresses:
                      - id: '1234'
                        addressType: current
                        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
                    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
        '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: An unknown error occurred when trying to retrieve {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'
    patch:
      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: Patch Subject
      description: Patch a subject you have already created
      operationId: patchSubject
      parameters:
      - name: subjectId
        in: path
        description: SubjectId you wish to generate a token for
        required: true
        schema:
          type: string
      requestBody:
        description: Patch object of properties you wish to change
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchSubjectRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subject'
        '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: An unknown error occurred when trying to retrieve {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'
    delete:
      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: Delete Subject
      description: Soft delete a subject which you have already created
      operationId: deleteSubject
      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'
        '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: An unknown error occurred when trying to retrieve {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 delete {subjectId}
                xml:
                  name: '##default'
    servers:
    - url: https://api.goodoverlord.com
      description: Live Server
  /referencing/subject/application/{applicationId}:
    parameters:
    - $ref: '#/components/parameters/CompanyId'
    put:
      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 Subject
      description: Create a new subject
      operationId: createSubject
      parameters:
      - name: applicationId
        in: path
        description: ApplicationId you wish to add the new subject to
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubjectRequest'
            examples:
              Example 1 - Create an applicant:
                value:
                  type: applicant
                  attachedSubjects: []
                  context:
                    firstName: Terry
                    lastName: Smith
                    mobile: 07383838383
                    email: test-again@test.com
                    product: Essential
                  rentalDetails:
                    priceShare: 100
                    affordabilityRatio: 2.5
              Example 2 - Create a guarantor for an existing applicant:
                value:
                  type: guarantor
                  attachedSubjects:
                  - id: 5a697798-304f-4738-8b62-01cbbe69bad9
                    type: applicant
                  context:
                    firstName: Brian
                    lastName: Davies
                    mobile: 07123456789
                    email: brian.davies@test.com
                    product: Essential
                  rentalDetails:
                    priceShare: 100
                    affordabilityRatio: 2.5
              Example 3 - Corporate Let:
                value:
                  type: applicant
                  attachedSubjects: []
                  context:
                    email: info@abcboatbuilding.com
                    firstName: Rizwan
                    lastName: Ahmed
                    company:
                      name: Acme Corporation
                      companyNumber: '12345678'
                    product: Corporate
                  rentalDetails:
                    priceShare: 100
                    affordabilityRatio: 2.5
              Example 4 - Applicant requiring a guarantor:
                value:
                  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
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subject'
              examples:
                Example 1 - Create an applicant:
                  value:
                    rentalDetails:
                      priceShare: 100
                      affordabilityRatio: 2.5
                    context:
                      name: Terry Smith
                      firstName: Terry
                      lastName: Smith
                      email: test-again@test.com
                      mobile: 07383838383
                      product: Essential
                      financial: {}
                      documents: []
                      idvt: NotRequired
                    outcome:
                      status: Pending Submission
                    id: a6770136-63f0-4315-9d9e-3700329a4b91
                    type: applicant
                    attachedSubjects: []
                    milestones:
                    - type: event
                      event: subject.created
                      createdAt: '2025-07-22T14:38:15.6511962+00:00'
                      updatedAt: '2025-07-22T14:38:15.6511963+00:00'
                    recommendations: []
                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: {}
                      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
                      email: info@abcboatbuilding.com
                      mobile: null
                      product: Corporate
                      financial: {}
                      documents: []
                      company:
                        name: Acme Corporation
                        companyNumber: '12345678'
                      idvt: NotRequired
                    outcome:
                      status: Pending Submission
                    id: e05e6416-21f2-4340-83f2-1105e902cb6b
                    type: applicant
                    attachedSubjects: []
                    milestones:
                    - type: event
                      event: subject.created
                      createdAt: '2025-07-22T14:55:16.8613265+00:00'
                      updatedAt: '2025-07-22T14:55:16.8613267+00:00'
                    recommendations: []
        '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:
                type: object
                properties:
                  message:
                    type: string
                    example: An unknown error occurred when trying to retrieve '{applicationId}'. Please try again later
                xml:
                  name: '##default'
    servers:
    - url: https://api.goodoverlord.com
      description: Live Server
  /referencing/subject/{subjectId}/touchpoints:
    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 Touchpoints
      description: Retrieve all touchpoints for a subject, including communications and interactions
      operationId: getSubjectTouchpoin

# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/goodlord/refs/heads/main/openapi/goodlord-subject-api-openapi.yml