API - Groups Data Detail

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

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

 

MethodEnd PointDetail
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:

FieldDescriptionDetailRequired
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
   }

}

 

ParameterLocationDescription 
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

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

         }

}
Have more questions? Submit a request
Powered by Zendesk