---
title: "Look up entity by external ID"
method: GET
path: "/api/v1/ackdb/entities/lookup"
tags: ["ackDB"]
---

# Look up entity by external ID

`GET /api/v1/ackdb/entities/lookup`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/ackdb/entities/lookup`
- Auth: HTTP bearer

Check if a source-specific ID (Slack channel, Stripe customer) or universal ID (domain, email) is already linked to an entity in ackDB. Always returns 200 - 'not found' is a valid lookup result, not an error.

**The resolve-once pattern:**
1. First event from a source (e.g., Slack channel `C04ABC123`) → workflow resolves the company domain, ingests with `domain` identity link
2. Subsequent events from the same channel → workflow calls `GET /entities/lookup?externalIdType=slack_channel_id&externalIdValue=C04ABC123&source=slack` → gets the `entityId` back → ingests with `entityId` directly, skipping domain resolution

**Three possible outcomes:**
- **Found:** Identity link exists → returns entity ID, name, domain, and link timestamp
- **Unresolved:** ID exists in unresolved content pool (ingested without domain) → returns unresolved content IDs
- **Never seen:** ID not in ackDB at all → returns `match: null, unresolvedMatches: []`

## Query parameters

- `externalIdType` string, required
- `externalIdValue` string, required
- `source` string

## Response `200`

Lookup result - always 200, check `match` field for result

- object
  - `data` object, required
    - `match` object, required: The matched entity, or null if no entity found.
      - `entityId` string, required
      - `entityName` string, required
      - `domain` string, required
      - `linkedAt` string, date-time, required
    - `unresolvedMatches` object[], required: Unresolved content records matching this ID (when no entity match).
      - `unresolvedContentId` string, required
      - `source` string, required
      - `timestamp` string, date-time, required

## Other responses

- `422`: Missing required parameters

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)