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:
|
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:
|
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
}
}
Request Body Format
{
"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, |
identifierType | payload |
Represents the type of identifier provided; must be one of:
|
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":{ |
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, |
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
|
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,
|
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
}
}
Comments
Please sign in to leave a comment.