Retrieve a Biometric Validation

GET https://api.verifik.co/v2/biometric-validations/{id}

A Biometric Validation is an instance within Verifik's system that allows you to process and validate user identities through facial recognition and liveness detection. This endpoint retrieves a specific biometric validation record by its unique identifier, including all associated data and relationships.

Headers

Name	Value
Authorization	Bearer {YOUR_ACCESS_TOKEN}

Path Parameters

Name	Type	Required	Description
id	string	Yes	The unique identifier of the biometric validation to retrieve.

Query Parameters

Basic Query Parameters

Parameter	Type	Description	Example
populates[]	array	Fields to populate with related data.	populates[]=client&populates[]=project

Advanced Query Parameters

Parameter	Type	Description	Example
sort	string	Sort order for results. Prefix with - for descending.	sort=-createdAt
limit	number	Maximum number of results to return.	limit=10

Filter Query Parameters

Parameter	Type	Description	Example
where_client	string	Filter by client ID.	where_client=507f1f77bcf86cd799439013
where_project	string	Filter by project ID.	where_project=507f1f77bcf86cd799439011
where_projectFlow	string	Filter by project flow ID.	where_projectFlow=507f1f77bcf86cd799439015
where_status	string	Filter by validation status.	where_status=validated
where_type	string	Filter by validation type.	where_type=login
where_livenessSession	string	Filter by liveness session ID.	where_livenessSession=674de8df21c72be3cc42b8a7

Comparison Operators

Parameter	Type	Description	Example
where<_createdAt	string	Filter records created before a date.	where<_createdAt=2024-12-01
where>_createdAt	string	Filter records created after a date.	where>_createdAt=2024-12-01
where<=_createdAt	string	Filter records created on or before a date.	where<=_createdAt=2024-12-01
where>=_createdAt	string	Filter records created on or after a date.	where>=_createdAt=2024-12-01
wherenot_status	string	Filter records where status is not equal to value.	wherenot_status=failed
where-null_field	string	Filter records where field is null.	where-null_redirectUrl
where-not-null_field	string	Filter records where field is not null.	where-not-null_redirectUrl

Array and Pattern Matching

Parameter	Type	Description	Example
in_status	array	Filter records where status is in the specified array.	in_status[]=validated&in_status[]=failed
notIn_status	array	Filter records where status is not in the specified array.	notIn_status[]=expired
like_name	string	Filter records where name contains the specified string (case-insensitive).	like_name=john
notLike_name	string	Filter records where name does not contain the specified string.	notLike_name=test

Request Examples

Basic Request

curl -X GET "https://api.verifik.co/v2/biometric-validations/674de8df21c72be3cc42b8a8" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

With Populates

curl -X GET "https://api.verifik.co/v2/biometric-validations/674de8df21c72be3cc42b8a8?populates[]=client&populates[]=project&populates[]=livenessSession" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

With Field Selection

curl -X GET "https://api.verifik.co/v2/biometric-validations/674de8df21c72be3cc42b8a8?columns=status,type,createdAt,url" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

With Filters

curl -X GET "https://api.verifik.co/v2/biometric-validations/674de8df21c72be3cc42b8a8?where_status=validated&where_type=login" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Complex Query

curl -X GET "https://api.verifik.co/v2/biometric-validations/674de8df21c72be3cc42b8a8?populates[]=client&populates[]=project&columns=status,type,createdAt,url&where>_createdAt=2024-12-01&sort=-createdAt" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

The response will contain the biometric validation record with all requested fields and populated relationships.

200

{
  "data": {
    "_id": "674de8df21c72be3cc42b8a8",
    "client": {
      "_id": "507f1f77bcf86cd799439013",
      "name": "Example Client",
      "status": "active"
    },
    "project": {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Example Project",
      "status": "active"
    },
    "projectFlow": {
      "_id": "507f1f77bcf86cd799439015",
      "name": "Login Flow",
      "type": "login"
    },
    "livenessSession": {
      "_id": "674de8df21c72be3cc42b8a7",
      "identifier": "[email protected]",
      "status": "completed",
      "expiresAt": "2024-12-02T17:15:35.000Z"
    },
    "status": "validated",
    "type": "login",
    "url": "https://access.verifik.co/sign-in/507f1f77bcf86cd799439011?type=liveness",
    "assignedCollection": "507f1f77bcf86cd799439016",
    "collectionCode": "col_12345",
    "livenessScore": 0.85,
    "response": {
      "liveness": {
        "score": 0.85,
        "status": "passed"
      },
      "persons": [
        {
          "id": "674de8df21c72be3cc42b8ab",
          "name": "John Doe",
          "score": 0.92
        }
      ]
    },
    "redirectUrl": null,
    "webhook": null,
    "requires2FA": false,
    "createdAt": "2024-12-02T17:05:36.788Z",
    "updatedAt": "2024-12-02T17:15:36.788Z"
  }
}

204

{
  "data": null
}

403

{
  "code": "Forbidden",
  "message": "access_denied"
}

404

{
  "code": "biometric_validation_not_found",
  "message": "404:biometric_validation_not_found"
}

Response Fields

Field	Type	Description
_id	string	Unique identifier of the biometric validation.
client	object	Client information (populated if requested).
project	object	Project information (populated if requested).
projectFlow	object	Project flow configuration (populated if requested).
livenessSession	object	Liveness detection session details (populated if requested).
status	string	Current validation status (new, sent, validated, failed, expired).
type	string	Type of validation process (validation, login, onboarding, oneTimeLink).
url	string	URL where users complete their biometric verification.
assignedCollection	string	Reference to the assigned collection for biometric data.
collectionCode	string	Collection identifier for biometric data storage.
livenessScore	number	Liveness detection score (0.0 to 1.0).
response	object	Detailed response from the biometric validation process.
redirectUrl	string	Optional URL for redirect after validation.
webhook	string	Optional webhook configuration.
requires2FA	boolean	Whether two-factor authentication is required.
createdAt	string	When the validation was created.
updatedAt	string	When the validation was last updated.

Notes

• Authentication Required: Users must have a valid access token with appropriate permissions.

• Access Control: Users can only access biometric validations for their own client or with super admin privileges.

• Liveness Session Access: Users with liveness session tokens can access related validations.

• Populate Relationships: Use populates[] to include related data like client, project, and liveness session information.

• Field Selection: Use columns or select to limit the fields returned in the response.

• Filtering: Apply various filters to narrow down results based on specific criteria.

• Sorting: Use sort parameter to order results by specific fields.

• Performance: Use lean=true for better performance when you don't need Mongoose document features.

Common Use Cases

• Status Checking: Retrieve validation status and results for user feedback.

• Audit Trails: Access detailed validation information for compliance and reporting.

• Integration: Get validation data for webhook processing or external system integration.

• User Management: Retrieve validation details for user account management.

• Analytics: Collect validation data for performance analysis and optimization.

Query Parameter Best Practices

1. Use Specific Fields: Only request the fields you need with columns parameter.

2. Limit Populates: Only populate relationships that are necessary for your use case.

3. Apply Filters: Use appropriate filters to narrow down results and improve performance.

4. Consider Pagination: For large datasets, use limit and sort parameters effectively.

5. Use Lean Mode: Enable lean=true when you don't need Mongoose document features.

This endpoint provides comprehensive access to biometric validation records with flexible querying capabilities for various use cases.