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

You can add or update only integrated segments. An integrated segment is a segment that was initially added via this API.

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
totalMembers	Count of members assigned in the segment	integer value	no read-only value returned only if IncludeMemberCounts is not set to false

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 segment 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
includeMemberCounts	payload	Flag to include the counts of supporters included in each segment. Value can be true/false with the default being false. Setting false will increase call performance

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":"",
                  "type":"INTEGRATED",
                  "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 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

{
  "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"}]

         }

}

In This Article:

Engage API: Segment Data

In This Article:

Segment Data Detail

Assigning Supporters to Segments

Comments