Web-Based Subscriber Management

The following examples show you how to use a web form and Vibes' APIs to opt a Person into or out of your lists.

This scenario assumes you have the double opt-in set up.

Suppose a Person has navigated to your web signup page. Before you can opt the Person into your list, you need to collect their mobile number, then you can make the first API call.

To add a Person to a list, they must first confirm on their handset that they want to receive messages. Vibes uses Acquisition Campaigns to handle the confirmation process, so rather than adding a Person directly to a list, you add a Participant to an Acquisition Campaign. 

Example One: How to Opt a Person Into Your Lists

To opt a Person into your list, call the Add Participant to Acquisition Campaign, which is based on the Acquisition API, as shown in the following example.

If you want to gather additional information from the Subscriber, please work with your Vibes account manager to create custom fields.

API Version 1

{
   "external_person_id":"EXT542342",
   "mobile_phone":{
      "mdn":"2995551234"
   },
   "custom_fields":{
      "first_name":"John",
      "last_name":"Doe"
   }
}

API Version 2 (E.164 MDN Format)

{
   "external_person_id":"EXT542342",
   "mobile_phone":{
      "mdn":"+12995551234"
   },
   "custom_fields":{
      "first_name":"John",
      "last_name":"Doe"
   }
}

For this example, look at the HTTP Status that is returned from the API Call above, then display on the web form that the Person needs to reply Y, or that they are already on the list.

SUCCESS: 201
{
   "person":{
      "external_person_id":"EXT532342",
      "person_id":"AB3423",
      "url":"/companies/:company_id/mobiledb/persons/AB3423"
   },
   "participation_date":"",
   "expire_date":"2017-01-16T14:30Z",
   "status":"PENDING"
}
 
FAILURE (invalid carrier): 422
{"errors":[{"message":"PersonErrors::MdnChangeNotAllowed"}]}
 

Status Codes are used for specific API Call results. In this example, status codes 201 and 422 are returned.

The sign-up landing page graphic shows an example of the possible API Call results that could be returned.

• 201: "Thanks for signing up! Reply Y to the message on your phone to confirm your registration."
  This means the Person was not Subscribed and was sent a confirmation message to confirm their Subscription.
• 200: "We already received your request to sign up, and you should have received a prompt to confirm your number. Please send Y to 12345 to confirm your subscription".
  This means the Person has not confirmed their Subscription.
  
• 409: "You are already signed up! If you are not receiving messages, please contact customer care at Vibes.com/help".
  This means the Person has tried to Subscribe more than once, but are already Subscribed.
  
• 404, 422, or other error: "I’m sorry, we did not recognize your phone number as a valid mobile number. Please double check your number."
  This means the Person's mobile number is invalid. Alert your operations team, there's an issue with your API calls.

Example Two: How to Opt a Person Out of Your Lists

To opt a Person out of your list, you can make a Remove Subscriber API call, similar to what is shown in the following example.

Using Vibes Person ID
DELETE  /companies/abc123/mobiledb/persons/abc123/subscriptions/1
 
Using customer external ID
DELETE  /companies/abc123/mobiledb/persons/external/abc123/subscriptions/1
 

The following Return example confirms on your landing page that a Person has been removed from the list or was not Subscribed to the list to begin with.

SUCCESS: 200
no body returned
 
FAILURE: 404
no body returned

Status Codes are used for the following results.

• 200: "We already received your request to sign up, and you should have received a prompt to confirm your number. Please send Y to 12345 to confirm your subscription".
  This means the Person has not confirmed their Subscription.
  
• 404: "I’m sorry, we did not recognize your phone number as a valid mobile number. Please double check your number."
  This means the Person's mobile number is invalid. Alert your operations team, there's an issue with your API calls.

See the following topics for more detailed information on how to use the Vibes APIs to add a Person to (or remove a Person from) your list.

• Opting in: Add Participant to Acquisition Campaign.
• Opting out: Subscription API Methods.