Quickstart on AcuView API

Overview

This guide provides details about the AcuView APIs and related information, which is helpful to generate real-time borrower intelligence, instant risk alerts, and verified identity/banking checks inside your loan workflows. AcuView is AcuFi’s real-time loan intelligence network that monitors borrower activity across a growing, privacy-preserving lender network; the RESTful API (v1.0, HTTPS, JSON) lets you authenticate, verify bank accounts, and create, retrieve, and manage loan records so you can detect stacking behavior and make faster, safer decisions before final approval.

API Information

All API requests are made over HTTPS. The AcuView API is exposed under the title:

AcuView.Api

Protocol: HTTPS
Content Type: application/json

Headers

Some endpoints require additional custom headers.

Header key name: X-Timezone
Header value: IANA time zone identifier (e.g., "America/Los_Angeles")

Authentication Endpoints

Endpoint Method Purpose Auth Required Request Body Success Response Error Response

Table 1. Tabular presentation for AcuView Authentication Endpoints
Endpoint	Method	Purpose	Auth Required	Request Body	Success Response	Error Response
`/api/Authentication/login`	POST	Authenticate a user and establish a session	No	`{ "username": "string", "password": "string" }`	200 OK → `{ "message": "Login Successful", "token": "<JWT token string>" }`	401 Unauthorized
`/api/Authentication/whoAmI`	GET	Retrieve details of the current authenticated user	Yes	None	200 OK → `{ "merchantId": "ABCD1234", "username": "example@gmail.com", "roles": [ "Admin" ], "product": "All", "clientType": "Online" }`	401 Unauthorized

/api/Authentication/login

POST

Authenticate a user and establish a session

{
 "username": "string",
 "password": "string"
 }

200 OK →

{
  "message": "Login Successful",
  "token": "<JWT token string>"
}

401 Unauthorized

/api/Authentication/whoAmI

GET

Retrieve details of the current authenticated user

Yes

None

200 OK →

{
  "merchantId": "ABCD1234",
  "username": "example@gmail.com",
  "roles": [
    "Admin"
  ],
  "product": "All",
  "clientType": "Online"
}

401 Unauthorized

1. Authenticate

Before you can call most endpoints, you need to log in and establish a session.

Request Parameters

The following are the request parameters for POST /api/Authentication/login:

Table 2. Headers
Name	Data Type	Required	Value/Description
`Content-Type`	string	Yes	application/json

Table 3. Body
Field	Data Type	Required	Description
`username`	string	Yes	User login (e.g., email)
`password`	string	Yes	User password

Request

POST /api/Authentication/login
Content-Type: application/json

{
  "username": "test.user@example.com",
  "password": "StrongPassword123"
}

Response Parameters

The following are the response parameters for POST /api/Authentication/login:


Field	Data Type	Description
`message`	string	Indicates the outcome of the login request
`token`	string (JWT)	A bearer token used to authenticate subsequent API requests.

Response

When login is successful:

{
  "message": "Login Successful"
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbkBleGFtcGxlLmNvbSIsImVtYWlsIjoiYWRtaW5AZXhhbXBsZS5jb20iLCJqdGkiOiJkZWEwNzRjOC03MzRhLTQyY2EtOTI0NC1jZTQzMTAwZDcwMjIiLCJjb3JyZWxhdGlvbklkIjoiYmJmNGZmNTUtMTMzMC00NDdkLTkxOGQtMmMwOTNmNGZlZjc3IiwiTWVyY2hhbnRJZCI6ImFjdWZpMDAxIiwiVXNlck5hbWUiOiJhZG1pbiIsIlR5cGUiOiJPbmxpbmUiLCJBbGxvd2VkUHJvZHVjdHMiOiIyQ1A0Zll5N3g2U0plRzl1VzBNREsyb0RJOGlBSHNWWjEvUUlZWk41MldBPSIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6WyJFbXBsb3llZSIsIkFkbWluIiwiQWRtaW4iXSwiZXhwIjoxNzU3NjY2NTIyLCJpc3MiOiJBY3VmaSIsImF1ZCI6Imh0dHBzOi8vd3d3LmFjdWZpLmNvbSJ9.B52VAE3Ih-bmN9U6xum4vAjc_WXSzPyMVXCdeiLBLxg" 
}

When login details are invalid:

{
  "message": "Invalid login details. Please try again."
}

2. Verify a Bank Account

Next, you can verify a borrower’s bank account details.

Note:

When you sent a request to verify the bank account, the response statuses will be a Match, Warning and even Not Found.

Request Parameters

The following are the request parameters for the verify bank account API:


Field	Data Type	Required	Description
`accountHoldersName`	String	Yes	Account holder’s full name (spelled exactly like this in the request).
`bankAccountNumber`	String	Yes	Bank account number.
`bankRoutingNumber`	String	Yes	Bank routing number.

Request:

POST /api/AccountVerification/verifyBankAccount
Content-Type: application/json
Authorization: Bearer <Token>
X-Timezone: America/Los_Angeles

{
  "accountHoldersName": "John Doe",
  "bankAccountNumber": "1234567890",
  "bankRoutingNumber": "123456789"
}

Response Parameters

The following are the response parameters for the verify bank account API:


Field	Data Type	Description
`matchStatus`	string	Verification result. One of: `Match`, `Warning`, `NotFound`.
`message`	string	Human-readable result message.
`providedCustomerDetails`	object	Echo of normalized input used for verification.
`providedCustomerDetails.accountHolderName`	string	Account holder’s name (note: no “s” in `Holder` here).
`providedCustomerDetails.accountNumber`	string	Bank account number.
`providedCustomerDetails.routingNumber`	string	Bank routing number.
`dataConflicts`	array	List of fields with data mismatch of the bank account number.

Response

When its a Match:

{
  "matchStatus": "Match",
  "message": "Account verified successfully",
  "providedCustomerDetails": {
    "accountHolderName": "JOHN DOE",
    "accountNumber": "1234567890",
    "routingNumber": "123456789"
  },
  "dataConflicts": []
}

When its a Warning:

{
    "matchStatus": "Warning",
    "message": "Account Holder information is mismatched",
    "providedCustomerDetails": {
        "accountHolderName": "JHON DOE",
        "accountNumber": "1234567890",
        "routingNumber": "123456788"
    },
    "dataConflicts": [
        {
            "fieldName": "AccountHolderName",
            "valueOnFile": "[PROTECTED]",
            "inputtedValue": "JOHN DOE"
        },
        {
            "fieldName": "BankRoutingNumber",
            "valueOnFile": "[PROTECTED]",
            "inputtedValue": "123456788"
        }
    ]
}

When its Not Found:

{
  "matchStatus": "NotFound",
  "message": "No bank account record found",
  "providedCustomerDetails": {
    "accountHolderName": "JOHN DOE",
    "accountNumber": "1234567890",
    "routingNumber": "123456789"
  },
  "dataConflicts": []
}

3. Create a Loan Record

Using this API, you can create and validate a loan record.

Note:

When you send the request to create a loan record, the following are the Record statuses:

Match
Warning
FraudCheck
FirstSeen

And, the following are the Loan statuses:

Approved
Denied
Pending
WrittenOff
PaidOff

Request Parameters

The following are the request parameters for the create/check a loan record API:


Field	Data Type	Required	Description
`name`	string	Yes	The full name of the borrower.
`dateOfBirth`	string	No	Date in `YYYY-MM-DD`.
`socialSecurityNumber`	string	Yes	SSN (string as sent).
`fullAddress`	string	No	Street, city, state, ZIP.
`phoneNumber`	string	No	Phone number (string in request).
`email`	string	Yes	The email address of the borrower.
`bankAccountNumber`	string	No	Bank account number.
`bankRoutingNumber`	string	No	Bank transit/routing number.
`occupation`	string	No	The occupation of the borrower.
`employer`	string	No	The name of the employer.
`income`	number	No	Annual income.
`requestedLoanAmount`	number	Yes	The loan amount requested.

Request


{
    "name": "John Doe",
    "dateOfBirth": "1995-08-02",
    "socialSecurityNumber": "812322800",
    "fullAddress": "321 Maple Drive, Austin, TX 78701",
    "phoneNumber": "8123228002",
    "email": "jdoe988@yopmail.com",
    "bankAccountNumber": "1234567890",
    "bankRoutingNumber": "123456789",
    "occupation": "Technical Manager ",
    "employer": "Tech Soluction",
    "income": "1,200",
    "requestedLoanAmount": "120"
}

Response Parameters

200 OK

The following are the response parameters for the create/check a loan record API:

Table 4. Top-Level Response
Field	Data Type	Description
`recordVerification`	object	Results of input vs. known-data verification.
`recordAnalysis`	object	Aggregate analysis of related/duplicate records and recency.
`recordInformation`	object	Canonicalized loan record saved by the system.

Table 5. `recordVerification` (object)
Field	Data Type	Description
`status`	string (enum)	Overall verification outcome. Values seen: `FirstSeen`, `Warning`.
`mismatches`	array<object>	Field-level discrepancies between input and values on file.
`totalRecordsCompared`	number	How many prior records were compared against.

Table 6. `recordVerification.mismatches[]` (object)
Field	Data Type	Description
`fieldName`	string	Name of the field with mismatch.
`discrepancies`	array<object>	One or more per compared record.

Table 7. `recordVerification.mismatches[].discrepancies[]` (object)
Field	Data Type	Description
`recordIndex`	number	Index of the compared record (1-based).
`inputValue`	string	Value submitted in this request.
`valuesOnFile`	string	Value found on file for the same subject.
`hasMatch`	boolean	Whether input equals value on file.

Table 8. `recordAnalysis` (object)
Field	Data Type	Description
`totalRecords`	number	Count of records considered in the analysis window.
`periodCounts`	object (map<string, number>)	Counts by recency bucket. Keys observed: `48 hours`, `1 week`, `1 month`, `3 months`, `6 months`, `9 months`, `12 months`, `2 years`, `older`.
`summary`	string	Human-readable summary of counts.
`lastSeen`	string (datetime)	Most recent seen timestamp (locale format).
`monthsReport`	string	Reporting window label.
`lastSeenBreakDowns`	array<object>	Per-record recent-activity details.

Table 9. `recordAnalysis.lastSeenBreakDowns[]` (object)
Field	Data Type	Description
`recordId`	string	Unique ID of the related record.
`merchantId`	string	Source merchant identifier.
`seen`	string	Relative “time ago.”
`dateTime`	string	Localized timestamp with timezone label.
`recordedDateTime`	string (ISO-8601)	UTC timestamp of when the record was created/seen.
`status`	string	Verification/recency status. Values seen: `FirstSeen`, `Warning`.
`count`	number \| null	Optional frequency metric (null if not set).
`loanStatus`	string	Current loan lifecycle status. Values seen: `PaidOff`, `Pending`.
`loanStatusChangedOn`	string \| null (ISO-8601)	When `loanStatus` last changed.
`requestedLoanAmount`	number	Requested amount on that record.
`merchantType`	string	Channel/type of merchant. Values seen: `Online`.
`allowLoanActions`	boolean	Whether follow-on loan actions are allowed.

Table 10. `recordInformation` (object)
Field	Data Type	Description
`name`	string (uppercase)	Canonicalized applicant name.
`dateOfBirth`	string (YYYY-MM-DD)	Applicant DOB.
`ssnLast4`	string	Last 4 digits of SSN.
`fullAddress`	string (uppercase)	Canonicalized address.
`phoneNumber`	number	Normalized phone (digits only).
`email`	string	Email address.
`bankAccountNumberLast4`	string	Last 4 digits of bank account.
`bankRoutingNumber`	string	Full routing number (may remain full).
`occupation`	string (uppercase)	Canonicalized occupation.
`employer`	string (uppercase)	Canonicalized employer name.
`income`	number	Parsed numeric income (currency not embedded).
`requestedLoanAmount`	number	Parsed numeric amount requested.
`loanStatus`	string	Lifecycle state of the loan. Values seen: `Pending`.
`approvedLoanAmount`	number	Amount approved so far.
`recordStatus`	string	Overall record state from verification. Values seen: `Warning`.
`id`	string	Primary identifier of the created record.
`addedBy`	string	Merchant/system that created the record.
`addedDate`	string (ISO-8601)	UTC creation timestamp.
`merchantType`	string	Channel/type of merchant. Values seen: `Online`.

Response

{
    "recordVerification": {
        "status": "Warning",
        "mismatches": [
            {
                "fieldName": "Income",
                "discrepancies": [
                    {
                        "recordIndex": 1,
                        "inputValue": "1200",
                        "valuesOnFile": "1000",
                        "hasMatch": false
                    }
                ]
            },
            {
                "fieldName": "Occupation",
                "discrepancies": [
                    {
                        "recordIndex": 1,
                        "inputValue": "TECHNICAL MANAGER",
                        "valuesOnFile": "TECHNICAL ENGINEER",
                        "hasMatch": false
                    }
                ]
            }
        ],
        "totalRecordsCompared": 2
    },
    "recordAnalysis": {
        "totalRecords": 2,
        "periodCounts": {
            "48 hours": 2,
            "1 week": 0,
            "1 month": 0,
            "3 months": 0,
            "6 months": 0,
            "9 months": 0,
            "12 months": 0,
            "2 years": 0,
            "older": 0
        },
        "summary": "Total of 1 records: 1 in last 48 hours",
        "lastSeen": "09/15/2025 14:51:09",
        "monthsReport": "1 Month",
        "lastSeenBreakDowns": [
            {
                "recordId": "68c7da85e16639b4295c02c0",
                "merchantId": "acufi001",
                "seen": "2 minutes ago",
                "dateTime": "09/15/2025 02:51 PM (IST)",
                "recordedDateTime": "2025-09-15T09:21:09.822Z",
                "status": "FirstSeen",
                "count": null,
                "loanStatus": "PaidOff",
                "loanStatusChangedOn": "2025-09-15T09:21:24.774Z",
                "requestedLoanAmount": 100,
                "merchantType": "Online",
                "allowLoanActions": true
            },
            {
                "recordId": "68c7db23e16639b4295c037e",
                "merchantId": "acufi001",
                "seen": "just now",
                "dateTime": "09/15/2025 02:53 PM (IST)",
                "recordedDateTime": "2025-09-15T09:23:47.9717632Z",
                "status": "Warning",
                "count": null,
                "loanStatus": "Pending",
                "loanStatusChangedOn": null,
                "requestedLoanAmount": 120,
                "merchantType": "Online",
                "allowLoanActions": true
            }
        ],
        "loanApprovalBreakDowns": []
    },
    "recordInformation": {
        "name": "John Doe",
        "dateOfBirth": "1995-08-02",
        "ssnLast4": "2800",
        "fullAddress": "321 MAPLE DRIVE AUSTIN TX 78701",
        "phoneNumber": 8123228002,
        "email": "jdoe988@yopmail.com",
        "bankAccountNumberLast4": "7890",
        "bankRoutingNumber": "123456789",
        "occupation": "TECHNICAL MANAGER",
        "employer": "TECH SOLUCTION",
        "income": 1200,
        "requestedLoanAmount": 120,
        "loanStatus": "Pending",
        "approvedLoanAmount": 120,
        "recordStatus": "Warning",
        "id": "68c7db23e16639b4295c037e",
        "addedBy": "acufi001",
        "addedDate": "2025-09-15T09:23:47.8929514Z",
        "merchantType": "Online"
    }
}

4. Retrieve Loan Records

With this API, you can search and retrieve loan applications with filters and pagination.

Request Parameters

The following are the request parameters for GET /api/LoanRecord:


Name	Data Type	Required	Description
`page`	integer	Yes	Page number for pagination (1-based).
`pageSize`	integer	Yes	Number of records per page.
`sortBy`	string	No	Field to sort by. From the sample: `CreatedDate`.
`sortDirection`	string	No	Sort order.

Request

api/LoanRecord?page=1&pageSize=2&sortBy=CreatedDate&sortDirection=DESC

Response Parameters

The following are the response parameters for GET /api/LoanRecord:

Table 11. Top-level
Field	Data Type	Description
`items`	array of objects	List of loan record summaries. See items[] fields below.
`pageNumber`	integer	Current page number.
`pageSize`	integer	Page size used for this response.
`totalItems`	integer	Total number of items matching the query.
`totalPages`	integer	Total number of pages available.
`hasPrevious`	boolean	Whether a previous page exists.
`hasNext`	boolean	Whether a next page exists.

Table 12. `items[]` fields
Field	Data Type	Description
`id`	string	Unique identifier of the loan record.
`name`	string	Applicant’s full name (uppercase in sample, not required).
`ssnLast4`	string	Masked SSN format with last 4 visible.
`email`	string	Contact email address.
`createdDate`	string (date, `YYYY-MM-DD`)	Record creation date.
`loanAmount`	number	Loan amount associated with the record.
`loanStatus`	string	Status of the loan. Examples seen: `"Pending"`, `"WrittenOff"`.
`recordStatus`	string	System status of the record. Example seen: `"FirstSeen"`.

Response

{
  "items": [
    {
      "id": "68c7c280dc59d202872b533f",
      "name": "DFGH DFGH",
      "ssnLast4": "XXX-XX-7654",
      "email": "fdgfhgjh@yopmail.com",
      "createdDate": "2025-09-15",
      "loanAmount": 100,
      "loanStatus": "Pending",
      "recordStatus": "FirstSeen"
    },
    {
      "id": "68a42aa28248fd649909274c",
      "name": "ANDREW DOE",
      "ssnLast4": "XXX-XX-3411",
      "email": "andrew111@yopmail.com",
      "createdDate": "2025-08-19",
      "loanAmount": 100,
      "loanStatus": "WrittenOff",
      "recordStatus": "FirstSeen"
    }
  ],
  "pageNumber": 1,
  "pageSize": 2,
  "totalItems": 27,
  "totalPages": 14,
  "hasPrevious": false,
  "hasNext": true
}

5. Retrive Loan Record By Id

This API allows you to retrieve a specific loan record by its unique identifier.

Path Parameters: id (string): Unique loan record identifier

Request URL: api/LoanRecord/68c7db23e16639b4295c037e

Response Parameters

The following are the response parameters for retrieve loan records by Id API:

Table 13. Top-level
Field	Data Type	Nullable	Description
`recordVerification`	object	No	Result of input vs. file checks.
`recordAnalysis`	object	No	Summary of related records and recency.
`recordInformation`	object	No	Canonical loan record saved by the system.

Table 14. `recordVerification` object
Field	Data Type	Nullable	Description	Example / Values
`status`	string	No	Overall verification result.	`Warning` (also: `FirstSeen`, etc.)
`mismatches`	array	No	Field-level differences vs. values on file.	`[ {…} ]`
`totalRecordsCompared`	number	No	Count of prior records compared.	`2`

Table 15. recordVerification.mismatches[]
Field	Data Type	Nullable	Description
`fieldName`	string	No	Name of the field with a difference.
`discrepancies`	array	No	One entry per compared record.

Table 16. recordVerification.mismatches[].discrepancies[]
Field	Data Type	Nullable	Description
`recordIndex`	number	No	1-based index of the compared record.
`inputValue`	string	No	Value sent in this request.
`valuesOnFile`	string	No	Value stored on file.
`hasMatch`	boolean	No	`true` if values match.

Table 17. `recordAnalysis` object
Field	Data Type	Nullable	Description
`totalRecords`	number	No	Records included in analysis.
`periodCounts`	object (map<string, number>)	No	Counts by time bucket.
`summary`	string	Yes	Human-readable summary.
`lastSeen`	string	No	Relative time since last activity.
`monthsReport`	string	Yes	Reporting window label.
`lastSeenBreakDowns`	array	No	Recent activity per record.

Table 18. recordAnalysis.lastSeenBreakDowns[]
Field	Data Type	Nullable	Description
`recordId`	string	No	Related record ID.
`merchantId`	string	No	Source merchant.
`seen`	string	No	Relative “time ago”.
`dateTime`	string	No	Local display timestamp with TZ label.
`recordedDateTime`	string (ISO-8601 UTC)	No	When the record was created/seen.
`status`	string	No	Verification/recency status.
`count`	number	Yes	Optional frequency metric.
`loanStatus`	string	No	Loan lifecycle status.
`loanStatusChangedOn`	string (ISO-8601 UTC)	Yes	When `loanStatus` last changed.
`requestedLoanAmount`	number	No	Requested amount on that record.
`merchantType`	string	No	Channel/type of merchant.
`allowLoanActions`	boolean	No	Whether follow-on actions are allowed.

Table 19. `recordInformation` object
Field	Data Type	Nullable	Description
`name`	string	No	Canonicalized applicant name (uppercased).
`dateOfBirth`	string (YYYY-MM-DD)	No	Applicant date of birth.
`ssnLast4`	string	No	Last 4 of SSN.
`fullAddress`	string	No	Canonicalized address (uppercased).
`phoneNumber`	number	No	Normalized phone (digits).
`email`	string	No	Applicant email.
`bankAccountNumberLast4`	string	No	Last 4 of bank account.
`bankRoutingNumber`	string	No	Routing number.
`occupation`	string	No	Canonicalized occupation (uppercased).
`employer`	string	No	Canonicalized employer (uppercased).
`income`	number	No	Parsed numeric income.
`requestedLoanAmount`	number	No	Parsed requested amount.
`loanStatus`	string	No	Current loan status.
`approvedLoanAmount`	number	No	Approved amount.
`recordStatus`	string	No	Overall record state.
`id`	string	No	Created record ID.
`addedBy`	string	No	Creator merchant/system.
`addedDate`	string (ISO-8601 UTC)	No	Record creation time.
`merchantType`	string	No	Channel/type of merchant.

Response

 
{
  "recordVerification": {
    "status": "Warning",
    "mismatches": [
      {
        "fieldName": "Income",
        "discrepancies": [
          {
            "recordIndex": 1,
            "inputValue": "1200",
            "valuesOnFile": "1000",
            "hasMatch": false
          }
        ]
      },
      {
        "fieldName": "Occupation",
        "discrepancies": [
          {
            "recordIndex": 1,
            "inputValue": "TECHNICAL MANAGER",
            "valuesOnFile": "TECHNICAL ENGINEER",
            "hasMatch": false
          }
        ]
      }
    ],
    "totalRecordsCompared": 2
  },
  "recordAnalysis": {
    "totalRecords": 2,
    "periodCounts": {
      "48 hours": 2,
      "1 week": 0,
      "1 month": 0,
      "3 months": 0,
      "6 months": 0,
      "9 months": 0,
      "12 months": 0,
      "2 years": 0
    },
    "summary": null,
    "lastSeen": "4 minutes ago",
    "monthsReport": null,
    "lastSeenBreakDowns": [
      {
        "recordId": "68c7db23e16639b4295c037e",
        "merchantId": "acufi001",
        "seen": "just now",
        "dateTime": "09/15/2025 02:53 PM (IST)",
        "recordedDateTime": "2025-09-15T09:23:47.971Z",
        "status": "Warning",
        "count": null,
        "loanStatus": "Pending",
        "loanStatusChangedOn": null,
        "requestedLoanAmount": 120,
        "merchantType": "Online",
        "allowLoanActions": true
      },
      {
        "recordId": "68c7da85e16639b4295c02c0",
        "merchantId": "acufi001",
        "seen": "7 minutes ago",
        "dateTime": "09/15/2025 02:51 PM (IST)",
        "recordedDateTime": "2025-09-15T09:21:09.822Z",
        "status": "FirstSeen",
        "count": null,
        "loanStatus": "PaidOff",
        "loanStatusChangedOn": "2025-09-15T09:21:24.774Z",
        "requestedLoanAmount": 100,
        "merchantType": "Online",
        "allowLoanActions": true
      }
    ],
    "loanApprovalBreakDowns": []
  },
  "recordInformation": {
    "name": "John Doe",
    "dateOfBirth": "1995-08-02",
    "ssnLast4": "2800",
    "fullAddress": "321 MAPLE DRIVE AUSTIN TX 78701",
    "phoneNumber": 8123228002,
    "email": "jdoe988@yopmail.com",
    "bankAccountNumberLast4": "7890",
    "bankRoutingNumber": "123456789",
    "occupation": "TECHNICAL MANAGER",
    "employer": "TECH SOLUCTION",
    "income": 1200,
    "requestedLoanAmount": 120,
    "loanStatus": "Pending",
    "approvedLoanAmount": 120,
    "recordStatus": "Warning",
    "id": "68c7db23e16639b4295c037e",
    "addedBy": "acufi001",
    "addedDate": "2025-09-15T09:23:47.892Z",
    "merchantType": "Online"
  }
}

6. Manage Loan Application

This API enables you to manage the loan application by approving/denying, qualify the application in pending, written off and paid off statuses.

Note:

When you send a request to manage loan application, the status options will be Approved, Denied, Written Off and Paid Off.

Request Parameters

The following are the request parameters for POST /api/LoanRecord/manage-loan-application:


Field	Data Type	Required
`id`	string	Yes
`loanStatus`	string	Yes

Request

To Approve:

[
  {
    "id": "689dd7e0901588971f51a01f",
    "loanStatus": "Approved",
  }
]

To Deny:

[
  {
    "id": "689dd7e0901588971f51a01f",
    "loanStatus": "Denied",
  }
]

To Qualify as WrittenOff:

[
  {
    "id": "689dd7e0901588971f51a01f",
    "loanStatus": "WrittenOff",
  }
]

To Qualify as PaidOff:

[
  {
    "id": "689dd7e0901588971f51a01f",
    "loanStatus": "PaidOff",
  }
]

Response Parameters

The following are the response parameters for POST /api/LoanRecord/manage-loan-application:

200 K

Table 20. Top-level fields:
Field	Data Type	Description
`summary`	object	Batch summary
`results`	array<object>	Per-record outcome

Table 21. `summary` object:
Field	Data Type	Description
`total`	number	Number of items received in the request body
`processed`	number	Number of items successfully processed

Table 22. `results[]` item:
Field	Data Type	Description
`recordId`	string	The loan record ID processed
`status`	string	Final status applied (`Approved`, `Denied`, `Pending`, `WrittenOff`, `PaidOff`)
`message`	string	Human-readable result (e.g., `"Loan has been Approved."` )

Response

When Approved:

{
  "summary": { "total": 1, "processed": 1 },
  "results": [
    {
      "recordId": "689dd7e0901588971f51a01f",
      "status": "Approved",
      "message": "Loan has been Approved."
    }
  ]
}

When Denied:

{
  "summary": { "total": 1, "processed": 1 },
  "results": [
    {
      "recordId": "689dd7e0901588971f51a01f",
      "status": "Denied",
      "message": "Loan has been Denied."
    }
  ]
}

When Qualified as WrittenOff:

{
  "summary": { "total": 1, "processed": 1 },
  "results": [
    {
      "recordId": "689dd7e0901588971f51a01f",
      "status": "WrittenOff",
      "message": "Loan has been Written Off."
    }
  ]
}

When Qualified as PaidOff:

{
  "summary": { "total": 1, "processed": 1 },
  "results": [
    {
      "recordId": "689dd7e0901588971f51a01f",
      "status": "PaidOff",
      "message": "Loan has been Paid Off."
    }
  ]
}

7. View Loan History

Using this API, you can retrieve the historical loan data for a specified borrower, including all associated loan records and their status history over time.

Request Parameters

The following are the request parameters for GET /api/LoanRecord/loan-history:


Field	Data Type	Required	Description
`recordId`	string	Yes	Loan record identifier.
`loanStatus`	string	No	Filter by status. One of: `Approved`, `Denied`, `Pending`, `WrittenOff`, `PaidOff`.

Request

api/LoanRecord/loan-history?recordId=689dd7e0901588971f51a01f&loanStatus=Status

Response Parameters

The following are the response parameters for GET /api/LoanRecord/loan-history:

Each array item represents one history record.


Field	Data Type	Description
`loanAmount`	number	Amount tied to this history entry.
`date`	string	Timestamp label (e.g., `08/14/2025 03:08 PM (GDT)`).
`loanStatus`	string	Status at that point: `Approved`, `Denied`, `Pending`, `WrittenOff`, `PaidOff`.
`recordReferenceId`	string	Reference ID for the record snapshot (e.g., `JVU2508460`).
`clientType`	string	Indicates the client type associated with the loan (e.g., `Store`, `Customer`).
`loanRecordStatusHistory`	array<object>	Timeline of status changes for this reference. See item schema below.

Table 23. `loanRecordStatusHistory[]` item
Field	Data Type	Description
`date`	string	Timestamp label at that status change.
`loanStatus`	string	Status at that change (`Approved`, `Denied`, `Pending`, `WrittenOff`, `PaidOff`).
`transactionId`	string	Unique transaction identifier for the status change (e.g., `JVU2508460-2`).
`loanAmount`	number	Amount associated with that transaction.
`payment`	object / null	Contains payment details if applicable; otherwise `null`.

Table 24. `payment`
Field	Data Type	Description
`totalPaid`	number	The total amount paid toward the loan.
`payment History`	array	List of all individual payment transactions with date and amount.

Table 25. `paymentHistory[]`
Field	Data Type	Description
`amount`	number	Amount paid in a single transaction.
`paymentDate`	string	ISO-8601 formatted timestamp indicating when the payment was made.

Response

{
    "loanAmount": 560,
    "date": "10-30-2025 12:44 PM (GDT)",
    "loanStatus": "PaidOff",
    "recordReferenceId": "ZEW2510902",
    "clientType": "Store",
    "loanRecordStatusHistory": [
        {
            "date": "10-30-2025 12:44 PM (GDT)",
            "loanStatus": "PaidOff",
            "transactionId": "ZEW2510902-3",
            "loanAmount": 560,
            "payment": {
                "totalPaid": 750,
                "paymentHistory": [
                    {
                        "amount": 150,
                        "paymentDate": "2025-10-30T07:13:55.972Z"
                    },
                    {
                        "amount": 150,
                        "paymentDate": "2025-10-30T07:13:58.394Z"
                    },
                    {
                        "amount": 150,
                        "paymentDate": "2025-10-30T07:14:01.597Z"
                    },
                    {
                        "amount": 150,
                        "paymentDate": "2025-10-30T07:14:05.459Z"
                    },
                    {
                        "amount": 150,
                        "paymentDate": "2025-10-30T07:14:08.002Z"
                    }
                ]
            }
        },
        {
            "date": "10-30-2025 12:42 PM (GDT)",
            "loanStatus": "FPD",
            "transactionId": "ZEW2510902-2",
            "loanAmount": 560,
            "payment": null
        },
        {
            "date": "10-30-2025 12:42 PM (GDT)",
            "loanStatus": "Approved",
            "transactionId": "ZEW2510902-1",
            "loanAmount": 560,
            "payment": null
        },
        {
            "date": "10-30-2025 12:40 PM (GDT)",
            "loanStatus": "Pending",
            "transactionId": "ZEW2510902",
            "loanAmount": 560,
            "payment": null
        }
    ]
}

8. Retrieve Borrower Record Details by Period

This API enables you to return a time-bucketed view of a borrower’s loan activity over standard periods (e.g., 48 Hours, 1 Week, 1 Month, 3 Months, 6 Months, 9 Months, 12 Months, 2 Years).

Request Parameters

The following are the request parameters for GET /api/v1/LoanRecord/record-period:


Name	Data Type	Required	Description
`id`	string	Yes	The loan record ID (borrower context) to analyze.

Table 26. Headers
Field	Data Type	Required	Value/Description
Authorization	string	Yes	Bearer token from `/api/Authentication/login`.
X-Timezone	string	Yes	IANA time zone (e.g., `America/Los_Angeles`).
Content-Type	string	Yes	`application/json`.

Request

GET /api/v1/LoanRecord/record-period?id=69024298c02447b1ac411690
Authorization: Bearer <token>
X-Timezone: America/Los_Angeles
Content-Type: application/json

Response Parameters

The following are the request parameters for GET /api/v1/LoanRecord/record-period:

Table 27. Top level
Field	Data Type	Description
`totalCount`	number	Total number of items found across all periods.
`recordPeriodSummary`	array	One entry per period (e.g., “48 Hours”, “1 Week”, …).

Table 28. `recordPeriodSummary[]`
Field	Data Type	Description
`periodName`	string	Period label (e.g., `48 Hours`, `1 Week`, `1 Month`, `3 Months`, `6 Months`, `9 Months`, `12 Months`, `2 Years`).
`totalCount`	number	Total items within this period.
`recordPeriodGroups`	array	Buckets within the period (e.g., Day/Week/Month/Quarter/Year).

Table 29. `recordPeriodGroups[]`
Field	Data Type	Description
`name`	string	Group name (e.g., `Day 5`, `Week 5`, `October`, `Quarter 2`, `Year (2025)`.
`subName`	string \| null	Optional sub-label (e.g., `Apr 2025 - Jul 2025`).
`count`	number	Number of items in this group.
`loanBreakdown`	array	Individual activity items for the group.

Table 30. `recordPeriodGroups[].loanBreakdown[]`
Field	Data Type	Description
`dateTime`	string (ISO 8601 UTC)	Timestamp of the record/activity.
`amount`	number	Related amount for the item (e.g., loan/payment value).
`formattedDate`	string	Display-friendly timestamp with local TZ label (e.g., `10-29-2025 09:19 AM PDT`).

Response

{
  "totalCount": 3,
  "recordPeriodSummary": [
    {
      "periodName": "48 Hours",
      "totalCount": 3,
      "recordPeriodGroups": [
        {
          "name": "Day 1",
          "subName": null,
          "count": 3,
          "loanBreakdown": [
            {
              "dateTime": "2025-10-30T12:09:44.289Z",
              "amount": 500,
              "formattedDate": "10/30/2025 05:39 PM IST"
            },
            {
              "dateTime": "2025-10-30T12:07:38.173Z",
              "amount": 500,
              "formattedDate": "10/30/2025 05:37 PM IST"
            },
            {
              "dateTime": "2025-10-30T12:30:53.081Z",
              "amount": 500,
              "formattedDate": "10/30/2025 06:00 PM IST"
            }
          ]
        },
        {
          "name": "Day 2",
          "subName": null,
          "count": 0,
          "loanBreakdown": []
        }
      ]
    }
  ]
}

Note:

Period and grouping labels are determined by the selected window (e.g., 1 Week → Day 1..7, 1 Month → Week 1..5, 3 Months → month names, 6/9/12 Months → quarters, 2 Years → years).
Errors follow the platform’s standard behavior outlined in Common Error Codes (e.g., 401 Unauthorized, 404 Not Found, 400 Invalid Request).

9. Create a Payment Record

This API enables you to creates a new payment entry for a loan.

Request Parameters

The following are the request parameters for POST/api/v1/payments:


Field	Data Type	Required	Description
`loanId`	string	Yes	Unique identifier of the loan to which the payment is applied.
`paymentAmount`	number	Yes	The payment amount for the specified loan. Must be greater than zero.
`notes`	string	No	Optional description or note for the payment transaction (e.g., ACH Payment).

Request


{ 
 "loanId": "68ef61373f492ed865d4521d", 
 "paymentAmount": 100, 
 "notes": "ACH Payment" 
}

Response Parameters

The following are the response parameters for POST/api/v1/payments:


Field	Data Type	Description
`data`	object \| null	Returned data object (null for this operation).
`message`	string	Indicates the outcome of the operation.
`error`	string \| null	Contains error details if the request fails.
`isSuccess`	boolean	Indicates whether the operation succeeded.

Response

When it's a success (200):


{
  "data": null,
  "message": "Operation completed successfully",
  "error": null,
  "isSuccess": true
}

When it's an error (400):


{
  "data": null,
  "message": null,
  "error": "Value cannot be zero",
  "isSuccess": false
}

10. Update a Payment Record

With this API, you can update an existing payment entry.

Request Parameters

The following are the request parameters for PUT /api/v1/payments:


Field	Data Type	Required	Description
`paymentId`	string	Yes	Unique identifier of the payment record to be updated.
`paymentAmount`	number	Yes	Updated payment amount for the specified payment record.
`notes`	string	No	Optional notes or remarks describing the updated payment (e.g., Updated ACH).

Request


{
  "paymentId": "68f888e26e01a693a2fecccb",
  "paymentAmount": 150,
  "notes": "Updated ACH"
}

Response Parameters

The following are the response parameters for PUT /api/v1/payments:


Field	Data Type	Description
`data`	object	Contains updated payment details returned after the operation.
`message`	string	Describes the result of the update operation.
`error`	string \| null	Contains error information, if the update fails.
`isSuccess`	boolean	Indicates whether the operation was successful.

Table 31. `data` object fields:
Field	Data Type	Description
`loanId`	string	Loan identifier to which the payment belongs.
`paymentAmount`	number	Updated payment amount.
`notes`	string	Updated notes or remarks for the payment.
`id`	string	Unique identifier of the payment record.

Response

When it's a success (200):


{
  "data": {
    "loanId": "68ef61373f492ed865d4521d",
    "paymentAmount": 150,
    "notes": "Updated ACH",
    "id": "68f888e26e01a693a2fecccb"
  },
  "message": "Operation completed successfully",
  "error": null,
  "isSuccess": true
}

When it's an error (400):


{
  "data": null,
  "message": null,
  "error": "Record not found",
  "isSuccess": false
}

11. Retrieve Total Payments for a Loan

This API allows you to retrieve the total sum of payments for any specific loan.

Request Parameters

The following are the request parameters for GET /api/v1/payments/{loanId}/total:

Table 32. Path Parameters
Field	Data Type	Required	Description
`loanId`	string	Yes	Unique identifier of the target loan.

Table 33. Headers
Field	Data Type	Required	Value/Description
Authorization	string	Yes	Bearer token from `/api/Authentication/login`.
X-Timezone	string	Yes	IANA time zone (e.g., `America/Los_Angeles`).
Content-Type	string	Yes	`application/json`

Request

GET /api/v1/payments/68ef61373f492ed865d4521d/total
Authorization: Bearer <token>
X-Timezone: America/Los_Angeles
Content-Type: application/json

Response Parameters

The following are the response parameters for GET /api/v1/payments/{loanId}/total :


Field	Data Type	Description
`data`	number	The total of all payments recorded for the loan.
`message`	string \| null	Informational message (null if not set).
`error`	string \| null	Error details if the operation fails (null on success).
`isSuccess`	boolean	Indicates whether the operation succeeded.

Response


{ 
  "data": 250, 
  "message": null, 
  "error": null, 
  "isSuccess": true 
}

12. Retrieve All Payments for a Loan

This API allows you to retrieve all payments associated with a loan.

Request Parameters

The following are the request parameters for GET /api/v1/payments/loanId?loanId={loanId} :

Table 34. Path Parameters
Field	Data Type	Required	Description
`loanId`	string	Yes	Unique identifier of the loan whose payments are to be retrieved.

Table 35. Headers
Field	Data Type	Required	Value/Description
Authorization	string	Yes	Bearer token obtained from `/api/Authentication/login`.
X-Timezone	string	Yes	IANA time zone identifier (e.g., `America/Los_Angeles`).
Content-Type	string	Yes	`application/json`.

Request


GET /api/v1/payments/loanId?loanId=68ef61373f492ed865d4521d
Authorization: Bearer <token>
X-Timezone: America/Los_Angeles
Content-Type: application/json

Response Parameters

The following are the response parameters for GET /api/v1/payments/loanId?loanId={loanId} :


Field	Data Type	Description
`data`	array	List of all payments linked to the specified loan.
`message`	string	Indicates the result of the operation.
`error`	string \| null	Contains error details if the operation fails.
`isSuccess`	boolean	Indicates whether the request was successful.

Table 36. `data` array object fields
Field	Data Type	Description
`loanId`	string	Unique identifier of the loan.
`paymentAmount`	number	Amount paid in the transaction.
`notes`	string	Notes or remarks for the payment.
`id`	string	Unique identifier of the payment record.
`addedBy`	string	User who added the payment entry.
`addedDate`	string (ISO 8601 UTC)	Timestamp of when the payment was created.
`updatedDate`	string (ISO 8601 UTC)	Timestamp of the last update.
`isActive`	boolean	Indicates whether the payment is active.
`isDeleted`	boolean	Indicates whether the payment has been soft deleted.

Response

When it's a success (200):


{
  "data": [
    {
      "loanId": "68ef61373f492ed865d4521d",
      "paymentAmount": 150,
      "notes": "Updated ACH",
      "id": "68f888e26e01a693a2fecccb",
      "addedBy": "admin",
      "addedDate": "2025-10-22T07:33:54.667Z",
      "updatedDate": "2025-10-22T07:43:53.283Z",
      "isActive": true,
      "isDeleted": false
    },
    {
      "loanId": "68ef61373f492ed865d4521d",
      "paymentAmount": 100,
      "notes": "ACH Payment",
      "id": "68f889636e01a693a2fecccf",
      "addedBy": "admin",
      "addedDate": "2025-10-22T07:36:03.741Z",
      "updatedDate": "2025-10-22T07:36:03.741Z",
      "isActive": true,
      "isDeleted": false
    }
  ],
  "message": "Operation completed successfully",
  "error": null,
  "isSuccess": true
}

When it's an error (400):


{
  "data": null,
  "message": null,
  "error": "Record not found",
  "isSuccess": false
}

13. Delete a Payment Record

With this API, you can soft delete/deactivate a payment by its Id.

Request Parameters

The following are the request parameters for DELETE/api/v1/payments/{paymentId}:

Table 37. Path Parameters
Field	Data Type	Required	Description
`paymentId`	string	Yes	Unique identifier of the payment record.

Table 38. Headers
Field	Data Type	Required	Value/Description
Authorization	string	Yes	Bearer token from `/api/Authentication/login`.
X-Timezone	string	Yes	IANA time zone (e.g., `America/Los_Angeles`).
Content-Type	string	Yes	`application/json`

Request

DELETE /api/v1/payments/68f888e26e01a693a2fecccb
Authorization: Bearer <token>
X-Timezone: America/Los_Angeles
Content-Type: application/json

Response Parameters

The following are the response parameters for DELETE/api/v1/payments/{paymentId}:


Field	Data Type	Description
`message`	string	Outcome message for the operation.
`error`	string \| null	Error details if the operation fails (null on success).
`isSuccess`	boolean	Indicates whether the operation succeeded.

Response

When it's a success (200):


{
  "message": "Operation completed successfully",
  "error": null,
  "isSuccess": true
}

When it's an error (400):


{
  "data": null,
  "message": null,
  "error": "Record not found",
  "isSuccess": false
}

14. Assess Risk of Borrower

This API evaluates borrower data across a defined time period and returns profitability, success, and recommendation scores.

Request Parameters

The following are the request parameters for GET/api/v1/payments/AssessRisk:


Field	Data Type	Required	Description
`lastName`	string	Yes	Borrower’s last name used for identification.
`last4Ssn`	string	Yes	Last four digits of the borrower’s Social Security Number.
`daysToAssess`	number	Yes	The number of past days to include in the risk assessment (for example, `730` = two years).

Table 39. Headers
Field	Data Type	Required	Value/Description
Authorization	string	Yes	Bearer token obtained from `/api/Authentication/login`.
X-Timezone	string	Yes	IANA time zone identifier (e.g., `America/Los_Angeles`).
Content-Type	string	Yes	`application/json`.

Request

GET /api/v1/payments/AssessRisk?lastName=KELLEY&last4Ssn=4234&daysToAssess=730
Authorization: Bearer <token>
X-Timezone: America/Los_Angeles
Content-Type: application/json

Response Parameters

The following are the response parameters for GET/api/v1/payments/AssessRisk:


Field	Data Type	Description
`borrower`	string	Borrower’s last name as provided in the request.
`profitabilityScore`	number	Indicates the borrower’s overall profitability for the lender.
`successRate`	number	Represents the borrower’s historical repayment success rate (percentage).
`trend`	number	Indicates the direction of borrower performance over time (higher = improving).
`recommendationScore`	number	Final composite score recommending borrower reliability (0–100).

Response

When it's a success (200):

{
  "borrower": "KELLEY",
  "profitabilityScore": 100,
  "successRate": 100,
  "trend": 50,
  "recommendationScore": 85
}

When it's an error (400):

"No loans found for this borrower."