Dynamo Developer DocsDynamo Developer Docs
External APIVIPVIP Users

List VIP users

The VIP users (players marked VIP for the workspace) on one channel, highest-LTV first, with their profile and personal info (including birthday). Paginated via `limit` + `offset` (`total`, `nextOffset`). VIP workspaces only. `scope=all` widens the read from the workspace's VIP set to **every conversation on the channel** (the whole audience) — same field set, filters, sort, and pagination. A channel bigger than the 25k scan guardrail comes back with `scanCapped: true` (then `total` is a floor). `compact=true` is a bulk projection: each row is trimmed to `conversationId` + `cuid` + `birthday`, and `limit` caps — and defaults — at 5000, so a whole audience fits in one response (CUID joins, birthday sweeps). Same envelope, scan, filters, sort, and pagination; the response stays plain JSON.

get/vip-users

Beta

The External API is in beta. Endpoints, parameters, and response shapes may change — including breaking changes — in future releases. Pin to documented behavior before relying on it in production.

Authorization

x-api-key x-date x-signature x-api-version
x-api-key<token>

Your API key (the ApiKeys document id).

In: header

x-date<token>

Current timestamp as an IMF-fixdate string (GMT, US locale) "EEE, dd MMM yyyy HH:mm:ss z", e.g. "Sun, 06 Dec 2020 12:59:11 GMT". 30-second TTL.

In: header

x-signature<token>

HMAC-SHA256 of the x-date string keyed by your secret, lowercase hex.

In: header

x-api-version<token>

API version you're coding against — currently 1. Required; a missing or unsupported value returns 400 with Missing or unsupported x-api-version header. Supported versions: 1.

In: header

Query Parameters

workspaceId*string

The VIP workspace id (from GET /workspaces).

mediumId*string

The channel id (from GET /channels).

scope?string

Which users to read: vip (default) — only users marked VIP for the workspace; all — every conversation on the channel (the whole audience).

hasBirthday?string

When true, only users with a known birthday.

birthdayMonth?integer

Only users whose birthday is in this calendar month.

compact?string

When true, each row is trimmed to conversationId + cuid + birthday (a bulk projection for CUID joins and birthday sweeps), and limit caps — and defaults — at 5000. The response stays plain JSON, same envelope.

limit?integer

Max users per page. Full rows clamp to 200 (default 50); with compact=true both the cap and the default are 5000. Values above the mode's cap are clamped, not rejected.

offset?integer

Number of users to skip (for pagination).

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

Try it

read-only

Kept in this tab only and signed in your browser — your secret never leaves your device.

Query

Enter your key and secret to send.

curl -X GET "https://example.com/vip-users?workspaceId=AbC123XyZ&mediumId=FB_PAGE_123456789012345"
{  "items": [    {      "conversationId": "string",      "userName": "string",      "firstName": "string",      "lastName": "string",      "cuid": "string",      "profilePic": "string",      "birthday": "string",      "lastPurchaseTimestamp": 0,      "lastUserMessageTimestamp": 0,      "lastAppOpenTimestamp": 0    }  ],  "returned": 0,  "total": 0,  "mayHaveMore": true,  "nextOffset": 0,  "scanCapped": true}
{  "message": "string"}
{  "message": "string"}
{  "message": "string"}
{  "message": "string"}
{  "error": [    {      "message": "string",      "path": [        "string"      ],      "type": "string",      "context": {}    }  ]}

Get (a single) broadcast insights

One broadcast's metadata **plus** per-send delivery insights and a lifetime rollup. Each `executions` entry is one logical send; up to 50 are returned (`executionsReturned`), with `executionsTotal` giving the true count. Also carries the message creative: `messages` is the **current** creative (one entry per variant); each send reports `notificationIndex` — the variant it used — plus `sentMessage`, the creative **exactly as that send went out** (compare it with `messages` to spot later edits) with per-button `clicks` folded in wherever the button sits (top-level, carousel card, or follow-up). Optional `startDate` / `endDate` (both together) window the **returned executions** by send date — without a window, a recurring broadcast returns its newest sends up to the cap, which can miss a historical range entirely. `lifetime` and `executionsTotal` always cover **all** sends; a windowed response adds `window` and `executionsInWindow` so you can detect a truncated window.

Export VIP users to CSV

Export all matched VIP users to a CSV and return `{ totalCount, csvUrl }`. Same filters as the list route, but returns every matched row rather than a page. `scope=all` widens the export to **every conversation on the channel** (the whole audience), not only marked VIPs. Each scope exports to its own deterministic filename (`vip_users_…` / `all_users_…`), so re-exports overwrite within a scope but a VIP export never clobbers an all-audience one.