API - 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"}

                   ]

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