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
   } 

}

Searching for supporters who have joined group X since Y date can be performed by providing a group id and a joined since date value as a parameters.

Request Body Format

The request body format is as follows:

{

  "header" :{"refId":"optionalId"}, 
  "payload":{
      "segmentId" : "299f0cf2-5f25-4ca2-b467-65b671b538f8", "joinedSince": "2019-03-21T08:27:50.157Z", "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
joinedSince	payload	An optional date value to get supporters that joined the group since the specified date. Provided value should be in this format "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"

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"] }}
Get segment's members by Salsa Engage Id that joined group since the provided date	{"payload":{ "segmentId" : "299f0cf2-5f25-4ca2-b467-65b671b538f8", "joinedSince": "2019-03-21T08:27:50.157Z"}}

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/members/search

segmentID is a required parameter. Perform a search for segments 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. If no ids are provided, then standard pagination will be performed.

Request Body Format

{

  "header" :{"refId":"optionalId"}, 

  "payload":{
      "segmentId" : "b72d1e3d-c811-411b-8b33-092278c80782",
      "offset":0,"count":20
   }

}

Parameter	Location	Description	Required
segmentId	payload	36 character UUID	yes
supporterIds	payload	An optional list of Salsa Engage supporter ids. If not provided, then all supporters will be retrieved (using pagination).	optional
offset	payload	Starting count at which to retrieve supporters	optional
count	payload	Number of supporters to retrieve	optional

Request Examples

Description

Body

Get all supporters for a segment

{"payload":{ "offset":0,"count":20,
 "segmentId":"0B99B409-E56D-4530-A226-474C61461DB4"}}

Get specific supporters by Salsa Engage Id

{"payload":{
 "segmentId" :  "0B99B409-E56D-4530-A226-474C61461DB4", 
"supporterIds":[
 "7EEEED4B-40A4-4FCE-B107-AE643AD1D926",
 "9AC97182-671C-4364-B69A-1298A8C6D83D"]
}}

Response Body Format

{
 "id": "f68c15bb-185e-4b1f-bbe0-a67033032c24",
 "timestamp": "2019-02-05T17:14:01.231Z",
 "header": {
 "processingTime": 199,
 "serverId": "prod-hqapp5.prod.ignite.net"
 },
 "payload": {
 "total": 7,
 "supporters": [
 {
 "readOnly": false,
 "supporterId": "60a3b3a8-06a4-434e-87b1-69232b319212",
 "firstName": "21sup5",
 "lastName": "21sup5",
 "createdDate": "2016-05-10T10:18:10.814Z",
 "lastModified": "2016-09-13T09:14:41.775Z",
 "address": {
 "addressLine1": "3814 Melancon Rd",
 "city": "Broussard",
 "state": "LA",
 "postalCode": "70518-8243",
 "county": "Iberia",
 "country": "US",
 "federalHouseDistrict": "LA03",
 "stateHouseDistrict": "LA048",
 "stateSenateDistrict": "LA022",
 "countyDistrict": "22045",
 "municipalityDistrict": "2204595707",
 "lattitude": 30.05617,
 "longitude": -91.9399,
 "status": "OptIn",
 "optInDate": "2016-05-10T10:18:10.820Z"
 },
 "contacts": [
 {
 "type": "EMAIL",
 "value": "21sup5.0bb16be1@mailosaur.in",
 "status": "HARD_BOUNCE",
 "optInDate": "2016-05-10T10:18:10.935Z",
 "optOutDate": "2016-09-13T09:14:41.000Z"
 }
 ],
 "customFieldValues": [],
 "result": "FOUND"
 },
 {
 "readOnly": false,
 "supporterId": "40daceb6-f9dc-4a70-b9aa-1e171ddc4bd5",
 "title": "Miss",
 "firstName": "sup3",
 "lastName": "sup3",
 "createdDate": "2016-05-10T09:58:17.545Z",
 "lastModified": "2016-09-13T09:14:41.730Z",
 "address": {
 "addressLine1": "10753 Blix St",
 "city": "North Hollywood",
 "state": "CA",
 "postalCode": "91602-3813",
 "county": "Los Angeles",
 "country": "US",
 "federalHouseDistrict": "CA30",
 "stateHouseDistrict": "CA046",
 "stateSenateDistrict": "CA018",
 "countyDistrict": "06037@CA_LAX_3",
 "municipalityDistrict": "0000644000@CA_LAX_2",
 "lattitude": 34.15692,
 "longitude": -118.36546,
 "status": "OptIn",
 "optInDate": "2016-05-10T09:58:17.550Z"
 },
 "contacts": [
 {
 "type": "HOME_PHONE",
 "value": "123-123-1234",
 "optInDate": "2016-05-10T09:58:17.560Z"
 },
 {
 "type": "EMAIL",
 "value": "sup213.0bb16be1@mailosaur.in",
 "status": "HARD_BOUNCE",
 "optInDate": "2016-05-10T09:58:17.598Z",
 "optOutDate": "2016-09-13T09:14:41.000Z"
 }
 ],
 "customFieldValues": [],
 "result": "FOUND"
 },
 {
 "readOnly": false,
 "supporterId": "0ca5443c-9245-4834-86bf-69f831bd6d87",
 "firstName": "sup212",
 "lastName": "sup212",
 "createdDate": "2016-05-10T09:57:02.567Z",
 "lastModified": "2016-09-13T09:02:35.136Z",
 "address": {
 "addressLine1": "3814 Melancon Rd",
 "city": "Broussard",
 "state": "LA",
 "postalCode": "70518-8243",
 "county": "Iberia",
 "country": "US",
 "federalHouseDistrict": "LA03",
 "stateHouseDistrict": "LA048",
 "stateSenateDistrict": "LA022",
 "countyDistrict": "22045",
 "municipalityDistrict": "2204595707",
 "lattitude": 30.05617,
 "longitude": -91.9399,
 "status": "OptIn",
 "optInDate": "2016-05-10T09:57:02.573Z"
 },
 "contacts": [
 {
 "type": "EMAIL",
 "value": "sup212.0bb16be1@mailosaur.in",
 "status": "HARD_BOUNCE",
 "optInDate": "2016-05-10T09:57:02.610Z",
 "optOutDate": "2016-09-13T09:02:35.000Z"
 }
 ],
 "customFieldValues": [],
 "result": "FOUND"
 },
 {
 "readOnly": false,
 "supporterId": "1288f1a6-c6e2-4efa-b1b4-307bf036690a",
 "title": "Mr",
 "firstName": "san21sup",
 "lastName": "san21sup",
 "createdDate": "2016-05-10T09:56:14.616Z",
 "lastModified": "2016-09-13T09:14:41.766Z",
 "address": {
 "addressLine1": "10753 Blix St",
 "city": "North Hollywood",
 "state": "CA",
 "postalCode": "91602-3813",
 "county": "Los Angeles",
 "country": "US",
 "federalHouseDistrict": "CA30",
 "stateHouseDistrict": "CA046",
 "stateSenateDistrict": "CA018",
 "countyDistrict": "06037@CA_LAX_3",
 "municipalityDistrict": "0000644000@CA_LAX_2",
 "lattitude": 34.15692,
 "longitude": -118.36546,
 "status": "OptIn",
 "optInDate": "2016-05-10T09:56:14.621Z"
 },
 "contacts": [
 {
 "type": "HOME_PHONE",
 "value": "123-123-1234",
 "optInDate": "2016-05-10T09:56:14.633Z"
 },
 {
 "type": "EMAIL",
 "value": "san21sup.0bb16be1@mailosaur.in",
 "status": "HARD_BOUNCE",
 "optInDate": "2016-05-10T09:56:14.672Z",
 "optOutDate": "2016-09-13T09:14:41.000Z"
 }
 ],
 "customFieldValues": [],
 "result": "FOUND"
 },
 {
 "readOnly": false,
 "supporterId": "320c4454-f950-4811-9308-8da9828112bc",
 "title": "Mrs",
 "firstName": "sup214",
 "lastName": "sup214",
 "createdDate": "2016-05-10T10:17:16.330Z",
 "lastModified": "2016-09-13T09:14:41.752Z",
 "address": {
 "addressLine1": "10753 Blix St",
 "city": "North Hollywood",
 "state": "CA",
 "postalCode": "91602-3813",
 "county": "Los Angeles",
 "country": "US",
 "federalHouseDistrict": "CA30",
 "stateHouseDistrict": "CA046",
 "stateSenateDistrict": "CA018",
 "countyDistrict": "06037@CA_LAX_3",
 "municipalityDistrict": "0000644000@CA_LAX_2",
 "lattitude": 34.15692,
 "longitude": -118.36546,
 "status": "OptIn",
 "optInDate": "2016-05-10T10:17:16.336Z"
 },
 "contacts": [
 {
 "type": "HOME_PHONE",
 "value": "123-123-1234",
 "optInDate": "2016-05-10T10:17:16.347Z"
 },
 {
 "type": "EMAIL",
 "value": "sup214.0bb16be1@mailosaur.in",
 "status": "HARD_BOUNCE",
 "optInDate": "2016-05-10T10:17:16.385Z",
 "optOutDate": "2016-09-13T09:14:41.000Z"
 }
 ],
 "customFieldValues": [],
 "result": "FOUND"
 },
 {
 "readOnly": false,
 "supporterId": "7f6f4846-83dd-46b8-b0e7-b79c17da1c75",
 "title": "Ms",
 "firstName": "tl2",
 "lastName": "tl2",
 "createdDate": "2016-05-10T16:41:04.659Z",
 "lastModified": "2016-09-13T09:14:41.722Z",
 "address": {
 "addressLine1": "10753 Blix St",
 "city": "North Hollywood",
 "state": "CA",
 "postalCode": "91602-3813",
 "county": "Los Angeles",
 "country": "US",
 "federalHouseDistrict": "CA30",
 "stateHouseDistrict": "CA046",
 "stateSenateDistrict": "CA018",
 "countyDistrict": "06037@CA_LAX_3",
 "municipalityDistrict": "0000644000@CA_LAX_2",
 "lattitude": 34.15692,
 "longitude": -118.36546,
 "status": "OptIn",
 "optInDate": "2016-05-10T16:41:04.663Z"
 },
 "contacts": [
 {
 "type": "HOME_PHONE",
 "value": "123-123-1234",
 "optInDate": "2016-05-10T16:41:04.670Z"
 },
 {
 "type": "EMAIL",
 "value": "tl2.3e41c646@mailosaur.in",
 "status": "HARD_BOUNCE",
 "optInDate": "2016-05-10T16:41:04.696Z",
 "optOutDate": "2016-09-13T09:14:41.000Z"
 }
 ],
 "customFieldValues": [],
 "result": "FOUND"
 },
 {
 "readOnly": false,
 "supporterId": "dd8abba4-dde0-4402-b910-2f3920e202ae",
 "title": "Miss",
 "firstName": "tl1",
 "lastName": "tl1",
 "createdDate": "2016-05-10T16:40:07.037Z",
 "lastModified": "2016-07-12T20:04:07.003Z",
 "address": {
 "addressLine1": "10753 Blix St",
 "city": "North Hollywood",
 "state": "CA",
 "postalCode": "91602-3813",
 "county": "Los Angeles",
 "country": "US",
 "federalHouseDistrict": "CA30",
 "stateHouseDistrict": "CA046",
 "stateSenateDistrict": "CA018",
 "countyDistrict": "06037@CA_LAX_3",
 "municipalityDistrict": "0000644000@CA_LAX_2",
 "lattitude": 34.15692,
 "longitude": -118.36546,
 "status": "OptIn",
 "optInDate": "2016-05-10T16:40:07.042Z"
 },
 "contacts": [
 {
 "type": "HOME_PHONE",
 "value": "123-123-1324",
 "optInDate": "2016-05-10T16:40:07.051Z"
 },
 {
 "type": "EMAIL",
 "value": "tl1.3e41c646@mailosaur.in",
 "status": "OPT_IN",
 "optInDate": "2016-05-10T16:40:07.081Z"
 }
 ],
 "customFieldValues": [],
 "result": "FOUND"
 }
 ],
 "count": 7
 }
}

In This Article:

Engage API: Segment Data

In This Article:

Segment Data Detail

Adding/Updating Segments

Create/Update Request Example

Create/Update Response Example

Deleting Segments

Delete Request Example

Delete Response Example

Searching for Segments

Request Body Format

Request Body Format

Request Examples

Response Body Format

Assigning Supporters to Segments

Assigning supporters to a segment

Assignment Request Example

Assignment Response Example

Deleting supporters from a segment

Delete Request Example

Delete Response Example

Searching for supporters assigned to a segment

Request Body Format

Request Examples

Response Body Format

Comments