Overview
The GET Contact by Channel API allows you to retrieve the contact for a given database, channel, qualifier and destination. The PATCH Contact by Channel API will add or update a contact with the given contact data using channel information.
Functionalities Available
The ContactbyChannel API call has GET functionalities.
GET: This call returns the contact that matches the database, channel, qualifier and destination information provided in the request call.
GET /databases/{databaseId}/contactbychannel/{channel}-{qualifier}/{destination}
(e.g. /databases/746583/contactbychannel/PUSH-appKey1000/MUID1234|XCID4321)
Scenarios that can be accomplished using this API
Retrieve a contact for the given database ID, channel, qualifier, and destination.
Request body
Not applicable.
Path Parameters
| Parameter | Value | Description | Parameter type | Data type |
|---|---|---|---|---|
| databaseID | Required | ID of the database enabled for SMS or Push | path | long |
| channel | Required | SMS or Push | path | String |
| qualifier | Required | Text to Join Program ID for SMS; AppKey for Push | path | String |
| destination | Required | SMS phone number for SMS; Xtify user ID and chnnel ID for Push | path | String |
Response Content Type
application/json
| Attribute | Required | Description | Data type |
|---|---|---|---|
| No | A contact's email address | String | |
| emailType | No | The type of email to send to a contact (HTML or TEXT) | String |
| leadSource | No | The lead source for a contact | String |
| optInDetails | No | The opt in details of a contact; can only be set on a contact being added | String |
| customFields | No | A list of custom field values | ArrayFieldValue |
Response Model Schema
{
"email": "String",
"emailType": "String",
"leadSource": "String",
"optInDetails": "String",
"customFields": [
"FieldValue"
]
}
Sample JSON Response Body
{
"email":"[email protected]",
"emailType":"HTML",
"leadSource":"Trade Show",
"optInDetails":"Opted in via iPad",
"customFields":[
{
"name" : "First Name",
"value" : "Bob"
},
{
"name" : "Last Name",
"value" : "Andrews"
},
{
"name" : "Alias Id",
"value" : "UserAccount4567"
}
]
}
Swagger URL
https://api-campaign-[data center]-[pod#].goacoustic.com/restdoc/#!/databases/databases_contactbychannel_get_get_11
Functionalities available
The API call has PATCH functionalities.
PATCH: This call is used to add or update a contact with the given contact data using channel information.
PATCH /databases/{databaseId}/contactbychannel
(e.g. /databases/746583/contactbychannel)
Scenarios that can be accomplished using this API
If a contact is found, the record is updated with the given information and consent is applied. If a contact is not found, the API will add a new contact record and apply consent.
Populate any profile fields in the contact record based on the information you know from their registration or from their profile data in the external system. It is recommended to pass the external system’s alias identifier to Acoustic Campaign so that it can be stored in the contact record and used as a lookup key field. Additionally, the mobile app could pass the appkey, userid/channelid back to the external system and store this as a unique identifier in the customer’s record.
Note: For the Push channel the Contact by Channel API is used by backend systems to add a contact and consent for push to Acoustic Campaign with registration IDs provided by our internal Push platform. It cannot be used to add consent for push by custom systems and any contacts or consent added will not result in push notifications being delivered by Acoustic Campaign.
Request Body
Path Parameters
| Parameter | Required | Description | Data type |
|---|---|---|---|
| databaseId | Yes | ID of the SMS or Push-enabled Database where the Contact will be inserted or updated | long |
ContactByChannelSpecification
| Attribute | Required | Description | Data type |
|---|---|---|---|
| channel | Yes | The channel data to identify a contact | model |
| contact | No | The values to set on the new or updated contact | model |
Channel Data
| Attribute | Required | Description | Data type |
|---|---|---|---|
| channelType | Yes | SMS or PUSH | String |
| qualifier | Yes | Text to Join Program ID for SMS; AppKey for Push | String |
| destination | Yes | SMS phone number for SMS; Xtify user ID and channel ID for Push | String |
| status | No | Opt in status. Acceptable values are ‘OPTED-IN’ and ‘OPTED-OUT’ | String |
| consentDate | No | Optional timestamp represented in a String (1970-01-01T00:00:00.000Z). ISO is the default format. | Date |
| consentSource | No | The source of the contact. Defaults to ‘API’ if not included. | String |
Attributes
| Attribute | Required | Description | Data type |
|---|---|---|---|
| timezoneId | No | ID of the time zone | String |
Contact
| Attribute | Required | Description | Data type |
|---|---|---|---|
| No | No | String | |
| emailType | No | The type of email to send to a contact (HTML or TEXT) | String |
| leadSource | No | The lead source for a contact | String |
| optInDetails | No | The Opt In details of a contact; can only be set on a contact being added. | String |
| customFields | No | Name value pairs representing columns in the database and their values. | ArrayFieldValue |
Swagger URL
https://api-campaign-XX-Y.goacoustic.com/restdoc/#!/databases/databases_contactbychannel_get_get_14
Note: XX is Country and Y is the number (https://api-campaign-us-0.goacoustic.com/restdoc/#!/databases/databases_contactbychannel_get_get_14)
SampleJSON Request Body
{
"channel":{
"channelType":"PUSH",
"qualifier":"appKey100",
"destination":"MUID1234|XCID4321",
"status":"OPTED-IN",
"consentDate":"2015-05-01T23:01:12.000Z"
},
"contact":{
"email":"[email protected]",
"emailType":"HTML",
"leadSource":"Trade Show",
"customFields":[
{
"name" : "First Name",
"value" : "Bob"
},
{
"name" : "Last Name",
"value" : "Andrews"
},
{
"name" : "Alias Id",
"value" : "UserAccount4567"
}
]
}
}
When you use the GET method for the contactychannel Rest API call, you can retrieve the contact for a given database, channel, qualifier, and destination regardless of bad data.
When you use the Patch method for the contactychannel Rest API call, you will get a 422 error for bad data. Since the PATCH method is used to add or update a contact with the given contact data using channel information, the validation process will run for this call.
The error could be generated for bad data in ANY of the data fields for the record and not just for the fields that they are specifying in the Rest API call.