Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Last Updated:

Lastupdatedate

Livesearch
placeholderSearch the Vibes Developer Wiki
typepage



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.

Note

Note: If you are using Version 2 of the APIs, a mobile number must use the E.164 format. E.164 is the official format for all international phone numbers that includes a plus sign followed by the country code and phone number.

For example:

  • U.S.: +12135551234
  • U.K.: +442135551234

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

API Version 1

Code Block
titleAPI Call: Add Participant to Acquisition Campaign
{
   "external_person_id":"EXT542342",
   "mobile_phone":{
      "mdn":"2995551234"
   },
   "custom_fields":{
      "first_name":"John",
      "last_name":"Doe"
   }
}

API Version 2 (E.164 MDN Format)

Code Block
titleAPI Call: Add Participant to Acquisition Campaign
{
   "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.

Code Block
titleSample Returns: Add Participant to Acquisition Campaign
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.
Note

Note: If you want to see all of the current Subscriptions for a Person to decide which ones to opt the Person out of, you can use the Get All Subscription Lists API to show their Subscriptions.

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.

Code Block
titleAPI Call: Remove Subscriber
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.

Code Block
titleSample Return: Remove Subscriber
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.