Skip to main content
POST
/
identities
/
filter
curl -X POST https://YOUR_BLNK_INSTANCE_URL/identities/filter \
  -H "Content-Type: application/json" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -d '{
    "filters": [
      {
        "field": "category",
        "operator": "eq",
        "value": "individual"
      }
    ],
    "limit": 20,
    "offset": 0
  }'

[
  {
    "identity_id": "idt_1234567890",
    "identity_type": "individual",
    "first_name": "John",
    "last_name": "Doe",
    "email_address": "[email protected]",
    "phone_number": "+1234567890",
    "nationality": "US",
    "category": "individual",
    "street": "123 Main St",
    "country": "United States",
    "state": "California",
    "post_code": "90210",
    "city": "Beverly Hills",
    "dob": "1990-01-15T00:00:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "meta_data": {}
  }
]
Filters identities using a JSON request body with support for complex filter conditions, sorting, and optional total count. This endpoint provides more flexibility than query parameter filtering.

​
Request Body

​
filters
array
required
Array of filter conditions to apply
​
limit
integer
default:"20"
Maximum number of identities to return
​
offset
integer
default:"0"
Number of identities to skip for pagination
​
sort_by
string
Field name to sort by (e.g., “created_at”, “first_name”)
​
sort_order
string
Sort direction: asc or desc
​
include_count
boolean
default:"false"
Whether to include total count of matching records in the response

​
Response

​
Without Count

Returns an array of identity objects matching the filter criteria.

​
With Count

​
data
array
Array of identity objects matching the filter criteria
​
total_count
integer
Total number of identities matching the filter (regardless of limit/offset)
curl -X POST https://YOUR_BLNK_INSTANCE_URL/identities/filter \
  -H "Content-Type: application/json" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -d '{
    "filters": [
      {
        "field": "category",
        "operator": "eq",
        "value": "individual"
      }
    ],
    "limit": 20,
    "offset": 0
  }'

[
  {
    "identity_id": "idt_1234567890",
    "identity_type": "individual",
    "first_name": "John",
    "last_name": "Doe",
    "email_address": "[email protected]",
    "phone_number": "+1234567890",
    "nationality": "US",
    "category": "individual",
    "street": "123 Main St",
    "country": "United States",
    "state": "California",
    "post_code": "90210",
    "city": "Beverly Hills",
    "dob": "1990-01-15T00:00:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "meta_data": {}
  }
]

​
Filter Operators

​
Comparison Operators

OperatorDescriptionExample
eqEquals{"field": "category", "operator": "eq", "value": "individual"}
neNot equals{"field": "category", "operator": "ne", "value": "corporate"}
gtGreater than{"field": "created_at", "operator": "gt", "value": "2024-01-01"}
gteGreater than or equal{"field": "created_at", "operator": "gte", "value": "2024-01-01"}
ltLess than{"field": "created_at", "operator": "lt", "value": "2024-12-31"}
lteLess than or equal{"field": "created_at", "operator": "lte", "value": "2024-12-31"}
inIn list{"field": "category", "operator": "in", "values": ["individual", "corporate"]}
containsContains substring{"field": "first_name", "operator": "contains", "value": "John"}

​
Filterable Fields

  • identity_id
  • identity_type
  • first_name
  • last_name
  • other_names
  • email_address
  • phone_number
  • nationality
  • organization_name
  • category
  • street
  • country
  • state
  • post_code
  • city
  • created_at

​
Sorting

Sort results by any field in ascending or descending order: 
{
  "filters": [...],
  "sort_by": "created_at",
  "sort_order": "desc"
}

​
Pagination with Total Count

When include_count is true, the response includes the total count of matching records, which is useful for building pagination UIs: 
{
  "filters": [...],
  "limit": 20,
  "offset": 0,
  "include_count": true
}
This allows you to calculate:
  • Total pages: Math.ceil(total_count / limit)
  • Current page: Math.floor(offset / limit) + 1
  • Has more results: (offset + limit) < total_count

​
Performance Considerations

  • Setting include_count: true requires an additional database query
  • Use specific filters to reduce result set size
  • Consider caching total counts for frequently-used filter combinations
  • For very large datasets, avoid using offset values over 10,000
See Also: List Identities, Get Identity

Build docs developers (and LLMs) love

Get started for freeTalk to us