Categories API

This API allows managing categories and their values in the system. It provides endpoints to create, read, update and delete categories, as well as to manage the values associated with each category.

The Category Object

The Category object represents a category in the system.

A category is an extension of lender fields, which allows assigning predetermined values to any entity in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "categoryKey": "document_type",
  "label": "Document Type",
  "createdAt": "2023-05-01T12:00:00Z",
  "updatedAt": "2023-05-02T14:30:00Z"
}

Attributes

The CategoryValue Object

The CategoryValue object represents a value within a category.

{
  "id": "456e7890-e89b-12d3-a456-426614174001",
  "categoryId": "123e4567-e89b-12d3-a456-426614174000",
  "categoryKey": "document_type",
  "value": "Identity Card",
  "createdAt": "2023-05-01T12:00:00Z",
  "updatedAt": "2023-05-02T14:30:00Z"
}

Attributes

Available Operations

Create a New Category

Creates a new category in the system.

POST /v1/category

Input Parameters:

Request Example:

{
  "categoryKey": "document_type",
  "label": "Document Type"
}

Successful Response:

The response will be the UUID of the newly created Category object.

Get All Categories

Gets a list of all available categories.

GET /v1/category

Successful Response:

The response will be a list of Category objects.

Get a Category

Gets information for a specific category.

GET /v1/category/{category_id}

Path Parameters:

Successful Response:

The response will be a complete Category object.

Delete a Category

Deletes a category from the system.

DELETE /v1/category/{category_id}

Path Parameters:

Successful Response:

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

Error response:

Status code 419 (Conflict) if the deletion failed due to it having CategoryValues attached.

Create a Category Value

Creates a new value within a specific category.

POST /v1/category/{category_id}/value

Path Parameters:

Input Parameters:

Request Example:

{
  "id": "identity_card_id",
  "value": "Identity Card"
}

Successful Response:

The response will be the complete created CategoryValue object. Note that if no ID is provided, one will be created based on the value (example: "identity_card").

Get All Values of a Category

Gets all values associated with a specific category.

GET /v1/category/{category_id}/values

Path Parameters:

Successful Response:

The response will be a list of CategoryValue objects.

Update a Category Value

Updates the value of a specific element within a category.

PATCH /v1/category/{category_id}/value/{category_value_id}/label

Path Parameters:

Input Parameters:

Request Example:

{
  "value": "National Identity Document"
}

Successful Response:

The response will be the updated CategoryValue object.

Delete a Category Value

Deletes a specific value from a category.

DELETE /v1/category/{category_id}/value/{category_value_id}

Path Parameters:

Successful Response:

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

Error Response:

Status code 419 (Conflict) if deletion failed due to a entity having this CategoryValue.

Required Permissions

All operations in this API require specific permissions:

• Read operations (GET): Require the borrowers.read permission
• Write operations (POST, PATCH, DELETE): Require the borrowers.write permission

Category Commands

This section describes the available commands for special operations with categories.

Categorize an Entity

Associates a specific entity with a category value. The supported entities are:

• borrowers or borrowers_ds (use borrowers_ds if you intend to inherit the category to all debts of the categorized borrower)
• debts
• flows (in case of unfolded information)

POST /v1/category/commands/categorize-entity

Input Parameters:

Request Example:

{
  "categoryKey": "document_type",
  "categoryValueId": "identity_card_id",
  "entityId": "789f0123-e89b-12d3-a456-426614174002",
  "entityType": "borrowers_ds"
}

Successful Response:

The response will confirm the successful association between the entity and the category value.

Delete All Values of a Category

Deletes all values associated with a specific category.

POST /v1/category/commands/delete-all-values

Input Parameters:

Request Example:

{
  "categoryKey": "document_type"
}

Successful Response:

Status code 200 confirming that all values were successfully deleted.

Delete Entity Categorization

Removes the association between a specific entity and a category value.

POST /v1/category/commands/delete-entity-category

Input Parameters:

Request Example:

{
  "categoryKey": "document_type",
  "categoryValueId": "identity_card_id",
  "entityId": "789f0123-e89b-12d3-a456-426614174002",
  "entityType": "borrowers_ds"
}

Successful Response:

The response will confirm that the association was successfully deleted.

Permissions for Commands

All category commands require the borrowers.write permission for execution.

Category Queries

This section describes the specialized queries available to get information about categories.

Get Categories of an Entity

Gets all categories associated with a specific entity.

GET /v1/category/queries/entity/{entity_type}/{entity_id}

Path Parameters:

Request Example:

GET /v1/category/queries/entity/borrower/789f0123-e89b-12d3-a456-426614174002

Successful Response:

The response will be a list of categories associated with the specified entity.

[
  {
    "categoryKey": "document_type",
    "categoryValueId": "identity_card_id",
    "categoryId": "123e4567-e89b-12d3-a456-426614174000",
    "entityId": "789f0123-e89b-12d3-a456-426614174002",
    "entityType": "borrowers_ds"
  },
  {
    "categoryKey": "marital_status",
    "categoryValueId": "single",
    "categoryId": "789a0123-e89b-12d3-a456-426614174003",
    "entityId": "789f0123-e89b-12d3-a456-426614174002",
    "entityType": "borrowers"
  }
]

Permissions for Queries

Category queries require the borrowers.read permission for execution.

Error Handling

The API may return the following error codes:

Errors will include a descriptive message in the response body.