Legacy API Field Mapping

This page explains how the Listen API V2 fields are designed, and maps every field of the legacy statements/search endpoint to V2. For the migration steps, see Migrating from Legacy API to Listen API V2.

How the V2 fields are designed

V2 does not copy the legacy field list one to one. It follows four design principles; once you know them, most of the mappings below are predictable.

Structured objects instead of flat fields

The legacy Statement put everything on one level, so author, source, content and metrics fields were mixed together. V2 groups them by what they describe:

• author: who wrote the mention (ID, name, avatar, gender, follower and fan counts)
• source: where it was published (platform type, social channel such as a Facebook page, and the mention URL)
• content: what it says (title, text, language, sentiment, review rating)
• engagementMetrics: how people reacted (influence score, engagement rate, counters)
• location: where it comes from (country, region, city, coordinates)
• discussion and context: the thread it belongs to and its parent

Platform-specific values have their own sub-objects, such as engagementMetrics.sourceMetrics.facebook for reactions. A sub-object that does not apply to a mention is null, instead of adding fields that are empty for most mentions.

The same Facebook post in both APIs (fields shortened):

Legacy API (V1)

{
  "author": "Sarah Johnson",
  "authorId": "1234567890",
  "sex": "f",
  "createdAt": 1761125400000,
  "sentiment": "POSITIVE",
  "group": "facebook",
  "sourceName": "Tech Reviews Hub",
  "metadata": { "likes": 28, "followers": 245 }
}

Listen API V2

{
  "author": {
    "id": "1234567890",
    "name": "Sarah Johnson",
    "gender": "Female",
    "influenceMetrics": { "followerCount": 245 }
  },
  "publishedAt": "2025-10-22T09:30:00Z",
  "content": { "sentiment": "Positive" },
  "source": { "type": "Facebook", "socialChannel": { "name": "Tech Reviews Hub" } },
  "engagementMetrics": { "sourceMetrics": { "common": { "likeCount": 28 } } }
}

Human-readable dates

Every date in V2, in requests and in responses, is an ISO 8601 string in UTC, such as 2026-10-20T09:12:15Z. You can read it in logs and pass it to any date library without knowing a time zone or a timestamp unit.

Enumeration values that mirror the Listen app

Enumeration values use the same names as the Listen app UI: sentiment is Positive, Negative, Neutral or Unspecified; sources are Facebook, X, Reddit and so on. What you see in the app is what you send in filters and get back in responses.

Request fields: legacy → V2

V2 groups filters under filters and uses ISO 8601 UTC dates and capitalized enum values.

Response fields: legacy Statement → V2 Mention

V2 returns a nested Mention object. Timestamps are ISO 8601 UTC strings instead of milliseconds, and empty values are null or absent.

Fields removed in V2

These legacy fields have no direct V2 field. Where the information is still available, the last column says where to find it.

Matching data you already stored

V2 mention IDs differ from legacy statement IDs. To avoid duplicates when you switch, each V2 mention carries deprecatedV1Fields.id, the legacy id of the same mention. Use it once to match V2 records to what you already stored, then key everything on the V2 id.