Entity Lookup

Entity Lookup

Purpose

Look up individual user profiles by identity field. Returns the full profile including all fields, segment memberships, and metadata.

Environment

Requires authenticated API access. See ../references/auth.md for credential resolution.

API Endpoints

V2 Identity Lookup

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/identity/${TABLE}/${FIELD}/${VALUE}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Example: GET /v2/identity/user/email/user@example.com

Data API Entity Lookup

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/${TABLE}/${FIELD}/${VALUE}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Entity Lookup by Value Only

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/${TABLE}/${VALUE}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Searches across all identity fields.

Entity Segment Memberships

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/${TABLE}/segments/${FIELD}/${VALUE}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Identity Lookup (POST)

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/identity/lookup" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"field": "email", "value": "user@example.com", "table": "user"}'

Delete Entity

# Hard delete
curl -s -X DELETE "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/${TABLE}/${FIELD}/${VALUE}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Soft delete
curl -s -X DELETE "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/softdelete/${TABLE}/${FIELD}/${VALUE}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Common Identity Fields

• email -- Email address
• _uid -- Lytics user ID
• user_id -- External user ID
• Check GET /v2/schema/{table}/idconfig for account-specific identity fields

Behavior

For Lookups (read)

Execute immediately. Display the profile in a structured format:

1. Identity: All identity fields and values
2. Key attributes: High-value profile fields (name, location, engagement scores)
3. Segment memberships: Which segments this user belongs to
4. Recent activity: Latest event timestamps

For Deletes (write)

Use the confirmation-gate pattern. Warn that:

• Hard deletes are irreversible
• Soft deletes can be undone but affect data processing

Error Handling

• Profile not found (404): Suggest trying different identity fields or checking spelling
• URL encoding: URL-encode the value if it contains special characters (e.g., @ in emails)
• Multiple matches: If multiple profiles match, present all and ask user to select

Dependencies

• Uses: ../references/auth.md, ../references/api-client.md, ../references/confirmation-gate.md (for deletes only)