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:

Find-Voyage-CampaignID-New

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]:

Settings-Advanced-API-Key

 

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:

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"
}
}

Back to Top

 

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