Interface SyncAudiencesSuccess

Type Declaration

• audience_id: string

  Audience ID from the request (buyer's identifier)

• Optionalname?: string

  Name of the audience

• Optionalseller_id?: string

  Seller-assigned identifier for this audience in their ad platform

• action: "created" | "updated" | "unchanged" | "failed" | "deleted"

  Action taken for this audience. 'status' is present when action is created, updated, or unchanged. 'status' is absent when action is deleted or failed.

• Optionalstatus?: AudienceStatus

• Optionaluploaded_count?: number

  Number of members submitted in this sync operation (delta, not cumulative). In discovery-only calls (no audiences array), this is 0.

  Minimum

  0

  Format

  int

• Optionaltotal_uploaded_count?: number

  Cumulative number of members uploaded across all syncs for this audience. Compare with matched_count to calculate match rate (matched_count / total_uploaded_count). Populated when the seller tracks cumulative upload counts.

  Minimum

  0

  Format

  int

• Optionalmatched_count?: number

  Total members matched to platform users across all syncs (cumulative, not just this call). Populated when status is 'ready'.

  Minimum

  0

  Format

  int

• Optionaleffective_match_rate?: number

  Deduplicated match rate across all identifier types (matched_count / total_uploaded_count after deduplication). A single number for reach estimation. Populated when status is 'ready'.

  Minimum

  0

  Maximum

  1

• Optionalmatch_breakdown?: { id_type: MatchIDType; submitted: number; matched: number; match_rate: number }[]

  Per-identifier-type match results. Shows which ID types are resolving and at what rate. Helps buyers decide which identifiers to prioritize. Populated when the seller can report per-type matching. Omitted when the seller only supports aggregate match counts.

• Optionallast_synced_at?: string

  ISO 8601 timestamp of when the most recent sync operation was accepted by the platform. Useful for agents reasoning about audience freshness. Omitted if the seller does not track this. For externally sourced audiences, REQUIRED once counts populate (status ready or too_small): every count field is as-of this timestamp — it is the buyer's only anchor for what a count means, since two reads can differ because membership changed, match rate changed, or the seller re-read the source.

  Format

  date-time

• Optionalsource?: {
      kind: "dataset" | "platform_segment";
      vendor: BrandReference;
      locator?: string;
      segment_ref?: string;
      columns_read?: string[];
      access_status?: "active" | "unavailable";
  }

  Echo of the external source feeding this audience (never credentials), present on externally sourced audiences in every response including discovery-only calls — the single pane invariant: externally sourced audiences appear in discovery identically to pushed ones, with the same status enum, match reporting, and targetability. Loss of source access (revocation, access_expires_at passing, or read failure of any cause) MUST NOT change the audience status: last matched state persists and remains targetable, last_synced_at freezes, and failed re-reads MUST NOT emit suspended — that value stays reserved for consent/policy causes, which remain orthogonal. Source health is reported here via access_status instead.

  • kind: "dataset" | "platform_segment"

    Source kind, echoed from the request.

  • vendor: BrandReference

  • Optionallocator?: string

    Dataset locator, echoed from the request (kind: dataset).

  • Optionalsegment_ref?: string

    Segment reference, echoed from the request (kind: platform_segment).

  • Optionalcolumns_read?: string[]

    Canonical identifier columns the seller actually read from the shared object on the most recent ingest (kind: dataset). Lets a buyer distinguish bad identifier data from a column the seller never read — match_breakdown reveals what resolved, not what was offered.

  • Optionalaccess_status?: "active" | "unavailable"

    Source pipe health. Set to unavailable after a failed read (the seller cannot reliably distinguish revocation from expiry from a transient vendor outage — all three observables are a failed read); cleared to active on the next successful one. With last_synced_at this tells the buyer both that the pipe is down and how stale the membership is. Never a status input: membership stays frozen at the last successful read and remains targetable.

• Optionalminimum_size?: number

  Minimum matched audience size required for targeting on this platform. Populated when status is 'too_small'. Helps agents know how many more members are needed.

  Minimum

  1

  Format

  int

• Optionalerrors?: Error[]

  Errors for this audience (only present when action='failed')