Relationships API

This API allows managing relationships between borrowers. It provides endpoints to create, read, update, and delete relationships, as well as to perform queries and obtain relationship summaries.

The Relationship Object

The Relationship object represents a relationship between a borrower and a contact in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "borrowerId": "b789-12d3-a456-426614174001",
  "contactId": "c123-45d6-b789-012345678902",
  "priority": 1,
  "isActive": true,
  "isLegalRepresentative": false,
  "relationship": "shareholder",
  "ownershipPct": 25.5,
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-04-01T12:00:00Z"
}

Attributes

Attribute	Description	Type
`id`	Unique identifier of the relationship	String
`borrowerId`	ID of the borrower associated with the relationship	String
`contactId`	ID of the contact associated with the relationship	String
`priority`	Priority of the relationship	Integer
`isActive`	Indicates if the relationship is active	Boolean
`isLegalRepresentative`	Indicates if the contact is a legal representative	Boolean
`relationship`	Type of relationship (shareholder, employee, family, other, unspecified)	String
`ownershipPct`	Ownership percentage (only for shareholders)	Float
`createdAt`	Date and time of relationship creation	String (ISO 8601)
`updatedAt`	Date and time of the last relationship update	String (ISO 8601)

Available Operations

Create a New Relationship

Creates a new relationship between a borrower and a contact.

POST /v1/relationships

Input Parameters:

Parameter	Description	Type	Required
`borrowerId`	ID of the borrower	String	Yes
`contactId`	ID of the contact	String	Yes
`priority`	Priority of the relationship	Integer	No
`relationship`	Type of relationship	String	No
`isLegalRepresentative`	Indicates if it is a legal representative	Boolean	No
`isActive`	Indicates if the relationship is active	Boolean	No
`ownershipPct`	Ownership percentage (only for shareholders)	Float	No

Example Request:

{
  "borrowerId": "b789-12d3-a456-426614174001",
  "contactId": "c123-45d6-b789-012345678902",
  "priority": 1,
  "relationship": "shareholder",
  "isLegalRepresentative": false,
  "isActive": true,
  "ownershipPct": 25.5
}

Successful Response:

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

Update a Relationship

Updates an existing relationship.

PATCH /v1/relationships/:relationship_id

Input Parameters:

Parameter	Description	Type	Required
`priority`	New priority of the relationship	Integer	No
`relationship`	New type of relationship	String	No
`isLegalRepresentative`	New legal representative status	Boolean	No
`isActive`	New activity status	Boolean	No
`ownershipPct`	New ownership percentage	Float	No

Example Request:

{
  "priority": 2,
  "isActive": false
}

Successful Response:

Returns the updated Relationship object.

Delete a Relationship

Deletes an existing relationship.

DELETE /v1/relationships/:relationship_id

Successful Response:

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

Get a Relationship

Retrieves information about a specific relationship.

GET /v1/relationships/:relationship_id

Successful Response:

Returns the complete Relationship object.

List Relationships

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

GET /v1/relationships

Query Parameters:

Parameter	Description	Type
`borrower-id`	Filter by borrower ID	String
`priority`	Filter by priority	String
`is-legal-representative`	Filter by legal representative	Boolean
`search`	Text to search	String
`page`	Page number	Integer
`per-page`	Items per page	Integer
`sort-by`	Field to sort by	String
`sort-direction`	Sorting direction (asc or desc)	String

Successful Response:

Paginated list of Relationship objects.

Get Relationship Summary

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

GET /v1/relationships-summary

Query Parameters:

Parameter	Description	Type
`borrower-id`	Filter by borrower ID	String
`page`	Page number	Integer
`per-page`	Items per page	Integer
`persona`	Filter by person type	String
`sort-by`	Field to sort by	String
`sort-direction`	Sorting direction (asc or desc)	String

Successful Response:

Summary of relationships according to specified criteria.

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