Validate Key

Overview

This endpoint validates a Bre-B Key and optionally compares additional information such as participant, account, and owner details.

You can submit a Bre-B key (create by you or not) along with optional additional information. The API then returns a boolean‐style match response (e.g., MATCH / NO_MATCH) to indicate whether the key corresponds to the expected individual.

Important Privacy Safeguard

If the submitted information does not match the resolved owner of the key, you will not receive any PII of the correct owner. This enables validation without revealing confidential information.

Endpoint Behavior

The key object is required.
The objects participant, account, and owner are optional, when included, each will be checked independently.
Each field returns a match indicator (MATCH / NO_MATCH).
If the submitted key does not exist or is not ACTIVE, the API returns HTTP 404.

Endpoint Details

Definition	Description
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/validate-key
Method	POST
Headers	Content-Type: application/json, Authorization
Authentication	Access Token (Bearer Token)

Request Body

Field	Type	Required	Description
key	Object	Yes	Key to validate
key.key_type	String	Yes	Key type (e.g., `PHONE` `BCODE`, `EMAIL`, `ID`, or `ALPHA`)
key.key_value	String	Yes	Key value
participant	Object	Optional	Participant comparison data
participant.identification_number	String	Optional	Participant NIT
participant.name	String	Optional	Participant name
account	Object	Optional	Account comparison data
account.account_type	String	Optional	Account type (e.g., `ORDINARY` or `LOW_VALUE`)
account.account_number	String	Optional	Account number
owner	Object	Optional	Account owner information
owner.first_name	String	Optional	First name
owner.second_name	String	Optional	Middle name
owner.first_last_name	String	Optional	Surname
owner.second_last_name	String	Optional	Second surname
owner.type	String	Optional	Owner type (e.g., `INDIVIDUAL`or `BUSINESS`)
owner.identification_type	String	Optional	ID type (e.g., `CC`)
owner.identification_number	String	Optional	ID number

Example Request

curl --location --request POST 'https://api.paas.sandbox.co.passportfintech.com/v1/validate-key' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --data '{ "key": { "key_type": "PHONE", "key_value": "3975999158" }, "participant": { "identification_number": "123456789", "name": "Bancolombia" }, "account": { "account_type": "ORDINARY", "account_number": "88758829529" }, "owner": { "first_name": "Ligia", "second_name": "Abril", "first_last_name": "Flores", "second_last_name": "Benhumea", "type": "INDIVIDUAL", "identification_type": "CC", "identification_number": "642349532" } }'

Response

HTTP Status Code: 200 OK.
The response will contain the validation details of the key.

Example of Response

{ "key": { "key_type": "PHONE", "key_value": "3975999158" }, "participant": { "identification_number": "MATCH", "name": "MATCH" }, "account": { "account_type": "MATCH", "account_number": "NO MATCH" }, "owner": { "first_name": "MATCH", "second_name": "MATCH", "first_last_name": "NO MATCH", "second_last_name": "MATCH", "type": "MATCH", "identification_type": "MATCH", "identification_number": "MATCH" } }

Common Errors and Handling

HTTP Status Code	Meaning	Description
400 Bad Request	Invalid request	Malformed JSON or invalid fields
401 Unauthorized	Missing/expired token	Bearer token invalid or expired
403 Forbidden	Not allowed	Caller not permitted to validate keys
404 Not Found	Key invalid	Key does not exist or is not ACTIVE
500 Internal Server Error	Server error	Unexpected system error

Best Practices

Always include the key object, all other fields are optional.
Use optional validation blocks (account, participant, owner) only if you need to verify related information.

Last updated on