Identities API

This API allows managing borrower identities in the system. It provides endpoints to create, read, update, and delete identities, as well as manage their attachments.

The Identity Object

The Identity object represents an identity associated with a borrower in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
  "key": "dni",
  "label": "National Identity Document",
  "value": "12345678A",
  "priority": 1,
  "tags": ["official", "current"],
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-04-01T12:00:00Z",
  "hasAttachments": true
}

Attributes

Sensitive identities

If the identity key is configured as sensitive in its DataModel (isSensitive: true):

• The value returned by GET/LIST endpoints is masked as __sensitive__.
• Plaintext is only available via the unmask endpoint below (subject to permissions).

Available Operations

Create a New Identity

Creates a new identity for a borrower.

POST /v1/identities

Input Parameters:

Note: If the identity key is sensitive, the service will encrypt the provided value. Subsequent reads return the masked sentinel __sensitive__.

Request Example:

{
  "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
  "key": "dni",
  "value": "12345678A",
  "tags": ["official", "current"]
}

Successful Response:

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

Get an Identity

Retrieves information of a specific identity.

GET /v1/identities/:identity_id

Path Parameters:

Successful Response:

The response will be a complete Identity object, as described above.

Unmask an Identity (Sensitive keys only)

Returns the plaintext value for a sensitive identity.

GET /v1/identities/:identity_id/unmask

Path Parameters:

Successful Response:

{
  "value": "12345678A"
}

Note: This endpoint requires private read permission (e.g. bc.private.read) and is not allowed for form tokens.

Update an Identity

Updates information of an existing identity.

PATCH /v1/identities/:identity_id

Path Parameters:

Input Parameters:

Request Example:

{
  "value": "87654321B",
  "tags": ["official", "current", "updated"]
}

Successful Response:

The response will be the updated Identity object.

Note: If the identity key is sensitive, updating value will re-encrypt it. Reads will still return __sensitive__, and unmask will return the updated plaintext.

Delete an Identity

Deletes an identity from the system.

DELETE /v1/identities/:identity_id

Path Parameters:

Successful Response:

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

List Identities

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

GET /v1/identities

Query Parameters:

Successful Response:

The response will be a paginated list of Identity objects.

Notes:

• When querying by value, you must also provide key.
• value queries are not allowed for sensitive identity keys.

Add an Attachment to an Identity

Adds an attachment to a specific identity.

POST /v1/identities/:identity_id/attachments

Path Parameters:

Input Parameters:

Request Example:

{
  "url": "https://example.com/document.pdf",
  "label": "Scanned DNI"
}

Successful Response:

Status code 201 (Created) if the attachment was added successfully.

Get Attachments of an Identity

Retrieves the list of attachments for a specific identity.

GET /v1/identities/:identity_id/attachments

Path Parameters:

Successful Response:

The response will be a list of Attachment objects.

Delete an Attachment from an Identity

Deletes a specific attachment from an identity.

DELETE /v1/identities/:identity_id/attachments/:attachment_id

Path Parameters:

Successful Response:

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

Error Handling

The API may return the following error codes:

Errors will include a descriptive message in the response body.