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
}
'

import requests

url = "http://api.gu1.ai/data-lists/{id}/items/find"

payload = {
    "value": ["<string>"],
    "matchMode": "<string>",
    "limit": 123,
    "includeInactive": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({value: ['<string>'], matchMode: '<string>', limit: 123, includeInactive: true})
};

fetch('http://api.gu1.ai/data-lists/{id}/items/find', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/data-lists/{id}/items/find",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'value' => [
        '<string>'
    ],
    'matchMode' => '<string>',
    'limit' => 123,
    'includeInactive' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/data-lists/{id}/items/find"

	payload := strings.NewReader("{\n  \"value\": [\n    \"<string>\"\n  ],\n  \"matchMode\": \"<string>\",\n  \"limit\": 123,\n  \"includeInactive\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/data-lists/{id}/items/find")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"value\": [\n    \"<string>\"\n  ],\n  \"matchMode\": \"<string>\",\n  \"limit\": 123,\n  \"includeInactive\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/data-lists/{id}/items/find")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"value\": [\n    \"<string>\"\n  ],\n  \"matchMode\": \"<string>\",\n  \"limit\": 123,\n  \"includeInactive\": true\n}"

response = http.request(request)
puts response.read_body

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
}
'

import requests

url = "http://api.gu1.ai/data-lists/{id}/items/find"

payload = {
    "value": ["<string>"],
    "matchMode": "<string>",
    "limit": 123,
    "includeInactive": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({value: ['<string>'], matchMode: '<string>', limit: 123, includeInactive: true})
};

fetch('http://api.gu1.ai/data-lists/{id}/items/find', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/data-lists/{id}/items/find",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'value' => [
        '<string>'
    ],
    'matchMode' => '<string>',
    'limit' => 123,
    'includeInactive' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/data-lists/{id}/items/find"

	payload := strings.NewReader("{\n  \"value\": [\n    \"<string>\"\n  ],\n  \"matchMode\": \"<string>\",\n  \"limit\": 123,\n  \"includeInactive\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/data-lists/{id}/items/find")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"value\": [\n    \"<string>\"\n  ],\n  \"matchMode\": \"<string>\",\n  \"limit\": 123,\n  \"includeInactive\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/data-lists/{id}/items/find")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"value\": [\n    \"<string>\"\n  ],\n  \"matchMode\": \"<string>\",\n  \"limit\": 123,\n  \"includeInactive\": true\n}"

response = http.request(request)
puts response.read_body

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

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.

string

default:"exact"

exact or contains.

number

default:"100"

Max rows to return (1–500). If more rows match, truncated is true and total is the full count.

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.

Getting Started

SDK

Use Cases

Webhooks

Workflows

Monitoring (entities)

Person

Messaging

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Payment Methods

Rules

Custom lists

Risk Matrix

Alerts

Investigations

Data Ingestion

Bulk imports

Documents

Enrichment

AML Crypto

Services

Integrations

Interactive Tutorials

Find items by value in a list

Overview

Endpoint

Authentication

Request Body

Examples

Response

Status codes

See Also

​Overview

​Endpoint

​Authentication

​Request Body

​Examples

​Response

​Status codes

​See Also

Overview

Endpoint

Authentication

Request Body

Examples

Response

Status codes

See Also