API - Supporter Data Overview

The API provides you the ability to fully manage the census information about a supporter.  The following table lists the end points that you can use for reading, adding, updating, and deleting supporter information from Salsa Engage.

 

MethodEnd PointDetail
POST /api/integration/ext/v1/supporters/search

Provides the ability to search for supporters by the following

  • Email address
  • External ID
  • Salsa Engage ID
  • Those that have been modified since a specific period of time
    or within a specific period of time
PUT /api/integration/ext/v1/supporters Add or updates the provided list of supporters
DELETE /api/integration/ext/v1/supporters Deletes the provided list of supporters

All calls listed above require that the API token be sent in the HTTP header using the parameter name authToken=<your_auth_token> 

 

Searching for Supporters

  • /api//integration/ext/v1/supporters/search

Searching for supporters can be performed in one of two ways

  • Specifying a list of ids such as email address, external id, or Salsa Engage id.   It should be understood that the provided ids must all be of the same type - passing a mix of ids is not supported.
  • Specifying a modifiedFrom date and optional a modifiedTo date to search for those who were modified on or after or in between that criteria - note that this is for modification of their census data(First Name, Last Name, Address, Contacts, etc)

Request Body Format

The request body format is as follows:

{

  "header" :{"refId":"optionalId"}, 

  "payload":{
         "modifiedFrom":"2016-05-26T11:49:24.905Z",
         "offset":0,
         "count":20}

}

 

ParameterLocationDescription
refId header An optional value that can be provided by the caller as a correlation Id. This value will be returned in the header or the response payload.
identifiers payload
  • List of Salsa Engage supporter ids
  • List of email addresses
  • List of external Ids
identifierType payload

If a list of identifiers is provided, then the identifier type is required
Must be one of:

  • SUPPORTER_ID
  • EMAIL_ADDESS
  • EXTERNAL_ID
modifiedFrom payload Date from to retrieve activities - ISO_8601 formatted String with a GMT timezone
modifiedTo payload Date to retrieve activities - ISO_8601 formatted String with a GMT timezone
offset payload Starting count at which to retrieve activities - supports pagination and is only applicable when modifiedFrom and modifiedTo searching is used
count payload Number of activities to retrieve - supports pagination and is only applicable when modifiedFrom and modifiedTo searching is used

 

Request Example

DescriptionBody
Get any supporters since a specific date
{"payload":{
"modifiedFrom":"2016-05-26T11:49:24.905Z",
"offset":0,
"count":20}
}
Get supporters within a date range
{"payload":{
"modifiedFrom":"2016-04-26T11:49:24.905Z",
"modifiedTo":"2016-05-26T11:49:24.905Z",
"offset":0,
"count":20}
}
Get specific supporters by
Salsa Engage supporterId
{"payload":{
"identifiers":[
 "0B99B409-E56D-4530-A226-474C61461DB4",
"7EEEED4B-40A4-4FCE-B107-AE643AD1D926",
"9AC97182-671C-4364-B69A-1298A8C6D83D"],
 "identifierType": "SUPPORTER_ID"

}
Get specific supporters by email address
{"payload":{
"identifiers":[
 "email1@gmail.com",
"email2@gmail.com",
"email2@gmail.com"],
 "identifierType": "EMAIL_ADDESSS"}
}
Get specific supporters by
email external id
{"payload":{
"identifiers":[
  "extId1",
"extId2",
"extId3"],
  "identifierType": "EXTERNAL_ID"}
}

 

Response Body Format

The response body format is as follows.  All results, regardless of types will have the following information. Details for each activity type as well as these fields can be found detail sections of this document.

Example Request

{
  "payload":{
          "count":1,
          "offset":0,
          "total':1200,
          "supporters":[
                   {"supporterId":"1f4d3ee4-af08-42bb-8ca2-50fc232e7b40",
                    "result":"FOUND"   
                    "title":"Mr",
                    "firstName":"John",
                    "middleName":"James",
                    "lastName":"Smith",
                    "suffix":"Jr.",
                    "dateOfBirth":"2016-05-27T04:00:00.000Z",
                    "gender":"MALE",
                    "createdDate":"2016-05-27T14:02:10.780Z",
                    "lastModified":"2016-05-27T14:02:10.809Z",
                    "externalSystemId":"96548",
                    "address":{
                         "line1":"123 Main St",
                         "line2":"Suite 200",
                         "city":"Anytown",
                         "state":"NY",
                         "postalCode":"10001",
                         "county":"New York",
                         "country":"US"},
                  "contacts":[
                       {"type":"CELL_PHONE","value":"555-555-5555"},
                       {"type":"WORK_PHONE","value":"555-555-5555"},
                       {"type":"HOME_PHONE","value":"555-555-5555"},
                       {"type":"EMAIL","value":"email@mail.com","status":"OPT_IN"}
                 ],
                 "customFieldValues":[
                          {"fieldId":"aa90e308-c2e6-48d8-834a-e9a516fa0a31","name":"Custom field 2","value":"Value","type":"STRING"},
                          {"fieldId":"b92c4b69-f927-4224-85a2-edace8ffeff7","name":"Custom field 1","value":"Value","type":"STRING"},
                          {"fieldId":"c424ab53-7e5f-4b15-8c6c-fd04bab20497","name":"Custom field 0","value":"Value","type":"STRING"}]
              }] 

         }
}
Have more questions? Submit a request
Powered by Zendesk