Skip to main content
POST
/
data-lists
/
{id}
/
items
/
find
Buscar itens por valor em uma lista
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
}
'

​
Visão geral

Busca itens dentro de uma lista específica (UUID). Usa primary_value e search_keys, com normalização sem acentos alinhada às outras buscas. value pode ser string (uma agulha) ou array de strings (até 50; duplicatas removidas após normalizar). Semântica OR: o item aparece no máximo uma vez se coincidir com qualquer agulha.
  • exact (padrão): igualdade normalizada com o primary ou com alguma chave.
  • contains: subcadeia no primary ou em alguma chave.
Por padrão só itens is_active: true; use includeInactive: true para incluir inativos.

​
Endpoint

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

​
Autenticação

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

​
Corpo da solicitação

​
value
string | string[]
required
Uma agulha (string, 1–4000) ou até 50 agulhas (string[], cada 1–4000). Strings vazias após trim são ignoradas; duplicatas colapsam após normalizar acentos.
​
matchMode
string
default:"exact"
exact ou contains.
​
limit
number
default:"100"
Máximo de linhas (1–500). truncated indica se há mais resultados que limit.
​
includeInactive
boolean
default:"false"
Com true, inclui itens inativos.

​
Exemplos

Um valor 
{
  "value": "20123456789",
  "matchMode": "exact"
}
Vários valores (OR) 
{
  "value": ["20123456789", "30701234567"],
  "matchMode": "exact",
  "limit": 100
}

​
Resposta

Inclui data.valuesSearched (número de agulhas distintas após deduplicar), além de items, total, returned, truncated, matchMode, listId — mesmo formato snake_case de Listar itens.

​
Ver também