This article assumes implementers know how authenticate with Salesforce and call Salesforce APEX REST services. This will not be covered in this article.
This REST service is responsible for retrieving a page of Preferences based on specific search criteria.
URL:
https://<mysalesforceinstance>/services/apexrest/T1C_Base/GetPreferencesByMultiSearchCriteriaMethod Type:
POST
Parameters:
searchCriteriaForPreferences (object[])
Required
The list of search criteria to get the preferences for. It has the following properties:
reportType (string)
Required
The type of report to get the preferences for.
reportFormat (string)
Required
The type of format associated with the report type to get the preferences for.
searchCriteria (object[])
Required
The search criteria to match against. This will include the external Ids of the interest subject and interest subject type to match against.
Properties:
SubjectTypeId (string)
Required
The external id of the Interest Subject Type that the associated SubjectId belongs to.
SubjectId (string)
Required
The external id of the Interest Subject that to find the preferences for.
fields (string[])
Optional
Array of additional fields that will be returned from the Contact. All field names specified are assumed to be the API name of a field on the Contact. This can be an empty array or null. Regardless of what additional fields are specified the Contact Name and Contact Id will be included in the return.
nextKey (string)
Optional
The next key to use for subsequent pages of information. If the result of a call includes NextKey subsequent calls to this service should be made with the next key being specified.
Returns:
A page of preferences will be returned which is an object with the following properties:
DistributionList (object[])
List of preferences that matched the criteria specified.
Properties:
SubjectTypeId (string)
The external id of the Interest Subject Type that was matched.
SubjectId (string)
The external id of the Interest Subject that was matched.
ReportType (string)
The report type that was matched.
ReportFormat (string)
The report format that was matched.
ContactDetails (object)
The details of the contact that were requested for in the fields parameter. Will at minimum contain the contact’s name and contact’s Id
NextKey (string)
The next key that will be populated if subsequent calls need to be made. If populated additional calls should be made populating the nextKey parameter until there are no more next keys populated in the return.
StatusMessage (string)
Status message will contain warning messages related to the request. The following are values that could be populated:
No Report Type was specified.
This will be returned if no report type was specified in the request.
No Report Format was specified.
This will be returned if no report format was specified in the request.
No Distribution Search Criteria was specified.
This will be returned if no search criteria was specified in the request.
The Type Id: {SubjectTypeId} does not have the specified Report Type ({reportType}) and Format ({reportFormat})
This will be appended to the status message if a specified Subject Type Id does not have the specified Report Type and Report Format. The {SubjectTypeId}, {reportType} and {reportFormat} merge fields will be replaced with the appropriate values
No Type was found in the system with the External Id: {SubjectTypeId}
This will be appended to the status message if no Interest Subject Type was found in Salesforce for a specified Subject Type Id.
No Subject was found in the system with the External Id: {SubjectId} with the Type Id: {SubjectTypeId}
This will be appended to the status message if no Interest Subject was found in Salesforce for the specified Subject Id who is under the type of the SubjectTypeId
No Contacts were found that have Preferences for the specified search criteria.
This will be returned if no Contacts had preferences for the specified search criteria.
Invalid field specified: {fieldname}
This will be returned if an invalid API field name was specified in the fields parameter.
Sample Payload:
{
"searchCriteriaForPreferences": [
{
"reportType": "Company Note",
"reportFormat": "Electronic",
"searchCriteria": [
{
"SubjectTypeId": "ACEPreferenceCoveredTickers",
"SubjectId": "70"
},
{
"SubjectTypeId": "ACEPreferenceCoveredTickers",
"SubjectId": "98"
}
],
"fields": [ "Email" ]
}
],
"nextKey": null
}Sample Response:
{
"StatusMessage": "",
"NextKey": null,
"DistributionList": [
{
"SubjectTypeId": "covered_tickers",
"SubjectId": "70",
"ReportType": "Company Note",
"ReportFormat": "Electronic",
"ContactDetails": {
"attributes": {
"type": "Contact",
"url": "/services/data/v31.0/sobjects/Contact/0033000000xxxxxxAA"
},
"Email": "[email protected]",
"Id": "0033000000xxxxxxAA",
"Name": "Test Contact"
}
},
{
"SubjectTypeId": "covered_tickers",
"SubjectId": "98",
"ReportType": "Company Note",
"ReportFormat": "Electronic",
"ContactDetails": {
"attributes": {
"type": "Contact",
"url": "/services/data/v31.0/sobjects/Contact/0033000000xxxxxxAB"
},
"Email": "[email protected]",
"Id": "0033000000xxxxxxAB",
"Name": "Test Contact 2"
}
},
{
"SubjectTypeId": "covered_tickers",
"SubjectId": "98",
"ReportType": "Company Note",
"ReportFormat": "Electronic",
"ContactDetails": {
"attributes": {
"type": "Contact",
"url": "/services/data/v31.0/sobjects/Contact/0033000000xxxxxxAC"
},
"Email": "[email protected]",
"Id": "0033000000xxxxxxAC",
"Name": "Test Contact 3"
}
}
]
}Sample curl:
curl --location 'https://{{salesforceinstance}}/services/apexrest/T1C_Base/GetPreferencesByMultiSearchCriteria' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{session_id}}' \
--data '{
"searchCriteriaForPreferences": [
{
"reportType": "Company Note",
"reportFormat": "Electronic",
"searchCriteria": [
{
"SubjectTypeId": "covered_tickers",
"SubjectId": "70"
},
{
"SubjectTypeId": "covered_tickers",
"SubjectId": "98"
}
],
"fields": [ "Email" ]
}
],
"nextKey": null
}'