API Reference

Acquisition Campaign Callbacks

These callbacks are triggered in response to changes in data associated with the Acquisition Campaign API. To receive callbacks, please make sure your endpoint is compatible with our endpoint specifications.

🚧

Before you register...

Set up your endpoint before sending any callback configurations. Do not use a "fake" URL to test the configuration, as this will result in errors.

Available Callbacks

Acquisition Participant Added

This callback event is triggered when a new participant has been added to an acquisition campaign.

Callback configuration

When registering for this callback, your request body should look something like the below example. Please note that you’ll need to configure callbacks for each campaign_id separately.

{
  "callback_type": "ack_participant_added",
  "ack_participant_added": {
      "campaign_id": "YOUR_ACQUISITION_CAMPAIGN_KEY"
    },
  "destination":{
     "url":"YOUR_DESTINATION_URL_W_HTTPS", /*Do not use a "fake" URL (such as google.com).*/
     "method":"POST",
     "content_type":"application/json"
  }
}

Callback body

The callback body will include information on the participant and the acquisition campaign. Note that the status will be pending, meaning the participant has begun the flow but has not completed the double-opt-in confirmation.

{
   "event_id":"AB234SDFD234",
   "callback_type":"ack_participant_added",
   "event_type":"ack_participant_added", //deprecated
   "event_date":"2017-03-15T15:42:23Z",
   "participant":{
      "person":{
         "id":"123456789",
         "external_id":"ex123",
         "mobile_phone":{
            "mdn":"+12995551234"
          },
         "url":"/companies/:company_key/mobiledb/persons/AB3423"
      },
      "acquisition_campaign":{
         "id":"C1323542",
         "description":"Great Acquisition Campaign",
         "url":"/companies/:company_key/campaigns/acquisition/ACQ1234",
         "keyword":"SUBSCRIBED"
      },
      "participation_date":"2017-01-14T14:30Z",
      "expire_date":"2017-01-15T14:30Z",
      "status":"PENDING"
   },
  "subscription_list": {
    "id": 1234
  }
}

Acquisition Participant Changed

This callback event is triggered whenever a participant's status has changed due to either confirming or declining an opt-in. Participation timeouts and automatically confirmed opt-ins will not trigger this event.

Callback configuration

When registering for this callback, your request body should look something like the below example. Please note that you’ll need to configure callbacks for each campaign_id separately. 

{
  "callback_type": "ack_participant_changed",
  "ack_participant_changed": {
      "campaign_id": "YOUR_ACQUISITION_CAMPAIGN_KEY"
    },
  "destination":{
     "url":"YOUR_DESTINATION_URL_W_HTTPS", /*Do not use a "fake" URL (such as google.com).*/
     "method":"POST",
     "content_type":"application/json"
  }
}

Callback body

The callback body will include information about the participant, along with one of the following statuses:

StatusDescription
CONFIRMEDParticipant confirmed opt-in by replying Y or with their zip code. They are now subscribed.
REJECTEDParticipant declined confirmation by replying N, No, or any STOP phrase or keyword. The acquisition flow is terminated.
{
   "event_id":"AB234SDFD234",
   "callback_type":"ack_participant_changed",
   "event_type":"ack_participant_changed", //deprecated
   "event_date":"2017-03-15T15:42:23Z",
   "participant":{
      "person":{
         "id":"123456789",
         "external_id":"ex123",
         "mobile_phone":{
            "mdn":"+12995551234"
          },
         "url":"/companies/:company_key/mobiledb/persons/AB3423"
      },
      "acquisition_campaign":{
         "id":"C1323542",
         "description":"Great Acquisition Campaign",
         "url":"/companies/:company_key/campaigns/acquisition/ACQ1234",
         "keyword":"SUBSCRIBED"
      },
      "participation_date":"",
      "expire_date":"",
      "status":"CONFIRMED"
   },
  "subscription_list": {
    "id": 1234
 }
}

Company Participant Added

The company_participant_added callback acts the same as the ack_participant_added callback but without requiring you to specify a specific acquisition campaign. Instead, the callback is triggered whenever a new participant is added to any acquisition campaign associated with your company_key.

Callback configuration

When registering for this callback, your request body should look something like the below example.

{
  "callback_type": "company_participant_added",
  "destination":{
     "url":"YOUR_DESTINATION_URL_W_HTTPS", /*Do not use a "fake" URL (such as google.com).*/
     "method":"POST",
     "content_type":"application/json"
  }
}

Callback body

The callback body will include information on the participant and the acquisition campaign. Note that the status will be pending, meaning the participant has begun the flow but has not completed the double-opt-in confirmation.

{
   "event_id":"AB234SDFD234",
   "callback_type":"company_participant_added",
   "event_type":"company_participant_added", //deprecated
   "event_date":"2017-03-15T15:42:23Z",
   "participant":{
      "person":{
         "id":"123456789",
         "external_id":"ex123",
         "mobile_phone":{
            "mdn":"+12995551234"
          },
         "url":"/companies/:company_key/mobiledb/persons/AB3423"
      },
      "acquisition_campaign":{
         "id":"C1323542",
         "description":"Great Acquisition Campaign",
         "url":"/companies/:company_key/campaigns/acquisition/ACQ1234",
         "keyword":"SUBSCRIBED"
      },
      "participation_date":"2017-01-14T14:30Z",
      "expire_date":"2017-01-15T14:30Z",
      "status":"PENDING"
   },
  "subscription_list": {
    "id": 1234
  }
}

Company Participant Changed

The company_participant_changed callback acts the same as the ack_participant_changed callback but without requiring you to specify a specific acquisition campaign. Instead, the callback is triggered whenever a participant's status is changed for any acquisition campaign associated with your company_key.

Callback configuration

When registering for this callback, your request body should look something like the below example.

{
  "callback_type": "company_participant_changed",
  "destination":{
     "url":"YOUR_DESTINATION_URL_W_HTTPS", /*Do not use a "fake" URL (such as google.com).*/
     "method":"POST",
     "content_type":"application/json"
  }
}

Callback body

The callback body will include information about the participant, along with one of the following statuses:

StatusDescription
CONFIRMEDParticipant confirmed opt-in by replying Y or with their zip code. They are now subscribed.
REJECTEDParticipant declined confirmation by replying N, No, or any STOP phrase or keyword. The acquisition flow is terminated.
{
   "event_id":"AB234SDFD234",
   "callback_type":"company_participant_changed",
   "event_type":"company_participant_changed", //deprecated
   "event_date":"2017-03-15T15:42:23Z",
   "participant":{
      "person":{
         "id":"123456789",
         "external_id":"ex123",
         "mobile_phone":{
            "mdn":"+12995551234"
          },
         "url":"/companies/:company_key/mobiledb/persons/AB3423"
      },
      "acquisition_campaign":{
         "id":"C1323542",
         "description":"Great Acquisition Campaign",
         "url":"/companies/:company_key/campaigns/acquisition/ACQ1234",
         "keyword":"SUBSCRIBED"
      },
      "participation_date":"",
      "expire_date":"",
      "status":"CONFIRMED"
   },
  "subscription_list": {
    "id": 1234
  }
}

Additional Resources