1. Salsa Help Center
  2. Salsa Engage Help Documentation
  3. API: Engage Integration

In This Article:

    Engage API: Segment Data

    Avatar
    Hilary Barnes
    Follow

    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

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

       

      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.