Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Data lists (including custom lists with type: "custom") store values your organization uses in rules (in_custom_list, not_in_custom_list, contains_any_from_custom_list, and related operators). The public REST surface is under: 
https://api.gu1.ai/data-lists
All calls require a Bearer API key (same as Authentication). Data is scoped to the organization tied to the key.

​
Concepts

  • name and description (list metadata): human-readable fields for your team only. They are used in the gu1 dashboard (list picker, tables, detail headers) and in audit or admin views so operators can recognize lists without opening each UUID. They are not matched by rule engines or check endpoints; rule logic still uses list id and item primaryValue / searchKeys.
  • primaryValue: main value stored for an item (exact match / normalization depends on list type and engine).
  • searchKeys: optional extra strings used for lookup; if omitted on ingest, the API typically defaults to [primaryValue].
  • itemData / metadata: optional JSON objects for extra columns or context.
  • List UUID in rules: for custom-list operators, the condition value is the list id (UUID) returned when you create or list the list.
See Rule conditions for condition syntax.

​
Typical client flow

  1. Create a list with POST /data-lists (use type: "custom" for a generic list, or another supported type such as company_blocklist if it fits your use case).
  2. Add items with POST /data-lists/{listId}/items (batch up to the API limit) or POST /data-lists/{listId}/items/bulk for larger payloads.
  3. Verify membership with POST /data-lists/{type}/check (checks across lists of that type) or POST /data-lists/bulk-check for several lookups at once.
  4. Browse items with GET /data-lists/{listId}/items (search query filters by primary value / keys as implemented by the service), or look up by value with POST /data-lists/{listId}/items/find when you need exact or substring match on primary + search_keys for that list only.
  5. Maintain lists with PATCH /data-lists/{id}, PATCH /data-lists/{id}/status, DELETE /data-lists/{id}, and per-item PATCH / DELETE under /data-lists/{id}/items/{itemId}.

​
Global vs tenant lists

Your tenant may see global lists (e.g. shared sanctions data). Only system administrators can mutate global lists or their items; normal API keys manage tenant-owned lists. Marketplace-only global lists are not exposed through these endpoints (the API returns 403 with a specific error code).

​
API Reference

Use the Custom lists → API Reference section in the sidebar for endpoint-by-endpoint parameters and examples.