API Opt-in

Here we will show you how to programmatically opt-in a phone number as subscriber via our API.




Creating an API Opt-in Campaign

Refer to our List Building Overview to learn more about creating a campaign generally. 

For each account, there will always be one preloaded API Opt In campaign, by default.  You will need to toggle it on for usage.


Getting a Campaign ID

Save your API List Building campaign as a draft, then edit it again to see the assigned CampaignID. You'll need this value for use in the API request. It can be found in the URL after "list-building" or when editing the modal, under the Design tab you can click on Edit Source Code:


Note: Double Opt-in is required for compliance.

Back to Top


API Opt-in Implementation Specifications

Technical details associated with making the API request are as follows. You can also see an example in the section Using JavaScript below.

POST: /api/v2/subscriber

Host: vyg.mobi

Accept: application/json

Content-Type: application/json

Body/Payload: Replace the campaignId value in this code with your Campaign ID, and ensure phone numbers are properly formatted with a + and the country code according to E.164 format:


"phoneNumber": "+15134XXXXXX‬",
"campaignId": <CAMPAIGN_ID>


subscriberId: 99999,
state: "Subscribed",

Example Payload with Optional Attributes

"phoneNumber": "+15555555555",
"campaignId": 1234,
"attributes": {
"email": "my@domain.com"

Expected response codes:

200 = Already a subscribe and can receive messages

201 = Have signed up successfully, and ready to receive messages.

202 = Have signed up successfully, but waiting for a double optin confirmation until fully subscribed and can receive messaging.

Back to Top


JavaScript and cURL Examples


const data = {
phoneNumber: "+15134XXXXXX‬",
campaignId: <CAMPAIGN_ID>

fetch('https://vyg.mobi/api/v2/subscriber', {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json',
body: JSON.stringify(data)
.then(response => response.json())
.then(data => {
console.log('Success:', data);
// Success: { subscriberId: 00000, state: "Subscribed" }
.catch((error) => {
console.error('Error:', error);
// Error: "Bad Request: Must be a US number starting with +1"

Note: CORS-supported to allow all origins.


curl --location --request POST 'https://vyg.mobi/api/v2/subscriber' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{ "phoneNumber": "+15134XXXXXX‬","campaignId": <CAMPAIGN_ID> }'


Already Subscribed Messages are never sent via API Opt-In to prevent people who are already subscribed from receiving messages. This is for spam prevention and to allow bulk import of numbers via API.

As a standard approach we recommend returning an Already Subscribed message or Subscribed Successfully based on the API call response.

Back to Top



If you have any additional questions please contact us at service@voyagesms.com.