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 them. For the migration steps, see the step-by-step migration guide.

How the new fields are designed

The new API 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. The new Mention 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 the new API, 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 → new

The new API groups filters under filters and uses ISO 8601 UTC dates and capitalized enum values.

Response fields: legacy Statement → new Mention

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

Removed fields

These legacy fields have no direct equivalent in the new API. Where the information is still available, the last column says where to find it.

Matching data you already stored

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