Keeping Data In Sync with Vibes Platform

Even though you use Vibes Mobile Engagement Platform as your main Opt-in database, your CRM system contains your Subscriber data, so you need to use APIs and Callbacks to communicate between your systems and the Platform.

The Platform does not collect additional data automatically, so if you want to take advantage of its extensive targeting and personalization capabilities, you can also use APIs to send the Platform the relevant data about Subscribers in your Customer Relationship Management (CRM) system. This will help you to do the following:

• Easily keep the Platform in sync with your most current Persons data.
• Have your system notified each time a Person is confirmed on a list or opts out of a list.
• Have your system notified when data is exchanged between the two systems. 

The following are some common situations where you can use a Vibes API or Callback.

1. When someone Subscribes using the Platform, you can use the Subscription Added Callback.

2. When someone updates their preferences and personal data outside of the Platform, you can use the Update a Person API.
   

   Note: If there is custom data you want to store, you need to set up the custom fields ahead of time.

3. When you need to add data about your Subscribers, use the Add Person API.
4. When someone unsubscribes, you can use the Subscription Removed Callback.

Situation One: New Subscribers - Vibes Mobile Engagement Platform Hosted

When a new Subscriber comes into your mobile database through a Vibes Mobile Engagement Platform landing page or Short Message Service (SMS) opt-in, your CRM system can receive a callback to an API endpoint.

The following example shows a Subscription Added Callback.

{
   "callback:id","DEF123",
   "event_id":"AB234SDFD234",     
   "callback_type":"subscription_added",
   "event_type":"subscription_added", //deprecated 
   "event_date":"2017-02-15T15:42:23Z",
   "delivery_attempt":"1",
   "subscription":{
      "person":{
         "id":"ABC123",
         "external_id":"ex1234",
         "url":"/companies/:company_key/mobiledb/persons/ABC123"
      },
      "subscription_list":{
         "id":"1234",
         "url":"/companies/:company_key/mobiledb/subscription_lists/1234"
      },
      "opt_in_date":"2017-01-15T15:34:52Z",
      "acquisition_campaign":{
         "id":"2342312",
         "url":"/companies/:company_key/campaigns/acquisition/2342312"
      },
      "url":"/companies/:company_key/mobiledb/persons/ABC123/subscriptions/1234"
   }
}

Situation Two: Updating Data About Your Subscribers

As shown in the following API Call example, when updating data about your Subscribers, you can use a unique identifier from your CRM system (external_person_id), or you can use the Vibes person_id.

The examples show API Version 1 and Version 2.

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

As shown in the following Return example, you will receive back an HTTP code letting you know if the Person was updated, if the Person was not found, or if the MDN can’t be changed.

SUCCESS: 200
Same Person body you submitted is returned
 
 
FAILURE: 404 - person not found
no body
 
FAILURE: 409 - MDN cannot be changed
no body

Add a Person

Use the following to create a new Person record.

The person_id, timezone_source, created_at and updated_at fields are not allowed, and any values will be ignored.

The mobile_phone field is optional and can be omitted. All custom fields are also optional and may be omitted.

Situation Three: When a Subscriber Opts Out

When a Person opts out via their mobile device, the Platform will send your system a notification that they are no longer a mobile Subscriber, as shown in the following example. 

{
   "callback_id":"DEF124",
   "event_id":"AB234SDFD234",     
   "callback_type":"subscription_removed",
   "event_type":"subscription_removed", //deprecated 
   "event_date":"2017-03-15T15:42:23Z",
   "delivery_attempt":"1",
   "subscription":{
      "person":{
         "id":"ABC123",
         "external_id":"ex1234",
         "url":"/companies/:company_key/mobiledb/persons/ABC123"
      },
      "subscription_list":{
         "id":"1234",
         "url":"/companies/:company_key/mobiledb/subscription_lists/1234"
      },
      "opt_in_date":"2017-01-15T15:34:52Z",
      "opt_out_date":"2017-02-18T15:34:52+0000",
      "opt_out_reason":"user_opt_out",
      "acquisition_campaign":{
         "id":"2342312",
         "url":"/companies/:company_key/campaigns/acquisition/2342312"
      },
      "url":"/companies/:company_key/mobiledb/persons/ABC123/subscriptions/1234"
   }
}