Skip to end of metadata
Go to start of metadata


Last Updated: Tuesday, August 27, 2019



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.

GET /companies/:company_key/campaigns/acquisition
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.

[
   {
      "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: A HTTP 404 - Not Found will be returned if the Acquisition Campaign cannot be located.

Get Acquisition Campaign

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

GET /companies/:company_key/campaigns/acquisition/:acquisition_id
Note: To get your company ID, please contact your Vibes account manager.

Request JSON

There is no Request JSON with a GET.

Return JSON

{
   "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: A HTTP 404 - Not Found will be returned if the Acquisition Campaign cannot be located.

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.

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=ATTEMPTED) Participants in the Acquisition Campaign.

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

Return HTTP Codes

  • 200: OK - This is returned for all valid requests. The array with be empty for entities without pending subscriptions.
  • 400: The supplied mobile number is not in proper mobile number format

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.

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: 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

{
   "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.

{
   "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.


  • No labels

12 Comments

  1. Steve - how should we put in what's required?

  2. Also - let's discuss the carrier codes; also should we call it Vibes PersonID instead of PersonID?

  3. Document what happens if you don't provide a phone number

  4. 2 Questions for app_participant

    1. When we find the person either has a pending participation or is already subscribed, should we return the participation entity, or an error entity with the 409?

    2. When expire_date or participation_date is to not be provided, should we set it to null or the empty string? My person preference is null.

    1. 1. This is why I don't like doing two operations in one API call. I think if they are already a pending participant, we should return 200 - Ok and still update the person record. If they are not a pending participant, we should return 201 - Created and add/update the person record. We'll use the 200 v 201 to differentiate if they were created as a participant, not whether the person record existed.

      If they already exist on the list, then I think we should simply return a 409 - Conflict and not update any of the information. 

      2. Expiration date should not be able to be specified. Expiration date should be set by the Acquisition campaign (I believe CM now defaults/uses 24 hours). Likewise, the participation date should not be set, but is simply when the person was added to the campaign (essentially like created_at).

      1. On Item 1.

        Here is what we currently have implemented:

        1. Create/Update the patron in MobileDB
          1. If a person_id is provided, update by that
            1. if the person can't be found, or doesn't have an mdn, return a validation error
          2. Else if a mdn is provided, create/update by that
          3. Else raise a validation error
        2. Check for a pending acquisition event, and return that as a 409 error response
        3. Check to see if the mdn is already subscribed to the list
          1. if it is, return that as a 409 Error Response
          2. else, create a new acquisition event and return a 200/201 with the participation entity

        Here is what I believe you are asking for

        1. Check if the person is already subscribed to the list
          1. if a person id is provided with no mdn, we need to use it to look up the mdn first (should we look up the person even if an mdn is provided? If yes, then what do we do if there is an existing mdn on the person and it is different from the one that was provided?)
          2. if they are subscribed, return a 409
        2. Create/Update the person record in mobiledb
        3. Check for an existing acquisition event.
          1. If there is one, return that with a 200.
          2. else, create one and return a 201.

        What do you think?

      2. On Item 2. I was referring to when we are returning the expire_date and participation_date. My original question could have been clearer.

        1. I would set it to null in the response.

  5. Unknown User (jitendra.bethina)

    Also should the id in person be person_id to be consistent with the rest of the API calls.

    1. Yes, use person_id. You'll probably need to change other cases where we started using id instead of the full descriptive name (Most of those are probably copy/paste from MobileDB APIs.

  6. Having an issue with searching for pending participants. I'm getting a "route not found" error. 

  7. Unknown User (dean.lappi)

    Per Sam's request based on an issue noticed by Jen Hobbs, we changed "ATTEMPTED" to "PENDING" in two Acquisition Campaign JSON Return code examples.

    Return JSON

    The return data will be the Acquisition Campaign Participation Object.

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

    Return JSON

    The following returns an Array of Active (status=Attempted) Participants in the Acquisition Campaign. Future capabilities could be to have a search for past participants, which is why it's an Array to return multiple values.

     

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