Skip to main content
POST
/
data-lists
/
{id}
/
items
/
find
Find items by value in a list
curl --request POST \
  --url http://api.gu1.ai/data-lists/{id}/items/find \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "value": [
    "<string>"
  ],
  "matchMode": "<string>",
  "limit": 123,
  "includeInactive": true
}
'

​
Overview

Looks up items inside a specific list (by list UUID). Matching runs against the item’s primary_value and every entry in search_keys, using the same accent-insensitive normalization as list search elsewhere. You can pass value as a string (one needle) or as an array of strings (up to 50 entries; duplicates are removed after normalization). Semantics are OR: any item that matches any needle is returned at most once in items.
  • exact (default): normalized needle equals normalized primary or equals any search key.
  • contains: normalized needle is a substring of primary or of any search key (SQL LIKE with wildcards escaped in the needle).
By default only is_active: true items are returned; set includeInactive: true to include inactive rows.

​
Endpoint

POST https://api.gu1.ai/data-lists/{id}/items/find

​
Authentication

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

​
Request Body

​
value
string | string[]
required
One needle (string, 1–4000 characters) or up to 50 needles (string[], each 1–4000 characters). Empty strings are ignored; duplicates collapse after trim + accent normalization. At least one non-empty needle is required.
​
matchMode
string
default:"exact"
exact or contains.
​
limit
number
default:"100"
Max rows to return (1–500). If more rows match, truncated is true and total is the full count.
​
includeInactive
boolean
default:"false"
When true, inactive items are included in the search.

​
Examples

Single value 
{
  "value": "20123456789",
  "matchMode": "exact",
  "limit": 50
}
Several values (OR) 
{
  "value": ["20123456789", "30701234567", "27999999999"],
  "matchMode": "exact",
  "limit": 100
}

​
Response

{
  "success": true,
  "data": {
    "listId": "…",
    "matchMode": "exact",
    "valuesSearched": 3,
    "items": [],
    "total": 0,
    "returned": 0,
    "truncated": false
  }
}
valuesSearched is the number of distinct normalized needles used (after deduplication). Each item uses the same snake_case shape as GET /data-lists/{id}/items (id, primary_value, search_keys, item_data, etc.).

​
Status codes

  • 404: list not found or not accessible for this organization.
  • 403: marketplace-only global list not exposed via this API.

​
See Also