Developer Portal

Introduction Glossary Authentication Webhooks API Specification

Introduction

Read Getting Started with Goodlord's Referencing API for a quick walkthrough to get started with our Referencing API.

Authentication

Goodlord's APIs use OAuth 2.0 Machine-to-Machine (M2M) authentication to ensure secure access. This process involves your client application (the machine) authenticating with Goodlord's authorization server using a Client ID and Client Secret to obtain an access token. Once obtained, this token must be included with each API request to access Goodlord's resources. The resource server will validate the token, ensuring that only legitimate requests are granted access, maintaining secure and authorised interactions.

Obtaining an Access Token

To retrieve an access token, send a POST request to Goodlord's auth/token endpoint. Below is an example request using curl to Goodlord's sandbox environment:

curl --location 'https://api-sandbox.goodlord.co/auth/token' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "<<Your Client ID>>",
    "client_secret": "<<Your Client Secret>>",
    "grant_type": "client_credentials"
}

Example Response

Upon a successful request, the authorization server will respond with a JSON object containing the access token and additional metadata:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "<<Your access token>>",
  "scope": "free_plan referencing_product"</pre>
}

Important Notes

Token Expiration: The access token is valid for 3600 seconds (1 hour). Once expired, you will need to request a new token by repeating the authentication process.

Token Format: The access token is issued in JWT (JSON Web Token) format.

Making API Requests

After obtaining the access token, include it in the Authorization header for subsequent API requests. You should also include the Company ID that was issued to you in the Company-ID header. For example, to call the referencing/application endpoint:

curl --location 'https://api-sandbox.goodlord.co/referencing/application' \
--header 'Authorization: Bearer <<Your access token>>' \
--header 'Company-ID: <<Your Company ID>>' \
--header 'Content-Type: application/json' \
--data '{}'

Ensure that the access token is properly included in the Authorization header for all API requests to authenticate and authorise your actions.

Webhooks

Goodlord supports webhook notifications to keep you informed of important events related to an individual subject's referencing process.

Subscribing to webhooks

Please contact us if you would like to subscribe to webhook events.

When requesting access to an account, you must let us know which events you wish to subscribe to and what endpoints you would like us to call when the event happens within our system.

Supported Events

Final Report is generated

This event is triggered when a final report has been generated for the applicant or guarantor. In this case, you can assume the referencing decision is final. You could use this event to notify your system when everything is completed.

Represented by event.name of "V2.subject.report.generated"

Reference Form generated

This event is triggered when the reference form has been generated. This form is a document which represents some basic information which the applicant has provided and is created at the point they complete the referencing journey.

Represented by event.name of "V2.subject.reference.form.generated"

Outcome Sections updated

This event is triggered whenever an outcome.section changes its status. If you needed to know when a section moves to Accepted/Rejected, then this would be the event you hook into.

Represented by event.name of "V2.subject.outcome.updated"

Webhook payload

The webhook payload will look like the below:

{
 "referer": "111",
 "context": {
   "source": {
     "name": "vouch",
     "version": "2"
   },
   "event": {
     "name": ""V2.subject.outcome.updated",
     "version": "1",
     "timestamp": "1623316665"
   }
 },
 "data": {
   "customerId": "<guid>",
   "applicationId": "<guid>",
   "subjectId": "<guid>",
   "type": "guarantor"
}

The customerId, applicationId and subjectId within the data object will allow you to then make requests for this specific Subject to any API endpoints you require, in response to receiving the webhook back from us.

Referencing Product

jwt