VYG Docs
Concepts

List building

Add a subscriber to a live SMS sign-up campaign from your own site or app.

Use this endpoint when a form, quiz or kiosk on your site should add someone to a list campaign. Eligible numbers receive a confirmation text and must reply Y before they are subscribed.

See the List building reference for the full input and response. To send sign-ups from JustUno or another pop-up tool, see Connect an external popup tool.

Who can call this

A sign-in token or an API key that includes contacts:write. Create a key in Settings → API keys. Keep the API key server-side; never ship it in browser or quiz client code. The MCP tool is subscribe_list_building_campaign.

If a request returns 403 insufficient_scope, add that permission to the key.

The campaign must belong to the brand on the credential, be live, and have the API entry method turned on. Otherwise the API answers 404 not_found and does not say why.

Add a subscriber

Replace {campaign_id} with the campaign id from the List Building editor.

curl -X POST "https://api.vyg.app/v1/list-building/campaigns/{campaign_id}/subscribers" \
  -H "Authorization: Bearer $VYG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+15551234567",
  "first_name": "Ava",
  "last_name": "Lee",
  "consent_text": "I agree to receive automated marketing texts from Example Brand. Msg and data rates may apply. Reply Y to confirm. Reply STOP to opt out.",
  "placement": "Website quiz",
  "birth_date": "1990-01-01"
}'

A new number that can receive the confirmation text:

{
	"status": "pending",
	"campaign_id": "8f2b0c1e-5d7a-4b7e-9a51-2c6f1e0d3a44",
	"contact_id": "0c000000-0000-4000-8000-000000000001",
	"message": "We sent a confirmation text. Reply Y to join."
}

Posting the same number again while that confirmation is still open returns pending and does not send a second text.

statusMeaning
pendingA confirmation text was sent, or one is already waiting for a Y reply.
already_subscribedThis number is already subscribed. API calls send no text.
refusedNo text was sent because a cooling period or daily number cap applies.
text_start_requiredThis number previously opted out and must text START to the brand number to rejoin.

phone accepts E.164 (+15551234567) or a US national number. consent_text is required (20–2000 characters) and must be the disclosure the person saw. placement is an optional short description of where they signed up, such as Kiosk at Austin store.

This endpoint is for SMS campaigns. When the campaign has a minimum age, send birth_date as an ISO date (YYYY-MM-DD). That value is stored on the consent record the same way the on-site form stores it. SMS keyword and token sign-up cannot collect a date of birth, so an age-gated campaign is not started from a text.

Retry keys and ask limits

An optional idempotency_key is bound to the normalized phone number within this brand and campaign. Repeating the key with the same phone returns the pending repeat answer without another text while the ask is open. Reusing it for a different phone returns 409 conflict.

After a decline, expiry or opt-out for this campaign, API asks have a 30-day cooling period. A channel that is still unsubscribed returns text_start_required and must text START. API requests are capped at one per number across all campaigns for the brand in a rolling 24 hours. A repeat with an open ask for this campaign returns pending; otherwise it returns refused. The brand cap is 5,000 API-sourced optin_requested consent records in a rolling 24 hours across all API keys. A new ask at that cap returns 429 rate_limited; pending retries still work. The per-key throttle remains 60 subscribe requests per minute.

Failures

Statuserror.codeWhen
400bad_requestconsent_text is missing or too short, phone is not a valid US number, birth_date is missing on an age-gated campaign, or the subscriber is under the campaign's minimum age.
404not_foundNo live SMS campaign with that id for this brand, or the API entry method is not turned on.
409conflictThe caller idempotency key was already used for another phone in this campaign.
429rate_limitedThe key exceeded 60 subscribe requests per minute, or the brand reached 5,000 API requests in 24 hours. The per-key throttle includes Retry-After; the daily cap does not.

A missing consent_text includes the message Include the consent text the subscriber saw. A missing birth_date on an age-gated campaign includes This campaign requires the subscriber's date of birth. An under-age birth_date includes The subscriber does not meet this campaign's age requirement.

On this page