In This Article:

    API for Segment Data

    In This Article:

      Segment Data Detail

      Segments provide the ability for you to logically group supporters and then use the grouping to target supporters in an email blast or export. The following endpoints provide the abilities to manage segments as well as the supporters who are assigned to any segment.

      Note: Segments that are manageable via the API are categorized within Salsa Engage as CRM segments. Attempting to manage a segment other than a CRM segment will result in an HTTP 405 (Method not allowed) error. 

       

      Method End Point Detail
      POST /api/integration/ext/v1/segments/search

      Provides the ability to search for segment by:

      • External ID
      • Salsa Engage ID
      PUT /api/integration/ext/v1/segments Adds or updates the provided list of segments
      DELETE /api/integration/ext/v1/segments Deletes the provided list of segments

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

      Adding/Updating Segments

      Adding as well as updating supporters is performed via the following endpoint:

       PUT  /api//integration/ext/v1/segments

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

      The following table details the attributes of a segment:

      Field Description Detail Required
      segmentId Unique id of the segment 36 character UUID Optional for Create, required for Update and Delete
      name Name of the segment 64 characters yes - must be unique
      description Description of the segment 256 characters no
      externalSystemId External system id of the segment 100 characters no

      result

      Result of an operation on a segment 16 characters

      Will be one of:

      • ADDED - the provided segment was added to the system
      • UPDATED - the provided segment was updated
      • VALIDATION_ERROR - if a validation error exists for the provided data
      • SYSTEM_ERROR - if an unrecoverable occurs on the Salsa Engage System
      • NOT_FOUND - if the id provided with the segment did not exist within the system
      • NOT_ALLOWED - if the segment represented by the provided id is not allowed to be modified via the API

      Segments must be named uniquely within the system.   When a segment is added or updated, the system will ensure the operation doesn't cause more than one segment have the same name. If the operation will cause more than one segment to have the same name, then a validation error will be reported on the provided segment and no operation will be performed.

      Create/Update Request Example

       {
           "payload":{
                     "segments":[
                           {"segmentId":"11454266-a9c8-40af-8fab-4c0bdca44615","name":"segment1","description":"segment1","externalSystemIdId":"35467"},
                           {"name":"segment1","description":"duplicate named","externalSystemId":"99999"}
                    ]
            }
      }  

      Create/Update Response Example

      {
           "payload":{
                     "segments":[
                           {"segmentId":"11454266-a9c8-40af-8fab-4c0bdca44615",
                                "name":"segment1","description":"segment1","externalSystemId":"35467", "result":"UPDATED"}
                           {"name":"segment1","description":"duplicate named","externalSystemId":"99999","result":"VALIDATION_ERROR",
                                 "errors":[{"id":"dd04a987-0613-423d-9d79-4a8c27971ebe","code":2002,"message":"The field is not unique in the system","fieldName":"name"}]}
                    ]
            }
      }  

      Deleting Segments

      Deleting segments is performed against the following endpoint

      DELETE  /api//integration/ext/v1/segments

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

      As with updating segments, deleting a segments requires the segmentId to be provided within the payload.

      Delete Request Example

      { 
      
      "payload":{
               "segments":[{"segmentId":"11454266-a9c8-40af-8fab-4c0bdca44615"}]
          }
      }

      Delete Response Example

      {
            "payload":{
                    "segments":[
                            {"segmentId":"11454266-a9c8-40af-8fab-4c0bdca44615","result":"DELETED"}]
             }
      }

      Searching for Segments

      • /api//integration/ext/v1/segments/search

      Searching for segments can be performed by providing a list of either Salsa Engage ids or list of external ids. It should be understood that the provided ids must all be of the same type - passing a mix of ids is not supported.

      Request Body Format

      The request body format is as follows:

      {
      
        "header" :{"refId":"optionalId"}, 
      
        "payload":{
            "offset":0,"count":20
         }
      
      }
      Parameter Location Description  
      identifiers payload

      An optional list of Salsa Engage segment ids or external ids. If not provided,
      then all segments will be retrieved (using pagination). If a list of identifiers is provided, then the identifierType
      parameter must be provided and only the segments who match the provided identifier will be returned.

       
      identifierType payload

      Represents the type of identifier provided; must be one of:

      • SEGMENT_ID
      • EXTERNAL_ID
       
      offset payload Starting count at which to retrieve segments  
      count payload Number of segments to retrieve  


      Request Examples

      Description Body
      Get all segments
      {"payload":{ "offset":0,"count":20}}
      Get specific segments by Salsa Engage Id
      {"payload":{
       "identifierType" :  "SEGMENT_ID", 
      "identifiers":[
       "0B99B409-E56D-4530-A226-474C61461DB4",
       "7EEEED4B-40A4-4FCE-B107-AE643AD1D926",
       "9AC97182-671C-4364-B69A-1298A8C6D83D"]
      }}
      Get specific segments by External Id
      {"payload":{
      "identifierType" :  "EXTERNAL_ID",
      "identifiers":[
       "98564",
      "98565,
      "98563"]
      }}


      Response Body Format

      The response body format is as follows for all results:

      {
        "payload":{
                "count":1,
                "offset":0,
                "total':5,
                "segments":[{
                        "segmentId":"1b7458d0-e747-40fe-8e1e-5d7fad4241cb",
                        "name":"segment1",
                        "description":"",
                        "totalMembers":50,
                        "result":"FOUND",
                        "externalSystemId":"98564"},
                      {"segmentId":"69afe9fc-dcde-4533-92d6-cbf069008c30",
                       "name":"test2",
                       "description":"desc2",
                       "totalMembers":20,
                       "result":"FOUND",
                       "externalSystemId":"98565"},
                      {"result":"NOT_FOUND","externalSystemId":"98563"}]
      
               }
      
      }

      Assigning Supporters to Segments

      The following tables list the endpoints that can be used for viewing and modifying the segments that supporters are assigned.

      Method End Point Detail
      POST /api/integration/ext/v1/segments/members/search

      Paginate through all of the supporters assigned to the segment,
      or just those matching supporter ids provided in the request

      PUT /api/integration/ext/v1/segments/members Assign the provided supporter ids
      DELETE /api/integration/ext/v1/segments/members Remove the provided supporter ids

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

      Assigning supporters to a segment

      Assigning supporters to a segment is performed via the following endpoint

      PUT  /api//integration/ext/v1/segments/members

      • You must include your api token with within an HTTP header parameter named authToken
      Field Description Detail Required
      segmentId Unique id of the segment 36 character UUID yes

      supporterIds

      List of supporter Ids to assign to the segment 36 character UUID yes - supporters must exist within the system
      in order for them to be assigned.
      supporters List of supporters that were assigned to the segment.

      Complex Object with the following attributes

      • supporterId
      • result which will be one of:
        • ADDED
        • UPDATED
          NOT_FOUND 
      no - read-only response attribute

      Assignment Request Example

      {
         "payload":{
                 "segmentId":"88eb5a95-d3fa-4edb-a90c-a3599c2c1166",
                 "supporterIds":["b86cda64-9a7e-4186-8d9c-efd63e64bad2",
                                         "1e968fe6-a84c-4184-9cb2-42a8945f81f3",
                                         "ca9403cb-c160-4b49-912c-fc31fc22caf7"]
                 }
            }
      
      }

      Assignment Response Example

      {
           "payload":{
                     "supporters":[
                          {"supporterId":"b86cda64-9a7e-4186-8d9c-efd63e64bad2","result":"ADDED"},
                          {"supporterId":"1e968fe6-a84c-4184-9cb2-42a8945f81f3","result":"UPDATED"},
                          {"supporterId":"ca9403cb-c160-4b49-912c-fc31fc22caf7","result":"NOT_FOUND"}],
                         "count":3
              }
      }

      Deleting  supporters from a segment

      Removing a supporter from a segment is performed via the following endpoint

      DELETE  /api//integration/ext/v1/segments

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


      Delete Request Example

      {
          "payload":{
                 "segmentId":"cc1688b6-56ef-4db2-96d9-5526fdfed632",
                 "supporterIds":["9a0ae5f4-8458-4e79-96ae-d911e0428254","326d6fad-1fc6-4e02-bf23-e73b64496aa4",
                                         "7dc73fe1-375f-436b-8a4b-2ede6e5bda75","fd2b7184-0279-4de0-aec8-d25a4bd116f6",
                                         "2fc47803-425f-41b6-99d0-e613c2f4f5df"]
             }
      }


      Delete Response Example

      {
      
          "payload":{
                    "supporters":[{"supporterId":"326d6fad-1fc6-4e02-bf23-e73b64496aa4","result":"DELETED"},
                                         {"supporterId":"7dc73fe1-375f-436b-8a4b-2ede6e5bda75","result":"DELETED"},
                                         {"supporterId":"9a0ae5f4-8458-4e79-96ae-d911e0428254","result":"DELETED"},
                                         {"supporterId":"fd2b7184-0279-4de0-aec8-d25a4bd116f6","result":"NOT_FOUND"},
                                         {"supporterId":"2fc47803-425f-41b6-99d0-e613c2f4f5df","result":"NOT_FOUND"}
                    ],
                    "count":5
             }
      }

      Searching for supporters assigned to a segment

      • /api//integration/ext/v1/segments/search

      Searching for segment assignments can be performed by providing a list of either Salsa Online ids. If no ids are provided, then standard pagination will be performed.

      Request Body Format

      { 
      
      "payload":{
               "segmentId" : "11454266-a9c8-40af-8fab-4c0bdca44615",
                "supporterIds":["b86cda64-9a7e-4186-8d9c-efd63e64bad2",
                                         "1e968fe6-a84c-4184-9cb2-42a8945f81f3",
                                         "ca9403cb-c160-4b49-912c-fc31fc22caf7"]
          }
      }
      Parameter Location Description Required
      segmentId payload

      Id of the segment to search

      no
      supporterIds payload

      List of supporter Ids to search for

      yes
      offset payload Starting count at which to retrieve assignments no
      count payload Number of assignments to retrieve no - but if not provided, only the counts not the supporters will be returned
      total payload Total number of assignments that exist no - read-only attribute
      provided in the response


      Request Examples

      Description Body
      Get all segment assignments
      {"payload":{
      "segmentId" : "11454266-a9c8-40af-8fab-4c0bdca44615",
      "offset":0,
      "count":20
      }
      }
      Search for specific supporter assignments
      {"payload":{
      "segmentId" : "11454266-a9c8-40af-8fab-4c0bdca44615",
      "supporterIds":["b86cda64-9a7e-4186-8d9c-efd63e64bad2",
                             "1e968fe6-a84c-4184-9cb2-42a8945f81f3",
                             "ca9403cb-c160-4b49-912c-fc31fc22caf7"]
      "offset":0,
      "count":20
      }
      } 


      Response Body Format

      {
        "payload":{
                "count":2,
                "offset":0,
                "total':2,
                "supporters":[
                          {"supporterId":"326d6fad-1fc6-4e02-bf23-e73b64496aa4","title":"Mr","firstName":"John","lastName":"Smith","dateOfBirth":"2016-07-26T04:00:00.000Z",
                           "externalSystemId":"65249a1", ....[remaining details] ...., "result":"FOUND" },
                           {"supporterId":"326d6fad-1fc6-4e02-bf23-e73b64496aa4","result":"NOT_FOUND"}
                ]
           }
      }
       
      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.