Meltwater

Meltwater

Meltwater is media intelligence and social listening: monitor earned mentions, manage saved searches, run analytics breakdowns, tag documents, schedule exports, register streaming hooks, and read owned-channel social metrics over the v3 REST API.

Operational order

1. Account scope — When the credential spans multiple companies, list companies and workspaces first; pass company_id on downstream calls that require it.
2. Saved searches — List or fetch saved searches to obtain search_id and query text. Create or update with search_json (omit search_id for create, include it for update). Delete removes the saved search.
3. Mention volume — Count mentions for a search with optional start_date / end_date (ISO 8601).
4. Analytics — Pre-built breakdowns (sources, tags, locations, entities, topics, keyphrases, top mentions, shared links, and related views) need search_id, window start / end, and tz. For ad-hoc analysis, read the custom analytics catalog first, then submit a custom analytics job with analytics_json.
5. Tags — List tag definitions; create and delete tags. Bulk add or remove tags on documents is async (up to 100 document ids per call) via document_ids and tags_json.
6. Exports — Start one-time or recurring mention exports, poll until status is finished, then download (large files may return a spillover download link). Delete export jobs when done.
7. Hooks — List REST hooks, create with a target URL (response header X-Hook-Secret is the signing secret for inbound payloads), delete to stop delivery.
8. Owned social — List connected owned accounts, read supported metric definitions, then query breakdown, heatmap, numeric metrics, or top posts for selected accounts.

Write payloads

• search_json — {"search": {"name": "…", "query": {…}}} with query type boolean, keyword, or combined per Meltwater docs.
• analytics_json — Full POST body for custom analytics (time window plus analysis or analytic shape per catalog).
• tags_json — JSON array such as [{"id": 123}, {"name": "priority"}].

Filter sets

Saved searches can reference filter sets; optional QUICKPICK sets are available when listing filter sets for a search.

Gotchas

• Search and query objects are strict — invalid boolean or keyword fields often return HTTP 422.
• Export jobs and bulk document tag changes are asynchronous — poll export status; tag add/remove returns 202 Accepted.
• Hook signing secret is returned only on create — retain it to verify inbound webhook payloads.
• Export data_url links expire — request download on poll when the job is ready so large exports surface as spillover links.
• Check API usage for the billing period before sweeping many searches or wide date windows.