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
Getting a Campaign ID
API Opt-in Implementation Specifications
JavaScript and cURL Examples

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.

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:

Request

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

Response

{ 
  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.

JavaScript and cURL Examples

JavaScript

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

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.

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