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
- Generate API Key in Voyage
- 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.
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:
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"
}
}
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.
If you have any additional questions please contact us at service@voyagesms.com.