Skip to main content
POST
/
data-lists
/
{id}
/
items
/
find
Buscar ítems por valor en una 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
}
'

​
Resumen

Busca ítems dentro de una lista concreta (UUID). La comparación usa primary_value y cada search_keys, con la misma normalización sin acentos que el resto de búsquedas. Podés enviar value como string (una aguja) o como array de strings (hasta 50 entradas; se eliminan duplicados tras normalizar). La semántica es OR: cualquier ítem que coincida con cualquiera de las agujas aparece como máximo una vez en items.
  • exact (por defecto): igualdad normalizada con el primary o con alguna clave.
  • contains: subcadena en el primary o en alguna clave (LIKE con %/_ escapados en la aguja).
Por defecto solo ítems is_active: true; con includeInactive: true se incluyen inactivos.

​
Endpoint

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

​
Autenticación

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

​
Cuerpo de la solicitud

​
value
string | string[]
required
Una aguja (string, 1–4000 caracteres) o hasta 50 agujas (string[], cada una 1–4000). Se ignoran strings vacíos tras trim; los duplicados colapsan tras normalizar acentos. Tiene que quedar al menos una aguja no vacía.
​
matchMode
string
default:"exact"
exact o contains.
​
limit
number
default:"100"
Máximo de filas devueltas (1–500). Si hay más coincidencias, truncated es true y total es el conteo total.
​
includeInactive
boolean
default:"false"
Con true incluye ítems inactivos.

​
Ejemplos

Un valor 
{
  "value": "20123456789",
  "matchMode": "exact",
  "limit": 50
}
Varios valores (OR) 
{
  "value": ["20123456789", "30701234567", "27999999999"],
  "matchMode": "exact",
  "limit": 100
}

​
Respuesta

Incluye data.valuesSearched: cantidad de agujas distintas usadas tras deduplicar, además de listId, matchMode, items, total, returned, truncated (mismo formato snake_case que Listar ítems).

​
Códigos HTTP

  • 404: lista inexistente o sin acceso para la organización.
  • 403: lista global solo marketplace no expuesta por esta API.

​
Ver también