VYG Docs

REST API reference

API endpoints, inputs and responses for your VYG integration.

The REST API is served at:

https://api.vyg.app/v1

Each endpoint lists its inputs, responses and errors. Download the OpenAPI 3.1 specification at https://api.vyg.app/v1/openapi.json.

Conventions

  • Authentication: Authorization: Bearer <API key or sign-in token>. See Authentication.
  • Scopes: each operation names the scopes that allow it; any one is enough. See Scopes.
  • Sign-in only: operations marked "Requires sign-in (OAuth)" need an OAuth connection.
  • MCP tool: operations that are also an MCP tool name it, linked to the tool catalog.
  • Format: JSON bodies. Timestamps are ISO 8601 strings in UTC.
  • Account: see Account context to select your account and store.
  • Errors: {"error": {"code", "message"}}. See Errors.
  • Field names: every query parameter, path parameter, body field and response key is snake_case.
  • Lists: every list returns { data, next_cursor }; pass next_cursor back as cursor. See Pagination.
  • Single records: returned as the object itself, not wrapped in data.
  • Rate limits: a few operations are rate limited. See Rate limits.

Areas

AreaWhat it covers
BrandYour business details and settings.
ConversationsConversations and messages, conversation search, conversation insights, and contacts.
CustomersCustomer list, lookup and profile, activity timeline, a customer's orders and subscriptions, customer fields.
SegmentsSaved segments: rules, estimates, members and history.
CommerceStore orders, subscriptions and products.
InsightsLifetime value, RFM tiers, top products and customers at risk.
CampaignsCampaigns, message variants, campaign building options and performance stats.
DiscountsYour saved discounts.
IntegrationsConnected apps, event types, and custom integration providers and event definitions.
API keysCreate, list, rotate and revoke API keys.
AdvocacyAdvocate programs, memberships, reward codes, attribution, campaigns, seeding and payouts.
List buildingAdd a subscriber to a live SMS sign-up campaign from your own site or app.
WebhooksThe brand's webhook endpoint for message and opt-out events.

Campaign routes

Every campaign route is under /v1/campaigns: reads (GET /v1/campaigns, GET /v1/campaigns/{campaign_id}, GET /v1/campaigns/compare) and changes. Performance stats are GET /v1/stats. Both are on the Campaigns page. A campaign id from GET /v1/campaigns is the campaign_id every other campaign route and tool takes.

Customer segments and RFM

GET /v1/segments and the segment routes are saved segments: named rules you create. The RFM tiers from GET /v1/insights/rfm (the get_rfm_tiers tool) are based on order history. See Insights.

Concepts

  • Advocacy: advocate programs, memberships, reward codes, attribution and payouts.
  • List building: add a subscriber to a live SMS sign-up campaign.
  • Connect an external popup tool: JustUno and other form posts through a List ID and webhook.
  • Commerce data: store data, currencies and connection requirements.
  • Insights: how lifetime value, RFM tiers, top products and churn risk are computed.
  • Segment rules: the rule format for creating and changing segments.

Not in this reference

  • Event collection on https://cdp.vyg.app (/cdp/ingest, /cdp/events, /cdp/vyg.js). See Data collection.
  • Custom integration webhooks. See Custom Integration.
  • MCP-only tools such as get_conversation_details. See the tool catalog.

On this page