In This Article:

    API for Activity Data

    In This Article:

      Activity Data Overview

      Activities represent the interaction of supporters with published forms.  At this time, supporters can interact with the following types of forms: 

      Activity Description
      SUBSCRIPTION_MANAGEMENT

      Make changes to email interests as well as globally opting out

      SUBSCRIBE Signup to become a supporter of your organization
      FUNDRAISE Make a donation to your organization
      PETITION Sign a petition to show their support for your organization's cause
      TARGETED_LETTER Send a letter to political leaders within their district
      TICKETED_EVENT Attend an event, or donate to the cause of an event

      Acquiring Activities

      Activities can be acquired from Salsa Engage in one of two ways

      1. By providing a list of existing activity UUIDS
      2. By providing a date range which to search.  In addition a specific type or types of activity can be included within the request

      Both the number of items provided and the number of items requested will count towards the rate limit for the token.

      The end point to invoke for searching activities is:

      POST  /api/integration/ext/v1/activities/search

      • include your API token as a HTTP header parameter named: authToken
      • include your search criteria within the body of the request as well formatted JSON

      Request Body Format

      {
      
        "header" :{"refId":"optionalId"}, 
      
        "payload":{
               "modifiedFrom":"2016-05-26T11:49:24.905Z",
               "type":"SUBSCRIPTION_MANAGEMENT",
               "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.
      activityIds payload List of activity ids to retrieve - 36 character UUID
      note that the modifiedFrom and modifiedTo parameters can not be provided when activity ids are provided 
      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
      type payload

      The types of activities to search for - this is an optional parameter that is only applicable for retrieving activities using the modifiedFrom and modifiedTo parameters.

      Value must be one of the following if provided:

      • SUBSCRIPTION_MANAGEMENT
      • SUBSCRIBE
      • FUNDRAISE
      • PETITION
      • TARGETED_LETTER
      • TICKETED_EVENT

       

      Request Example

      Description Body
      Get any activities since a specific date
      {"payload":{
      "modifiedFrom":"2016-05-26T11:49:24.905Z",
      "offset":0,
      "count":20}
      }
      Get specific activities since a specific date
      {"payload":{
      "modifiedFrom":"2016-05-26T11:49:24.905Z",
      "type":"SUBSCRIPTION_MANAGEMENT",
      "offset":0,
      "count":20}
      }
      Get activities 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 activities by id
      {"payload":{
      "activityIds":[
       "0B99B409-E56D-4530-A226-474C61461DB4",
      "7EEEED4B-40A4-4FCE-B107-AE643AD1D926",
      "9AC97182-671C-4364-B69A-1298A8C6D83D"]}
      }


      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 Response

      {
       "header":{
          "processingTime":196,
          "serverId":"127.0.0.1"},
          "payload":{
               "total":1,
               "offset":0,
               "count":1,
               "activities":[
                      {"activityType":"SUBSCRIBE",
                       "activityId":"ae41ff3a-3820-4085-9c90-5a0154ccd624",
                       "activityFormName": "Activity Name",
                       "activityFormId":"8ec2afb6-bc8a-4214-be62-6d1035f4fe75",
                       "supporterId":"85289038-7880-4a55-8f42-15741899284e",
                       "activityDate":"2016-05-26T11:49:24.913Z",
                       "activityType":"SUBSCRIPTION_MANAGEMENT",
                       "lastModified":"2016-05-26T11:49:24.916Z"}],
               }
      }

      Base Activity Data

      All Activities returned from the API have the same structured base information.  

      ActivityType - ALL

      • Note that this is the only detail returned for SUBSCRIBE or SUBSCRIPTION_MANAGEMENT types

       

      Field location Meaning detail
      processingTime header Time in mills this request took to process Number
      serverId header Id of the server that performed the processing 64 character
      total payload Total number of results that matched the search criteria Number
      offset payload Starting count which activities to retrieve - pagination supporter Number
      count payload Number of items returned in the request Number
      activities payload List of activities returned.  
      activityId activity The unique id of this activity 36 character UUID
      activityFormName activity The name of the activity defined within Salsa Engage (E.g 'Support our cause') 64 character
      Not provided for  SUBSCRIPTION_MANAGEMENT activities
      activityFormId activity The unique id of the for - this can be use for correlating all activities for a specific form 36 character UUID
      Not provided for  SUBSCRIPTION_MANAGEMENT activities 
      supporterId activity The id of the supporter within Salsa Engage that this activity belongs to 36 character UUID
      activityDate activity Date which the activity occured ISO_8601 formatted String with a GMT timezone
      activityType activity The type of the activity

      Will be one of

      • SUBSCRIPTION_MANAGEMENT
      • SUBSCRIBE
      • FUNDRAISE
      • PETITION
      • TARGETED_LETTER
      • TICKETED_EVENT

       

      lastModified payload

      Last date/time this activity was modified. Activities such as donations and ticketed events may be modified after their initial submission. Reason for the modifications is the following:

      • New transactions for a recurring donation
      • Refunding of a donation
      • Refunding of an event ticket
      • Updates to event ticket attendee information
      • Updates to questions for an event ticket 
      ISO_8601 formatted String with a GMT timezone

      Example Return

      {
       "header":{
          "processingTime":196,
          "serverId":"SERVER_ID"},
          "payload":{
               "total":1,
               "offset":0,
               "count":1,
               "activities":[
                      {"activityType":"SUBSCRIBE",
                       "activityId":"ae41ff3a-3820-4085-9c90-5a0154ccd624",
                       "activityFormName":
                       "Activity Name",
                       "activityFormId":"8ec2afb6-bc8a-4214-be62-6d1035f4fe75",
                       "supporterId":"85289038-7880-4a55-8f42-15741899284e",
                       "activityDate":"2016-05-26T11:49:24.913Z",
                       "activityType":"SUBSCRIPTION_MANAGEMENT",
                       "lastModified":"2016-05-26T11:49:24.916Z"}],
               }
      }

      Fundraising Activity Data

      ActivityType - FUNDRAISE

      There are two main components of the Fundraise Detail:

      • The meta-data of the donation which includes amounts, recurring detail, status, and other information
      • The individual transactions of the intent - which would include transactions for recurring donations, refunds, and cancellations

      In addition to the Base Detail, the following will be returned: 

      Field Description Detail
      donationId Unique id of the donation 36 character UUID
      totalReceivedAmount Total amount that has been received for this donation.

      Decimal

      Note that this amount reflect the true captured value of the donation after evaluating all charges and refunds

      oneTimeAmount Amount of the one time donation

      Decimal

      • This amount will not be updated due to refunds
           
       donationType  Type of donation that was made

      Will be either ONE_TIME or RECURRING 

      recurringInterval  The interval which subsequent charges will be made Will be either MONTHLY or YEARLY
      recurringAmount Amount of the recurring donation charge

      Decimal

      recurringCount  Number of recurring charges to date  Number 
      recurringTransactionId The initial transaction id of the recurring donation  32 characters 
       recurringStart Start date of the recurring transaction ISO_8601 formatted String with a GMT timezone
       recurringEnd End date of the recurring transaction  ISO_8601 formatted String with a GMT timezone
      accountType Type of the account used to make the donation Will be either CREDIT_CARD or E_ECHECK
      accountNumber Masked account number 32 characters. Only the last 4 readable
      accountExpiration Expiration date of the accountNumber ISO_8601 formatted String with a GMT timezone
      accountProvider Provider of the account 64 characters
      paymentProcessorName Name of the Salsa Engage payment gateway configuration 64 characters
      fundName Name of the fund associated with the donation 128 characters
      fundGLCode GL code of the fund 32 characters
      designation Fund designation 128 characters
      dedicationType Type of dedication for this donation

      Will be one of:

      • NONE
      • IN_HONOR_OF
      • IN_MEMORY_OF

      dedication Details of the dedication Blob of text
      notify Details of whom to notify about this donation Blob of text
      transactions List of transactions that have occurred for this donation Array of Transaction objects - there will always be at least 1
      wasImported Flag to indicate if the donation was imported into Salsa Engage and did not
      come in through an activity form 
      True or False


      Transaction Object

      Field Description Detail
      transactionId Unique id of the transaction 36 character UUID
      relatedTransactionId Id of another transaction

      A related transaction ID will exist for charges that have been refunded.
      This the relatedTransactionId for a refunded charge will point to the transaction
      that represents the refund. Additionally, the  relatedTransactionId on the refund
      will like to the charge.

      reason Represents the reason for the transaction Will be one of DONATION or EVENT_TICKET
      reasonId Id of the item this transaction occurred.

      36 character UUID

        • Only applicable if the reason is not DONATION
      date Date of the transaction

      ISO_8601 formatted String with a GMT timezone

      type Type of the transaction

      Will be one of

      • CHARGE - funds captured
      • REFUND - funds refunded
      • CANCEL - recurring donation was cancelled
      • COMPLETE - recurring donation completed
      amount Amount of the transaction

      Decimal

      • Only applicable for types of CHARGE or REFUND
       deductibleAmount  Amount that was configured to be deductible Decimal
       feesPaid Any fees which the supporter chose to pay in addition to the donation Decimal 
       gatewayTransactionId  Transaction Id returned by the payment gateway 32 characters 
      gatewayAuthorizationCode   Authorization Id returned by the payment gateway 32 characters 


      One Time Donation Example

      {
       "header":{"processingTime":34,"serverId":"serverId"},
       "payload":{"total":1,"offset":0,count="1",
                 activities":[
                          {"activityId":"3efeff36-8aa9-42a3-95af-e4f51e60a35d",
                           "activityFormName":"Activity Name",
                           "activityFormId":"a14064a8-2522-4ca8-b5c5-49b91dac2eed",
                           "supporterId":"75d4b7c7-b3b2-4977-9b39-1036cf7a7798",
                           "activityDate":"2016-05-26T13:41:13.558Z",
                           "activityType":"FUNDRAISE",
                           "lastModified":"2016-05-26T13:41:13.559Z",
                           "donationId":"42513445-0c00-4a2b-b391-6dd0cac7243b",
                           "totalReceivedAmount":20.00,
                           "oneTimeAmount":20.0,
                           "donationType":"ONE_TIME",
                           "accountType":"CREDIT_CARD",
                           "accountNumber":"xxxxxxxxxxxx1111",
                           "accountExpiration":"2016-05-26T04:00:00.000Z",
                           "accountProvider":"Visa",
                           "paymentProcessorName":"processor name",
                           "fundName":"fund name",
                           "fundGLCode":"598c",
                           "designation":"Lighting",
                           "dedicationType":"IN_HONOR_OF",
                           "dedication":"dedication",
                           "notify":"notify",
                           "transactions":[{
                                    "transactionId":"1d604c86-f703-4a5c-801a-41de6c3d36aa",
                                    "type":"CHARGE",
                                    "reason":"DONATION",
                                    "date":"2016-05-26T13:41:13.563Z",
                                    "amount":20.0,"deductibleAmount":20.0,
                                    "feesPaid":0.0,
                                    "gatewayTransactionId":"8375290456","gatewayAuthorizationCode":"AUTH"}]
                     }
               ]
           }
        }

      Recurring Donation Example

      {
       "header":{"processingTime":34,"serverId":"serverId"},
       "payload":{"total":1,"offset":0,count="1",
                 activities":[
                          {"activityId":"3efeff36-8aa9-42a3-95af-e4f51e60a35d",
                           "activityFormName":"Activity Name",
                           "activityFormId":"a14064a8-2522-4ca8-b5c5-49b91dac2eed",
                           "supporterId":"75d4b7c7-b3b2-4977-9b39-1036cf7a7798",
                           "activityDate":"2016-05-26T13:41:13.558Z",
                           "activityType":"FUNDRAISE",
                           "lastModified":"2016-05-26T13:41:13.559Z",
                           "donationId":"42513445-0c00-4a2b-b391-6dd0cac7243b",
                           "totalReceivedAmount":20.00,
                           "recurringAmount":20.0,
                           "donationType":"RECURRING",
                           "recurringInterval":"MONTHLY",
                           "recurringCount":2,
                           "recurringTransactionId":"8375290456",
                           "recurringStart":"2016-05-26T04:00:00.000Z",
                           "recurringEnd":"2016-08-26T04:00:00.000Z",
                           "accountType":"CREDIT_CARD",
                           "accountNumber":"xxxxxxxxxxxx1111",
                           "accountExpiration":"2016-05-26T04:00:00.000Z",
                           "accountProvider":"Visa",
                           "paymentProcessorName":"processor name",
                           "fundName":"fund name",
                           "fundGLCode":"598c",
                           "designation":"Lighting",
                           "dedicationType":"IN_HONOR_OF",
                           "dedication":"dedication",
                           "notify":"notify",
                           "transactions":[{
                                    "transactionId":"1d604c86-f703-4a5c-801a-41de6c3d36aa",
                                    "type":"CHARGE",
                                    "reason":"DONATION",
                                    "date":"2016-05-26T13:41:13.563Z",
                                    "amount":20.0,"deductibleAmount":20.0,
                                    "feesPaid":0.0,
                                    "gatewayTransactionId":"8375290456","gatewayAuthorizationCode":"AUTH"}]
                     }
               ]
           }
        }

      Petition Activity Detail

      ActivityType - PETITION

      In addition to the Base Detail, the following will be returned : 

      Feild Description Detail
      comment Comment left by the signer of the petition No strict limit on the size of the comment - it's advised to store within a text field
      moderationState The current comment display setting within Salsa Engage

      Will be one of:

      • DISPLAY
      • DONT_DISPLAY
      • PENDING

      Only provided if there was a comment

      displaySignaturePublicly Flag to indicate if the signer chose to show their signature Will be either True or False
      displayCommentPublicly Flag to indicate if the signer chose to show their comment.

      Will be either True or False

      Only provided if there was a comment


      Petition Example

      {
          "header":{"processingTime":26,"serverId":"serverId"},
          "payload":{
               "total":1,"offset":0,"count":1,
               "activities":[
                     {"activityId":"de5654fa-802e-4831-a7da-760c4c2e9dc9",
                      "activityFormName":"Activity Name",
                      "activityFormId":"eb67c422-de68-40ef-ac93-6b5cd87dc4d2",
                      "supporterId":"71f6c860-7bcd-4872-aeb5-bbf1a950c00c",
                      "activityDate":"2016-05-26T14:00:57.649Z",
                      "activityType":"PETITION",
                      "lastModified":"2016-05-26T14:00:57.650Z",
                      "comment":"I supporter this cause",
                      "moderationState":"PENDING",
                      "displaySignaturePublicly":true,
                      "displayCommentPublicly":true}
                 ]
           }
      }

      Targeted Letter Activity Data

      ActivityType - TARGETED_LETTER

      There are two main components of the Targeted Letter detail:

      • Letters
      • Targets that received the letter

      The returned payload will provide this information within a hierarchical structure that starts with the letters attribute of the payload.

      In addition to the Base Detail, the following will be returned: 

      Field Description Detail
      letters Contains the list of letters that were send Array of Letter objects, and there will always be at least 1


      Letters Object

      Field Description Detail
      name Name of the letter 64 characters in length
      subject Subject of the letter 255 characters in length
      message Body of the letter Blob of text
      additionalComment Optional comment written by the supporter Blob of text
      messageWasModified Flag to indicate if the supporter modified the message Either True or False
      targets Contains the list of targets that were send that letter Array of Target objects and each letter will contain at least 1


      Targets Object

      Field Description Detail Optional
      targetId The unique ID of the target 36 character UUID false
      targetName Name of the target 64 characters false
      targetTitle Title of the Target 128 characters false
      politicalParty Poliical party of the target

      128 characters

      • Only applicable to US Federal, State, and County legislators
      true
      targetType Type of the target

      64 characters

      Will be one of

      • Federal Executive
      • Federal Senate
      • Federal House
      • State Executive
      • State Senate
      • State House
      • US County
      • US Municipality
      • Custom Target
      false
      state State which the target resides Full state name true
      districtId District Id of the target 32 characters true
      districtName District Name 128 Characters true
      role The role of the target 128 Characters true
      department The department of the target 128 Characters true
      sentEmail Sent an email to the target boolean false
      sentFacebook Post to target's Facebook page boolean false
      sentTwitter Post to target's Twitter page boolean  false
      madeCall Called the target boolean  false
      callDurationSeconds Number of seconds the user spoke to the target integer  0
      callResult Result of call

      Will be one of

      • BUSY
      • FAILED
      • COMPLETED
      • CANCELLED
      • NO_ANSWER
      • MACHINE
      • OVER_BUDGET
      • SKIPPED
      • NO_CALL
       

       

      Targeted Letter Example Output

      {
             "header":{"processingTime":26,"serverId":"serverId"},
             "payload":{
                         "total":1,"offset":0,"count":1,
                         activities":[{"activityId":"5b566e5b-ed17-473e-ad82-f5998baece83",
                              "activityFormName":"Activity Name",
                              "activityFormId":"a88e7431-2afe-4e01-86e7-951465ace7e8",
                              "supporterId":"3bf7f4bb-7f9d-4a10-b90e-43ed4a2ab807",
                              "activityDate":"2016-05-26T14:00:57.716Z",
                              "activityType":"TARGETED_LETTER",
                              "lastModified":"2016-05-26T14:00:57.717Z",
                              "letters":[{"name":"Letter 1", "subject":"subject", "message":"message", "additionalComment":"additionalComment",
                                              "subjectWasModified":false,"messageWasModified":true,
                                              "targets":[{"targetId":"6c4da70a-3e4c-4d3d-b757-bcc20bcc2570","targetName":"target name",
                                                              "targetTitle":"target title","politicalParty":"party", "targetType":"target type","state":"New York",
                                                              "districtId":"districtId","districtName":"district name","role":"role","sentEmail":"false","sentFacebook":"false"
      , "sentFacebook":"false","sentTwitter":"false","madeCall":"true", "callDurationSeconds":"10","callResult":"COMPLETED"}]

                                            }]
                       }]
             }
      }

      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.