Borrower Fields API

This API allows managing custom fields associated with borrowers in the system. It provides endpoints to create, read, update, and delete borrower fields, as well as to perform queries and searches on these fields.

BorrowerField Object

The BorrowerField object represents a custom field associated with a borrower.

JSON Example:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "borrowerId": "789e4567-e89b-12d3-a456-426614174001",
  "key": "income",
  "label": "Annual Income",
  "value": 50000,
  "dataType": "number",
  "tags": ["financial", "yearly"],
  "history": [
    {
      "referenceId": "form123",
      "value": 50000,
      "updatedAt": "2023-01-01T00:00:00Z"
    }
  ],
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z"
}

Attributes

Attribute	Description	Type
id	Unique identifier of the field	String
borrowerId	Associated borrower's ID	String
key	Key or name of the field	String
label	Descriptive label of the field (optional)	String
value	Value of the field	Any
dataType	Data type of the value	String
tags	Tags associated with the field	Array of String
history	History of field values	Array of Object
createdAt	Date and time of field creation	String (ISO 8601)
updatedAt	Date and time of the last field update	String (ISO 8601)

Available Operations

Create a Borrower Field

Creates a new borrower field in the system.

POST /v1/borrower-fields

Input Parameters:

Parameter	Description	Type	Required
borrowerId	Borrower's ID	String	Yes
formId	Form ID (optional)	String	No
referenceId	Reference ID (optional)	String	No
key	Key or name of the field	String	Yes
value	Value of the field	Any	Yes
dataType	Data type of the value	String	Yes
tags	Tags associated with the field	Array of String	No

Request Example:

{
  "borrowerId": "789e4567-e89b-12d3-a456-426614174001",
  "formId": "form123",
  "key": "income",
  "value": 50000,
  "dataType": "number",
  "tags": ["financial", "yearly"]
}

Successful Response:

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

Update a Borrower Field

Updates an existing borrower field.

PATCH /v1/borrower-fields/:field_id

Path Parameters:

Parameter	Description
field_id	ID of the field to update

Input Parameters:

Parameter	Description	Type	Required
borrowerId	Borrower's ID	String	Yes
formId	Form ID (optional)	String	No
referenceId	Reference ID (optional)	String	No
value	New value of the field	Any	Yes
tags	New tags associated with the field	Array of String	No

Request Example:

{
  "borrowerId": "789e4567-e89b-12d3-a456-426614174001",
  "referenceId": "form124",
  "value": 55000,
  "tags": ["financial", "yearly", "updated"]
}

Successful Response:

The response will be the updated BorrowerField object.

Get a Borrower Field

Retrieves information of a specific borrower field.

GET /v1/borrower-fields/:field_id

Path Parameters:

Parameter	Description
field_id	ID of the field to retrieve

Successful Response:

The response will be the complete BorrowerField object.

Delete a Borrower Field

Deletes a borrower field from the system.

DELETE /v1/borrower-fields/:field_id

Path Parameters:

Parameter	Description
field_id	ID of the field to delete

Successful Response:

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

List Borrower Fields

Retrieves a paginated list of borrower fields with filtering and sorting options.

GET /v1/borrower-fields

Query Parameters:

Parameter	Description	Type
borrower-id	Filter by borrower ID	String
key	Filter by field key	String
value	Filter by exact field value	String
form-id	Filter by form ID	String
search	Text to search in fields	String
page	Page number (default: 1)	Integer
per-page	Items per page (default: 10)	Integer
sort-by	Field to sort by	String
sort-direction	Sorting direction (asc or desc)	String

Successful Response:

The response will be a paginated list of BorrowerField objects.

[Query] Get Existing Values of a Borrower Field

GET /v1/borrower-fields/queries/count-distinct-values

Query Parameters:

Parameter	Description	Type
key	Key of the field to query (mandatory)	String

Successful Response:

The response will be the set of all values present in the queried model.

[Command] Update All X Values of a Borrower Field to a Y Value

POST /v1/borrower-fields/commands/bulk-update-values

Input Parameters

Parameter	Description	Type	Required
key	Field key	String	Yes
currentValue	Value to be replaced	String	Yes
targetValue	New value	String	Yes

Request Example:

{
  "key": "nationality",
  "currentValue": "mexican",
  "targetValue": "MX"
}

Successful Response:

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

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Errors will include a descriptive message in the response body.

On this page