Skip to main content
API docs by Redocly

BrightMatch Relay (1.0.0)

BrightMatch Relay enables lending partners to efficiently communicate loan application status updates back to the BrightMatch platform. As a lender, you'll use this API to notify BrightMatch when loan applications progress through your decisioning workflow - whether approved, declined, or require additional review.

By feeding decision outcomes back to BrightMatch, you help improve the platform's outcome prediction accuracy and increase future approval rates. This creates a continuous feedback loop that benefits both lenders and borrowers by ensuring better application matching and more efficient decisioning workflows.

Endpoints

BrightMatch Relay API endpoints including authentication and status update functionality

Obtain access token using OAuth2 Client Credentials flow

Use this endpoint to authenticate with BrightMatch and obtain an access token required for calling the Relay API endpoints. This implements the OAuth2 Client Credentials grant type.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "client_credentials"

Must be 'client_credentials' for this flow

client_id
required
string

Your BrightMatch client identifier

client_secret
required
string

Your BrightMatch client secret

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "scope": "relay/status:write"
}

Send loan application status updates to BrightMatch

Lenders must call this endpoint to notify BrightMatch whenever there is a status change for a loan application.

Request Body schema: application/json
required
applicationId
required
string

Unique identifier for the loan application (typically a 36 character UUID)

status
required
string
Enum: "Applied" "Approved" "Declined" "Withdrawn"

Current status of the loan application

declineReason
string
Enum: "Review for Broker" "Under Assessment" "ATM Withdrawals" "Credit Score" "Crypto" "Employment" "Gambling" "Jobseeker" "No Reason Provided" "Other Reason" "SACC or EWA" "Serviceability"

Specific reason for the decline (required when status is 'Declined')

declineReasonDetail
string <= 1000 characters

Free text field providing additional detail about the decline (required when status is 'Declined')

originalTimestamp
string <date-time>

ISO 8601 timestamp of when the status change originally occurred

Responses

Request samples

Content type
application/json
{
  • "applicationId": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "Applied",
  • "declineReason": "Under Assessment",
  • "declineReasonDetail": "Credit score of 450 is below our minimum requirement of 600",
  • "originalTimestamp": "2024-01-15T10:30:00Z"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Status update processed successfully"
}

Schema

TokenRequest

grant_type
required
string
Value: "client_credentials"

Must be 'client_credentials' for this flow

client_id
required
string

Your BrightMatch client identifier

client_secret
required
string

Your BrightMatch client secret

{
  • "grant_type": "client_credentials",
  • "client_id": "your_client_id",
  • "client_secret": "your_client_secret"
}

TokenResponse

access_token
string

The access token for API requests

token_type
string

Token type, typically 'Bearer'

expires_in
integer

Token lifetime in seconds

scope
string

Granted scopes for the token

{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "scope": "relay/status:write"
}

WebhookNotification

applicationId
required
string

Unique identifier for the loan application (typically a 36 character UUID)

status
required
string
Enum: "Applied" "Approved" "Declined" "Withdrawn"

Current status of the loan application

declineReason
string
Enum: "Review for Broker" "Under Assessment" "ATM Withdrawals" "Credit Score" "Crypto" "Employment" "Gambling" "Jobseeker" "No Reason Provided" "Other Reason" "SACC or EWA" "Serviceability"

Specific reason for the decline (required when status is 'Declined')

declineReasonDetail
string <= 1000 characters

Free text field providing additional detail about the decline (required when status is 'Declined')

originalTimestamp
string <date-time>

ISO 8601 timestamp of when the status change originally occurred

{
  • "applicationId": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "Applied",
  • "declineReason": "Under Assessment",
  • "declineReasonDetail": "Credit score of 450 is below our minimum requirement of 600",
  • "originalTimestamp": "2024-01-15T10:30:00Z"
}