Contact Points API

This API allows managing contact points (PoC) associated with borrowers in the system. It provides endpoints to create, read, update, delete, and verify contact points, as well as to perform queries on them.

The Point of Contact Object

The Point of Contact object represents a contact point associated with a borrower in the system.

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "label": "Main Phone",
    "contactMethod": "phone",
    "value": "+34600000000",
    "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
    "isVerified": true,
    "priority": 1,
    "verifiedAt": "2023-04-01T12:00:00Z",
    "tags": ["main", "verified"],
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-04-01T12:00:00Z",
    "signatures": ["sig123", "sig456"]
}

Attributes

Attribute	Description	Type
`id`	Unique identifier of the contact point	String
`label`	Descriptive label of the contact point	String
`contactMethod`	Contact method (phone or email)	String
`value`	Value of the contact point (phone number or email address)	String
`borrowerId`	Identifier of the associated borrower	String
`isVerified`	Indicates if the contact point has been verified	Boolean
`priority`	Priority of the contact point	Integer
`verifiedAt`	Date and time of contact point verification	String (ISO 8601)
`tags`	List of tags associated with the contact point	Array of String
`createdAt`	Date and time of contact point creation	String (ISO 8601)
`updatedAt`	Date and time of the last update of the contact point	String (ISO 8601)
`signatures`	List of associated signature identifiers	Array of String

Available Operations

Create a New Contact Point

Creates a new contact point in the system.

POST /v1/points-of-contact

Input Parameters:

Parameter	Description	Type	Required
`borrowerId`	ID of the associated borrower	String	Yes
`label`	Descriptive label of the contact point	String	No
`contactMethod`	Contact method (phone or email)	String	Yes
`value`	Value of the contact point	String	Yes
`priority`	Priority of the contact point	Integer	No
`tags`	List of tags	Array of String	No

Example Request:

{
    "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
    "label": "Main Phone",
    "contactMethod": "phone",
    "value": "+34600000000",
    "priority": 1,
    "tags": ["main"]
}

Successful Response:

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

Get a Contact Point

Retrieves the information of a specific contact point.

GET /v1/points-of-contact/:point_of_contact_id

Path Parameters:

Parameter	Description
`point_of_contact_id`	ID of the contact point to retrieve

Successful Response:

The response will be a Point of Contact object.

Update a Contact Point

Updates the information of an existing contact point.

PATCH /v1/points-of-contact/:point_of_contact_id

Path Parameters:

Parameter	Description
`point_of_contact_id`	ID of the contact point to update

Input Parameters:

Parameter	Description	Type	Required
`label`	New descriptive label	String	No
`contactMethod`	New contact method	String	No
`value`	New value of the contact point	String	No
`priority`	New priority	Integer	No
`tags`	New list of tags	Array of String	No

Example Request:

{
    "label": "Secondary Phone",
    "priority": 2,
    "tags": ["secondary", "updated"]
}

Successful Response:

The response will be the updated Point of Contact object.

Delete a Contact Point

Deletes a contact point from the system.

DELETE /v1/points-of-contact/:point_of_contact_id

Path Parameters:

Parameter	Description
`point_of_contact_id`	ID of the contact point to delete

Successful Response:

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

Initiate Contact Point Verification

Initiates the verification process of a contact point by sending an OTP.

POST /v1/points-of-contact/:point_of_contact_id/verification

Path Parameters:

Parameter	Description
`point_of_contact_id`	ID of the contact point to verify

Input Parameters:

Parameter	Description	Type	Required
`templateId`	ID of the template for the OTP message	String	Yes

Example Request:

{
    "templateId": "otp_verification_template_001"
}

Successful Response:

{
    "otpId": "otp_123456789"
}

Verify a Contact Point

Verifies a contact point using the sent OTP code.

POST /v1/points-of-contact/:point_of_contact_id/verification/attempt

Path Parameters:

Parameter	Description
`point_of_contact_id`	ID of the contact point to verify

Input Parameters:

Parameter	Description	Type	Required
`otpId`	ID of the sent OTP	String	Yes
`code`	Received OTP code	String	Yes

Example Request:

{
    "otpId": "otp_123456789",
    "code": "123456"
}

Successful Response:

Status code 202 (Accepted) if the verification was successful.

List Contact Points

Retrieves a paginated list of contact points with filtering and sorting options.

GET /v1/points-of-contact

Query Parameters:

Parameter	Description	Type
`borrower-id`	Filter by borrower ID	String
`contact-method`	Filter by contact method	String
`priority`	Filter by priority	Integer
`search`	Text to search in contact points	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 Point of Contact objects.

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