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



Generate API Key in Voyage

Next, you'll need to generate an API Key in Voyage if you don't have one already. Click on Settings [1], then select Advanced [2]. From there click on + Add API Key [3]:



They key will be instantly generated, and you can click here to copy it:Copy-API-Key

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"

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 a 200 (Already Subscribed) vs. 201 (Subscribed Successfully) in the API call response, which should be handled by the developer to present an already subscribed message to the customer on the UI.

Back to Top



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