Look up entity by external ID
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:
- First event from a source (e.g., Slack channel C04ABC123) → workflow resolves the company domain, ingests with domain identity link
- 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: []
Request
- Base URLhttp://localhost:3009
- AuthHTTP bearer
Query parameters
Identity link type to look up. Universal types (e.g., domain) work without a source param. Source-specific types (e.g., slack_channel_id, stripe_customer_id) require the source param.
The actual external ID value to look up.
Source type (e.g., slack, stripe). Required for source-specific ID types. Omit for universal types like domain - the lookup will search across all sources.
Response
Lookup result - always 200, check match field for result
Example response
{
"data": {
"match": {
"entityId": "01HXYZ123456789ABCDEFGH",
"entityName": "acme.com",
"domain": "acme.com"
}
}
}Changes
No recorded changes to this operation across all 1 revision of this API.