Skip to content

external_id in supported_identifier_types is ambiguous with AudienceMember.external_id #1217

@bokelley

Description

@bokelley

Problem

GetAdCPCapabilitiesResponse.audience_targeting.supported_identifier_types now includes 'external_id' as a value:

```typescript
supported_identifier_types: ('hashed_email' | 'hashed_phone' | 'external_id')[];
```

AudienceMember also has a top-level external_id: string field, described as "Buyer-assigned stable identifier for this audience member (e.g. CRM record ID, loyalty ID). Used for deduplication, removal, and cross-referencing with buyer systems."

These are two different concepts sharing a name:

  1. AudienceMember.external_id — a buyer-internal deduplication key, present on every audience member, not used for ad platform matching.
  2. supported_identifier_types: ['external_id'] — signals that the seller can match users using the buyer's CRM/loyalty ID directly (a closed-ecosystem capability like Amazon, Walmart, Instacart).

An agent implementation could reasonably misread supported_identifier_types: ['external_id'] as "use the AudienceMember.external_id deduplication field for matching" when the seller actually means something specific to their identity graph.

Proposed fix

Rename the supported_identifier_types value to something unambiguous:

```typescript
supported_identifier_types: ('hashed_email' | 'hashed_phone' | 'retailer_customer_id' | 'platform_customer_id')[];
```

Or keep external_id but add a JSDoc note that explicitly distinguishes it from AudienceMember.external_id:

'external_id': The seller accepts the buyer's CRM/loyalty ID as a matchable identifier for their identity graph. This is distinct from AudienceMember.external_id, which is a buyer-side deduplication key and is always required. Only declare this when the seller operates a closed ecosystem with a shared ID namespace (e.g., a retailer matching against their loyalty program).

Context

This ambiguity was introduced when external_id was promoted from a UIDType union member to a top-level required field on AudienceMember in 2.5.x.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions