ackDB

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:

  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: []
get/api/v1/ackdb/entities/lookup

Request

  • Base URL
    http://localhost:3009
  • Auth
    HTTP bearer

Query parameters

externalIdTypestring required

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.

externalIdValuestring required

The actual external ID value to look up.

sourcestring

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.