Borrowers API

This API allows managing borrowers in the system. It provides endpoints to create, read, update, and delete borrowers, as well as perform specific operations such as updating status, risk rating, and other borrower properties.

The Borrower Central Base URL is used (see introduction).

The Borrower Object

The Borrower object represents a borrower in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "persona": "business",
  "avatarUrl": "https://example.com/avatar.jpg",
  "label": "Company ABC",
  "tags": ["SME", "technology"],
  "flag": "green",
  "riskRating": "A",
  "repaymentRiskRating": 8,
  "currentStep": {
    "stepId": "step123",
    "order": 1,
    "key": "application",
    "label": "Application",
    "createdAt": "2023-04-01T12:00:00Z"
  },
  "cmsClientIds": ["client123", "client456"],
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-04-01T12:00:00Z"
}

Attributes

Borrowers API

The Borrower Summary Object

The Borrower Summary object provides a detailed summary of a borrower, including additional information such as identities, custom fields, points of contact, and alerts.

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "persona": "business",
    "label": "Company ABC",
    "identities": [
        {
            "id": "id123",
            "key": "tax_id",
            "label": "Tax ID",
            "value": "123456789",
            "priority": 1
        }
    ],
    "fields": [
        {
            "id": "field123",
            "key": "industry",
            "label": "Industry",
            "value": "Technology"
        }
    ],
    "pointsOfContact": [
        {
            "id": "poc123",
            "signatures": [
                "email",
                "phone"
            ],
            "priority": 1,
            "value": "john.doe@example.com"
        }
    ],
    "alerts": [
        {
            "id": "alert123",
            "ruleId": "rule456",
            "ruleCode": "HIGH_RISK",
            "level": 3,
            "message": "High risk borrower detected",
            "isAcknowledged": false,
            "createdAt": "2023-04-01T12:00:00Z"
        }
    ],
    "tags": [
        "SME",
        "technology"
    ],
    "flag": "green",
    "stage": "application",
    "riskRating": "A",
    "repaymentRiskRating": 8,
    "currentStep": {
        "stepId": "step123",
        "order": 1,
        "key": "application",
        "label": "Application",
        "createdAt": "2023-04-01T12:00:00Z"
    },
    "cmsClientIds": [
        "client123",
        "client456"
    ],
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-04-01T12:00:00Z"
}

Attributes

Nested Objects

Identity

Field

Point of Contact

Alert

Endpoints

Create a New Borrower

Creates a new borrower in the system.

POST /v1/borrowers

Input Parameters:

Example Request:

{
  "persona": "business",
  "label": "Startup XYZ",
  "riskRating": "B",
  "repaymentRiskRating": 7,
  "flag": "yellow",
  "tags": ["startup", "fintech"]
}

Successful Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Get a Borrower

Retrieves information about a specific borrower.

GET /v1/borrowers/:borrower_id

Path Parameters:

Successful Response:

The response will be a complete Borrower object, as described above.

Update a Borrower

Updates information about an existing borrower.

PATCH /v1/borrowers/:borrower_id

Path Parameters:

Input Parameters:

Example Request:

{
  "label": "Startup ABC (Renovated)",
  "tags": ["startup", "fintech", "renovated"]
}

Successful Response:

The response will be the updated Borrower object.

Delete a Borrower

Deletes a borrower from the system.

DELETE /v1/borrowers/:borrower_id

Path Parameters:

Successful Response:

Status code 204 (No Content) if the deletion was successful.

Update a Borrower's Risk Rating

Updates the risk rating of a borrower.

PUT /v1/borrowers/:borrower_id/risk-rating

Path Parameters:

Input Parameters:

Example Request:

{
  "value": "A",
  "referenceId": "ref123"
}

Successful Response:

Status code 204 (No Content) if the update was successful.

Update a Borrower's Repayment Risk Rating

Updates the repayment risk rating of a borrower.

PUT /v1/borrowers/:borrower_id/repayment-risk-rating

Path Parameters:

Input Parameters:

Example Request:

{
  "value": 8,
  "referenceId": "ref456"
}

Successful Response:

Status code 204 (No Content) if the update was successful.

Update a Borrower's Flag

Updates the flag of a borrower.

PUT /v1/borrowers/:borrower_id/flag

Path Parameters:

Input Parameters:

Example Request:

{
  "value": "green",
  "referenceId": "ref789"
}

Successful Response:

Status code 204 (No Content) if the update was successful.

List Borrowers

Retrieves a paginated list of borrowers with filtering and sorting options.

GET /v1/borrowers

Query Parameters:

Successful Response:

The response will be a paginated list of Borrower objects.

Get Borrowers Summary

Retrieves a summary of borrowers with advanced filtering and grouping options.

GET /v1/borrowers-summary

Query Parameters:

Successful Response:

The response will be a summary of borrowers according to the specified criteria.

Send SMS to a Borrower

Sends an SMS message to a specific borrower.

POST /v1/borrowers/:borrower_id/communications/sms

Path Parameters:

Input Parameters:

Example Request:

{
  "message": "Your application has been approved",
  "pointOfContactId": "poc123"
}

Successful Response:

Status code 204 (No Content) if the message was sent successfully.

Associate a CMS Client ID to a Borrower

Associates a new CMS Client ID to a specific borrower.

POST /v1/borrowers/:borrower_id/cms-client-ids/:cms_client_id

Path Parameters:

Successful Response:

Status code 204 (No Content) if the association was successful.

Possible Errors:

Update CMS Client IDs of a Borrower

Updates the complete list of CMS Client IDs associated with a specific borrower.

PUT /v1/borrowers/:borrower_id/cms-client-ids

Path Parameters:

Input Parameters:

Example Request:

{
  "cmsClientIds": ["client123", "client456", "client789"]
}

Successful Response:

Status code 204 (No Content) if the update was successful.

Possible Errors:

Error Handling

The API may return the following error codes:

Errors will include a descriptive message in the response body.