VYG Docs
Concepts

Connect an external popup tool

Send sign-ups from JustUno or any form post into a list campaign through a List ID and webhook.

Use this when a pop-up tool you already run should add people to a list campaign. The person always receives a confirmation text and must reply Y before they are subscribed.

The List ID is the credential. Do not put an API key in the tool.

Set up the campaign

  1. Open the campaign's Subscribe trigger and turn on Pop-up Integration.
  2. Copy the List ID (lst_…) and the Webhook URL.

Webhook URL:

https://api.vyg.app/v1/list-building/webhooks/{list_id}

Replace {list_id} with the List ID from the form.

JustUno

  1. Create a modal in JustUno.
  2. Paste the List ID or the webhook URL into the tool's webhook or integration field.
  3. Send the form as JSON or as a form post.

You can also add ?tool=justuno to the URL, or send an X-Tool: justuno header. If the payload uses JustUno field names (phone_number, first_name, page_url), the tool is detected automatically.

Any tool that can post a form to a URL

Point the tool at the webhook URL. JSON and application/x-www-form-urlencoded bodies are accepted.

Fields

The webhook reads these keys (first match wins):

FieldAccepted keys
Phonephone, phone_number, $phone_number
First namefirstName, first_name
Last namelastName, last_name
Emailemail
ConsentconsentText, consent_text
Page URLpageUrl, page_url, url
Event idid, submission_id, event_id
Date of birthbirth_date, birthdate, dob, date_of_birth (YYYY-MM-DD)

Phone is required. Other fields are optional. Extra keys are stored with the sign-up.

Send consent_text with the exact disclosure the shopper saw. When omitted, the consent log stores no disclosure text; the shopper's Y reply remains the consent event.

When the campaign has a minimum age, send a date of birth. A missing date of birth is 400 invalid_payload with This campaign requires the subscriber's date of birth. An under-age date is 400 with The subscriber does not meet this campaign's age requirement. Nothing is stored in either case. An old-enough date is stored on the consent record the same way the subscribe API stores it.

Responses

StatusBodyWhen
202{ "status": "accepted" }The sign-up was accepted. The response does not disclose subscriber status.
400{ "error": "invalid_payload", "message": "…" }The body is not a JSON object or form fields, has no usable phone number, is missing a date of birth on an age-gated campaign, or the subscriber is under the campaign's minimum age. Nothing is stored.
404{ "error": "not_found", "message": "…" }The List ID is unknown or Pop-up Integration is not on for a live campaign.
429{ "error": "rate_limited", "message": "…" }The source IP, List ID, or rolling campaign daily cap was exceeded.

A malformed payload never creates a contact.

See List building for the authenticated subscribe endpoint.

Consent text is limited to 2000 characters, page URLs to 2048, and submission IDs to 128. Oversized fields return 400 invalid_payload. Extra metadata is limited to 20 keys, with each value truncated to 1000 characters.

The webhook also limits requests per source IP (600/minute) and per List ID (120/minute), and new confirmation asks per campaign (5000 in a rolling 24 hours). Exceeding a limit returns 429 rate_limited.

On this page