Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added note about custom fields needing to first be created in platform prior to sending via API


Last Updated:

Lastupdatedate

Livesearch
placeholderSearch the Vibes Developer Wiki
typepage



Anchor
getacquisitioncampaigns
getacquisitioncampaigns
Get Acquisition Campaigns

Acquisition Campaigns are used to kick off the Subscription process.

The following retrieves an array of all the Acquisition campaigns currently active in the company.

Code Block
GET /companies/:company_key/campaigns/acquisition


Note
Note: To get your company ID, please contact your Vibes account manager.

Request JSON

There is no Request JSON with a GET.

Return JSON

A maximum of 50 records will be returned.

Code Block
[
   {
      "acquisition_id":"Kwnl5OL3",
      "description":"Great Acquisition Campaign",
      "campaign_type":{
         "code":"ACQUISITION"
      },
      "status":"active",
      "start_date":"2016-04-05T14:30Z",
      "end_date":"2017-04-05T14:30Z",
      "created_date":"2015-04-05T14:30Z",
      "updated_date":"2015-04-08T14:30Z",
      "acquisition_campaign":{
         "keywords":[
            "STORE",
            "STOR",
            "STORES"
         ]
      },
      "url":"/companies/:company_key/campaigns/acquisition/Kwnl5OL3"
   },
   {
      "acquisition_id":"ugW37mWsM",
      "description":"Great Acquisition Campaign",
      "campaign_type":{
         "code":"ACQUISITION"
      },
      "status":"Active",
      "start_date":"2016-04-05T14:30Z",
      "end_date":"2017-04-05T14:30Z",
      "created_date":"2015-04-05T14:30Z",
      "updated_date":"2015-04-08T14:30Z",
      "acquisition_campaign":{
         "keywords":[
            "STORE",
            "STOR",
            "STORES"
         ]
      },
      "url":"/companies/:company_key/campaigns/acquisition/ugW37mWsM"
   }
]


Note

Note: A HTTP 404 - Not Found will be returned if the Acquisition Campaign cannot be located.

Anchor
getacquisitioncampaign
getacquisitioncampaign
Get Acquisition Campaign

The following will retrieve a particular Acquisition Campaign object by its ID.

Code Block
GET /companies/:company_key/campaigns/acquisition/:acquisition_id


Note
Note: To get your company ID, please contact your Vibes account manager.

Request JSON

There is no Request JSON with a GET.

Return JSON

Code Block
{
   "acquisition_id":"Kwnl5OL3",
   "description":"Great Acquisition Campaign",
   "campaign_type":{
      "code":"ACQUISITION"
   },
   "status":"active",
   "start_date":"2016-04-05T14:30Z",
   "end_date":"2017-04-05T14:30Z",
   "created_date":"2015-04-05T14:30Z",
   "updated_date":"2015-04-08T14:30Z",
   "acquisition_campaign":{
      "keywords":[
         "STORE",
         "STOR",
         "STORES"
      ]
   },
   "url":"/companies/:company_key/campaigns/acquisition/Kwnl5OL3"
}


Note

Note: A HTTP 404 - Not Found will be returned if the Acquisition Campaign cannot be located.

Anchor
searchforpendingparticipants
searchforpendingparticipants
Search for Pending Participants

There are three ways to search for pending Participants:

  • By person_id.
  • By external_person_id.
  • By mdn.

The following GET code shows these three searches.

Code Block
GET /companies/:company_key/campaigns/acquisition/:acquisition_id/participants?person_id=:person_id
GET /companies/:company_key/campaigns/acquisition/:acquisition_id/participants?external_person_id=:external_person_id
GET /companies/:company_key/campaigns/acquisition/:acquisition_id/participants?mdn=:mdn

Request JSON

There is no Request JSON with a GET.

Return JSON

The following returns an array of active (status=PENDING) Participants in the Acquisition Campaign.

Code Block
[
   {
      "person":{
         "person_id":"AB3423",
         "url":"/companies/:company_key/mobiledb/persons/AB3423"
      },
      "participation_date":"2016-04-03T14:30Z",
      "expire_date":"2016-04-05T14:30Z",
      "status":"pending"
   }
]


Note

Note: An HTTP 404 - Not Found will be returned if the entity does not exist.

Anchor
addparticipant
addparticipant
Add a Participant

The following shows adding a Participant. When adding a Participant, the specified Person is added to the Acquisition Campaign. You need to use the Person entity with the Acquisition call.

Code Block
POST /companies/:company_key/campaigns/acquisition/:acquisition_id/participants

You can add whatever amount of data that is available about the Person. An existing unsubscribed Person record will be searched for, and if found, it will be updated.

Note
Note: This will not be updated if a Subscription already exists.


  • At a minimum, either person_id, external_person_id or MDN must be specified.
  • Any fields specified for the Person will be updated with the new values.
  • Any fields whose values are set to Null will be removed from the Person.
  • Any fields completely omitted will be ignored, and any existing values will remain.
  • These changes will only be performed if a 2xx HTTP response is returned by the API call.
  • Note, custom fields must first be created in the Vibes Platform prior to sending via API.

Request JSON

Code Block
{
   "person_id":"AB3423",
   "external_person_id":"EXT542342",
   "mobile_phone":{
      "mdn":"+12995551234"
   },
   "custom_fields":{
      "first_name":"Steve",
      "rewards_id":"543557654",
      "favorite_stores":[
         {
            "id":"4",
            "name":"My Hardware Store",
            "option_key":"my_hardware_store"
         },
         {
            "id":"12",
            "name":"Local Grocery",
            "option_key":"local_grocery"
         }
      ]
   }
}

Return JSON

The return data will be the Acquisition Campaign participation object.

Code Block
{
   "person":{
      "person_id":"AB3423",
      "url":"/companies/:company_key/mobiledb/persons/AB3423"
   },
   "participation_date":"2016-04-04T19:09:16Z",
   "expire_date":"2016-04-05T14:30Z",
   "status":"pending"
}

Return HTTP Codes

  • 200: This means the Person has a pending acquisition and has not yet confirmed.
  • 201: Depending on the "status", the following can be returned:
    • pending - This means the Person was not Subscribed and was sent a confirmation message to confirm.
    • SUBSCRIBED - This is returned when the Person is Subscribed and the welcome message was sent to their phone.
  • 400: The supplied mobile number is not in proper mobile number format
  • 409: Already Subscribed -This means the Person has tried to Subscribe more than once, but are already Subscribed.
  • 422: is returned in the following situations:
    • A MdnHasConfirmationBlock message is returned when the Person has previously replied “No” to a Subscription prompt.

    • The supplied mobile number ("mdn") does not map to a provisioned carrier. It is mostly returned for a landline number.
    • An ExternalPersonIDMismatch message is returned when trying to Subscribe a Person with an External Person ID that is already in use.

    • An error listing specific elements from the body is returned when trying to populate custom field data for custom fields unknown to the platform.