In This Article:

    API for Supporter Data

    In This Article:

      Overview

      The API provides the ability you 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.

      Method End Point Detail
      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}
      
      }
      Parameter Location Description
      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

      Description Body
      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"}]
                    }] 
      
               }

      Supporter Detail Data

      The following sections detail the supporter details, validation rules, and what is required when adding or updating a supporter

      Supporter Census Object

      Field Description Detail Required
      supporterId Unique id of the supporter 36 character UUID required for Update and Delete
      title Title of the supporter 36 characters no
      firstName Name of the supporter 36 characters no
      middleName Middle name of the supporter 36 characters no
      lastName Last name of the supporter 100 characters no
      suffix Suffix of the supporter 16 characters no
      dateOfBirth Date of birth of the supporter ISO_8601 formatted String with a GMT timezone no
      gender Gender of the support

      Must be one of

      • FEMALE
      • MALE
      • OTHER
      no
      externalSystemId Caller provided Id 100 characters no
      createdDate Date the supporter was created in Salsa Engage ISO_8601 formatted String with a GMT timezone not updateable
      lastModifiedDate Date the supporter was last modified in Salsa Engage ISO_8601 formatted String with a GMT timezone not updateable
      address The address of the supporter See Address Object no
      contacts Various contacts of the supporter List of contacts. See Contacts Object

      Yes - email is a required contact.

      Contacts are limited to 1 per type

      customFieldValues Various custom fields of the supporter List of custom fields. See Custom Field Object no
      result Constant to indicate state of the operation on the supporter.
      The value provided is contextual to the operation requested
      (E.g. delete, update, search).  

      Will be one of:

      • ADDED
      • UPDATED
      • DELETED
      • FOUND
      • NOT_FOUND
      • VALIDATION_ERROR
      • SYSTEM_ERROR

       

      not updateable


      Address Object

      Field Description Detail Required
      addressLine1 Line 1 of the address 128 charachters no
      addressLine2 Line 2 of the address 128 charachters no
      city City 64 characters no
      state State 2 character state code no
      postalCode Postal Code 10 characters no
      county County 64 characters no
      country Country 2 character country code no
      federalDistrict US Federal House District 16 characters not updateable
      stateHouseDistrict US State House District 16 characters not updateable
      stateSenateDistrict US State Senate District 16 characters not updateable
      countyDistrict US County District 16 characters not updateable
      municipalityDistrict US Municipality District 32 characters not updateable
      lattitude Lattitude Floating point number not updateable
      longitude Longitude Floating point number not updateable


      Contact Object

      One of each type of contact can be managed with the supporter.  
      An email contact is required for a supporter

      Field Description Detail Required
      type The type of contact

      Must be one of

      • EMAIL
      • HOME_PHONE
      • CELL_PHONE
      • WORK_PHONE
      • FACEBOOK_ID
      • TWITTER_ID
      • LINKEDIN_ID

      yes

       

      value Value for the contact Must be a valid email address for an email contact yes
      status Status of the contact

      Valid only for email contacts - ignored for others
      Must be one of

      • OPT_IN
      • OPT_OUT
      • HARD_BOUNCE

      These status codes relate to the experience of sending
      email to the supporter. The API will allow you to specify
      the status during an add or an update

      No.

      If not provided for new supporters the email status
      will default to OPT_IN.

      If not provided for an update to a supporter, no changes will be
      made to the status.

      The above applies to email contacts only.
       

       

      Custom Fields

      Salsa Engage provides the ability for you to configure custom fields.  The API can then be used for the purpose of syncing data into those custom fields and/or acquire the data currently set.

      The API does not provide the ability to create the custom field directly, custom fields must first be created within Salsa Engage.  Once created, the name(or id) and the value of the  field specific to a supporter can be included in supporter add or update calls.

      Field Description Detail Required
      fieldId

      Unique ID of the custom
      field

      36 character UUID no - can be provided in lieu of the name
      when setting the value of a custom field for
      a specific supporter 
      name Name of the custom field 64 characters no - can be provided in lieu of the fieldId. If the field
      id is not provided, then the system will attempt to identify the custom
      field by name.  
      value Value of the custom field This is dependent on how the custom field was configured within Salsa Engage. Salsa Engage provides a robust set of rules that can be configured to specify type, max length, range, etc. Provided values will be validated against these rules during an update, and an appropriate validation message will be returned if the value doesn't meet the criteria of the rules or if the custom field could not be found by name or id 

       

      Adding and Updating Supporters

      Adding as well as updating supporters is performed against the following endpoint

      PUT  /api//integration/ext/v1/supporters

      • You must include your api token with within an HTTP header parameter named authToken

      The following is required for each supporter within the payload

      • An EMAIL contact with a valid email address
      • A Salsa Engage supporterId if the intent is to update the supporter

      Supporters that are included within the payload that do not have a supporterId UUID will be attempted to be added into the system. Before doing so, the system will first attempt to find the user within the your organization by email address. If a user matching the email address is found, then an update will be performed. Salsa Engage does not allow more that one person to have the same email address.

      When additions or updates are processed by the system, validation of the fields will be performed to ensure they are the correct constants, or they don't exceed the maximum length.   If any field fails validation, then the result attribute of that supporter will be updated to indicate so and error objects will
      be assigned to the object that had the problem.  

      When the call to add or update completes, the resulting payload will include all of the data that was sent within the call. Each supporter within the call will have a decorated result attribute to indicate the result of the operation.  For adds or updates, these values will  be:

      • ADDED - the provided supporter was added to the system
      • UPDATED - the provided supporter was updated
      • VALIDATION_ERROR - if one or more objects for the supporter has validation errors with the provided data
      • SYSTEM_ERROR - if an unrecoverable occurs on the Salsa Engage System
      • NOT_FOUND - if the id provided with the supporter did not exist within the system

      Partial Updates

      At this time, the API does not support partial updates of a specific object. If an address is provided with a supporter, all fields of the address will be updated - including nulls, empty strings.

      However, not all objects need to be provided within a supporter call. If you desire to just update the census information of a supporter, then you only need to provide that object for each supporter- but you must provide the supporterId.  

      Supporter Update Request Example

      { 
      
      "payload":{"supporters":[
      
                          // adding a supporter
      
                         { "title":"Mr",
                          "firstName":"John", "middleName":"James","lastName":"Smith","suffix":"Jr.","dateOfBirth":"2016-05-27T04:00:00.000Z","gender":"MALE", "externalSystemId":"96548",
                          "address":{  "line1":"123 Main St", "line2":"Suite 200", "city":"Anytown", "state":"NY","postalCode":"10001","county":"New York","country":"US"},
                          "contacts":[{"type":"EMAIL","value":"email@mail.com","status":"OPT_IN"},
                       
                         // updating a supporter
                        {"supporterId":"1f4d3ee4-af08-42bb-8ca2-50fc232e7b40","title":"Mr",
                          "firstName":"John", "middleName":"James","lastName":"Smith","suffix":"Jr.","dateOfBirth":"2016-05-27T04:00:00.000Z","gender":"MALE", "externalSystemId":"96548",
                          "address":{  "line1":"123 Main St", "line2":"Suite 200", "city":"Anytown", "state":"NY","postalCode":"10001","county":"New York","country":"US"},
                          "contacts":[{"type":"EMAIL","value":"email@mail.com","status":"OPT_IN"}]
      
       
      
                         // updating a supporter - failed update, not found.
                        {"supporterId":"00000000-af08-42bb-8ca2-50fc232e7b40","title":"Mr",
                          "firstName":"John", "middleName":"James","lastName":"Smith","suffix":"Jr.","dateOfBirth":"2016-05-27T04:00:00.000Z","gender":"MALE", "externalSystemId":"96548",
                          "address":{  "line1":"123 Main St", "line2":"Suite 200", "city":"Anytown", "state":"NY","postalCode":"10001","county":"New York","country":"US"},
                          "contacts":[{"type":"EMAIL","value":"email@mail.com","status":"OPT_IN"}]
      
                         // validation failure
                        {"supporterId":"1f4d3ee4-af08-42bb-8ca2-50fc232e7b40","title":"Mr",
                          "firstName":"John", "middleName":"James","lastName":"Smith","suffix":"Jr.","dateOfBirth":"2016-05-27T04:00:00.000Z","gender":"MALE", "externalSystemId":"96548",
                          "contacts":[{"type":"EMAIL","value":"bad@email@bad.com","status":"OPT_IN"}]
      
                ]}
          }
      
      }

      Response

      { 
      
      "payload":{"supporters":[
      
                          // adding a supporter
                         {"supporterId":"1f4d3ee4-af08-42bb-8ca2-50fc232e7b40"  result="ADDED", "title":"Mr",
                          "firstName":"John", "middleName":"James","lastName":"Smith","suffix":"Jr.","dateOfBirth":"2016-05-27T04:00:00.000Z","gender":"MALE", "externalSystemId":"96548",
                          "address":{  "line1":"123 Main St", "line2":"Suite 200", "city":"Anytown", "state":"NY","postalCode":"10001","county":"New York","country":"US"},
                          "contacts":[{"type":"EMAIL","value":"email@mail.com","status":"OPT_IN"},
                        
                         // updating a supporter
                        {"supporterId":"1f4d3ee4-af08-42bb-8ca2-50fc232e7b40",  result="UPDATED", "title":"Mr",
                          "firstName":"John", "middleName":"James","lastName":"Smith","suffix":"Jr.","dateOfBirth":"2016-05-27T04:00:00.000Z","gender":"MALE", "externalSystemId":"96548",
                          "address":{  "line1":"123 Main St", "line2":"Suite 200", "city":"Anytown", "state":"NY","postalCode":"10001","county":"New York","country":"US"},
                          "contacts":[{"type":"EMAIL","value":"email@mail.com","status":"OPT_IN"}]
      
       
      
                         // updating a supporter - failed update, not found.
                        {"supporterId":"00000000-af08-42bb-8ca2-50fc232e7b40",  result="NOT_FOUND",  "title":"Mr",
                          "firstName":"John", "middleName":"James","lastName":"Smith","suffix":"Jr.","dateOfBirth":"2016-05-27T04:00:00.000Z","gender":"MALE", "externalSystemId":"96548",
                          "address":{  "line1":"123 Main St", "line2":"Suite 200", "city":"Anytown", "state":"NY","postalCode":"10001","county":"New York","country":"US"},
                          "contacts":[{"type":"EMAIL","value":"email@mail.com","status":"OPT_IN"}]
      
                         // validation failure
                        {"supporterId":"1f4d3ee4-af08-42bb-8ca2-50fc232e7b40",  result="VALIDATION_ERROR",  "title":"Mr",
                          "firstName":"John", "middleName":"James","lastName":"Smith","suffix":"Jr.","dateOfBirth":"2016-05-27T04:00:00.000Z","gender":"MALE", "externalSystemId":"96548",
                          "contacts":[{"type":"EMAIL","value":"bad@email@bad.com","status":"OPT_IN",
                                            "errors":[{"id":"4cdce4a9-4197-433a-8ebe-5550b7bcb02d","code":2008,"message":"The email provided is not of correct format","details":"Domain contains illegal character","fieldName":"value"}]}]
      
                  }]
            }
      }

      Deleting Supporters

      Deleting supporters is performed against the following endpoint

      DELETE  /api//integration/ext/v1/supporters

      • You must include your api token with within an HTTP header parameter named authToken

      As with updating supporters, deleting a supporters requires the supporterId to be provided within the payload. It should also be understood that a supporter deletion can not be un-done

      Delete Request Example

      { 
      
      "payload":{"supporters":[
                              {"supporterId":"4cdce4a9-4197-433a-8ebe-5550b7bcb02d"},
                              {"supporterId":"1f4d3ee4-af08-42bb-8ca2-50fc232e7b40"}
      
                       ]
                }
        }

      Response

      { 
      
      "payload":{"supporters":[
                              {"supporterId":"4cdce4a9-4197-433a-8ebe-5550b7bcb02d", result="NOT_FOUND"},
                              {"supporterId":"1f4d3ee4-af08-42bb-8ca2-50fc232e7b40", result="DELETED"}
      
                         ]
      
                  }
      }
      Was this article helpful?
      0 out of 0 found this helpful
      Have more questions? Submit a request

      Comments

      0 comments

      Please sign in to leave a comment.