Keeping Data In Sync with Catapult

If you want to take advantage of Catapult's capabilities, you can send Catapult the relevant data about Subscribers in your Customer Relationship Management (CRM) system to take full advantage of Catapult's extensive targeting and personalization capabilities. You can do this through a combination of API calls and callbacks to do the following:

Easily keep Catapult in sync with your most current People 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 scenarios are for when you need to keep your system and Catapult data in sync. Even though you use Catapult as your main Opt-in database, your CRM system contains your Subscriber data. Catapult does not collect additional data automatically, so you need to use APIs and Callbacks to communicate between your systems and Catapult.

These are some common situations where you need to use an API.

Someone Subscribes using Catapult. You will use the Subscription Added Callback.
Someone updates their preferences and personal data outside of Catapult. You would use the Update a Person API.
Note: If there is custom data you want to store, custom fields need to be set up ahead of time.
Someone Unsubscribes. You will use the Subscription Removed Callback.

Note: When a Person adds a mobile number to your preference center, and you want to sign them up, you should go through the Web-Based Subscriber Management process as described in the previous scenario.

Situation One: New Subscribers - Catapult Hosted

When a new Subscriber comes into your mobile database through a Catapult 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.

Subscription Added Callback

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

Note: If you need Catapult to call a pre-existing API, the Vibes Mobile Solutions Group can create a custom integration solution for you.

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 in your CRM system (external_person_id), or you can use the Vibes person_id.

API Call: Updating a Person

PUT http://public-api.vibescm.com/mobiledb/persons
 
Headers
Content-Type: Application/JSON
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
 
BODY
{
   "external_person_id":"EXT542342",
   "mobile_phone":{
      "mdn":"2995551234"
   },
   "custom_fields":{
      "first_name":"John",
      "last_name":"Doe"
   }
}

Note: If you are unable to update by ID and only have the Mobile Directory Number (MDN), then you can use the Add Person API call, and Vibes will merge the MDN's information with the existing person.

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

Return: Updating a Person

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

Situation Three: Opting Out Subscribers

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

Subscription Removed Callback

{
   "callback_id":"DEF124",
   "event_id":"AB234SDFD234",
   "event_type":"subscription_removed",
   "event_date":"2017-03-15T15:42:23Z",
   "delivery_attempt":"1",
   "subscription":{
      "person":{
         "id":"ABC123",
         "external_id":"ex1234",
         "url":"/companies/:id/mobiledb/persons/ABC123"
      },
      "subscription_list":{
         "id":"1234",
         "url":"/companies/:id/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/:id/campaigns/acquisition/2342312"
      },
      "url":"/companies/:id/mobiledb/persons/ABC123/subscriptions/1234"
   }
}

For more detailed information on these API and Callback examples, see the following topics:

Subscription Added Callback – For a new Subscriber through a Catapult landing page or SMS opt-in.
Subscription Removed Callback – Opting out Subscribers.
Add Person API Call – How to add data about your Subscribers.
Update a Person API Call – Updating data about your Subscribers.