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.