Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 26 Next »

It is important that you send Catapult the relevant data about Subscribers in your 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 easily keep Catapult in sync with your most current People data, and have your system notified each time a Person is confirmed on a list or opts out of a list, as well as when data is exchanged between the two systems.  

This topic provides the following API and Callback examples:

New Subscribers - Customer Hosted

When a Person adds a mobile number to your preference center, and you want to sign them up, you should go through the Subscriber Sign-up Through a Mobile Phone process as described in the previous scenario.

New Subscribers - Catapult Hosted

When a new Subscriber comes into your mobile database through a Catapult landing page or SMS opt-in, your CRM system can receive a callback to an API endpoint. The following example shows the standard format for callbacks.

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.

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

How to Add Data About Your Subscribers

Your CRM system can add near real-time data about your Subscribers at any time. Please work with your Vibes Account Manager to determine the best format in which to store your data. Vibes supports strings, multi-select and single-select lists, date/time, as well as other formats. 

The following example shows how to use an API Call to add a Person.

API Call: Adding a Person
POST 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"
   }
}

As shown in the following Return example, you will receive back an HTTP code letting you know if the Person was added, if an existing Person was found, and that your new entry was merged.

Return: Adding Person
SUCCESS: 200, 201 - person added or person merged/updated
Same Person body you submitted is returned

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 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
  • No labels