1. REST API for Oracle Responsys Marketing Cloud Service
  2. Tasks
  3. Profile Lists

Add or Update RIID in the Organizational Scope Mapping

put

/rest/api/v1.3/lists/{listName}/orgListExtensions/members

Adds or Updates profile list recipient's RIID in the Organizational Scope Mapping

Request

Path Parameters
Body ()
Request body
Root Schema : Merge Org List Recipients
Type: object
Title: Merge Org List Recipients
Show Source
  • Indicates what should be done for records where a match is not found (true = insert / false = no insert).
  • Allowed Values: [ "RIID_", "CUSTOMER_ID_", "EMAIL_ADDRESS_", "MOBILE_NUMBER_", "EMAIL_MD5_HASH_", "EMAIL_SHA256_HASH_" ]
    First match column for determining whether an insert or update should occur.
  • recordData
    Record data that represents field names and corresponding values for the recipient.
  • Allowed Values: [ "REPLACE_ALL", "NO_UPDATE" ]
    Controls how the existing record should be updated.
Nested Schema : recordData
Type: object
Record data that represents field names and corresponding values for the recipient.
Show Source
Nested Schema : fieldNames
Type: array
Field names in the Profile List
Show Source
Nested Schema : records
Type: array
Array of values corresponding to the fieldNames. Each element in the array represents a single recipient.
Show Source
Nested Schema : items
Type: array
Field Values for the recipient in the Profile List
Show Source
Back to Top

Response

Supported Media Types

Default Response

Body ()
Root Schema : Merge Org List Recipients
Type: object
Title: Merge Org List Recipients
Show Source
  • Indicates what should be done for records where a match is not found (true = insert / false = no insert).
  • Allowed Values: [ "RIID_", "CUSTOMER_ID_", "EMAIL_ADDRESS_", "MOBILE_NUMBER_", "EMAIL_MD5_HASH_", "EMAIL_SHA256_HASH_" ]
    First match column for determining whether an insert or update should occur.
  • recordData
    Record data that represents field names and corresponding values for the recipient.
  • Allowed Values: [ "REPLACE_ALL", "NO_UPDATE" ]
    Controls how the existing record should be updated.
Nested Schema : recordData
Type: object
Record data that represents field names and corresponding values for the recipient.
Show Source
Nested Schema : fieldNames
Type: array
Field names in the Profile List
Show Source
Nested Schema : records
Type: array
Array of values corresponding to the fieldNames. Each element in the array represents a single recipient.
Show Source
Nested Schema : items
Type: array
Field Values for the recipient in the Profile List
Show Source
Back to Top

Examples

Add or Update RIID-to-Audience Scope Code Mapping Data for Profile List members

IMPORTANT: This API only applies if Targeting by Organization is enabled for your account. This API allows you to update the system mapping table that maps a Profile List member's RIID to the Organization Scope appropriate for that member. This ensures that Responsys only sends messages to those recipients belonging to a campaign's target audience of selected organization units.

REQUEST NOTES:
  • The service URL only requires the names of the Profile List. The mapping table that stores the information is an internal system table that is not accessible through the application UI. (That is, it is not a PET that is accessible to Responsys users directly.)
  • Up to 200 members can be processed in a single request.
  • Mandatory fieldNames attributes:
    • AUDIENCE_SCOPE_CODE: This is the audience scope code, as defined in the organization table. It is a code that defines the org to which the customer belongs. You can view the organization tree when logged in to Responsys by selecting Account | Organization Management.
    • REC_STATUS_: This is the status of the record. Valid values are "A" (Active) or "D" (Deleted).
    • The fieldNames attribute must also contain at least one of the merge key fields from the profile list (for example, RIID_, EMAIL_ADDRESS_, CUSTOMER_ID_), otherwise the request will result in a MERGEFAILED error.
  • To add a mapping record: Specify "A" for REC_STATUS_. The system adds the mapping to the table. Note that each RIID (customer) can have more than one audience scope coding.
  • To mark a record as deleted: Specify "D" for REC_STATUS_. The system will treat this record as deleted.
  • Up to two match columns can be used for merging records into a profile extension table. If only one match column is specified, the other match column can be set to an empty value (for example, "matchColumnName2" : "").
  • matchColumnName1 and matchColumnName2 values must not contain the usual trailing underscore for the enumerated values. For example, RIID works but RIID_ results in an INVALID_PARAMETER error ("Match Column is null").
  • Limitation for match columns: New records will not be inserted for insertOnNoMatch if a matchColumnName is either EMAIL_MD5_HASH or EMAIL_SHA256_HASH, even if matching records are not found in the table. The email hash attributes (EMAIL_MD5_HASH or EMAIL_SHA256_HASH) are only used for updating existing records.

A successful request requires the following headers:

FIELDS DESCRIPTION
Authorization <AUTH_TOKEN>
Content-Type application/json

Sample Request Body:

In the example below, both records have an AUDIENCE_SCOPE_CODE of "IN". The first example is a valid "Active" (add) entry, but the second record illustrates an incorrect REC_STATUS_, "F", which will result in the error shown in the Sample Response body. 

    {
      "recordData" : {
        "fieldNames" : ["AUDIENCE_SCOPE_CODE", "REC_STATUS_", "EMAIL_ADDRESS_"],
        "records" : [
          ["IN", "A", "4as0dsa@tesasdsat.com"],
          ["IN", "F", "ab.cd@gmail.com"]
        ],
        "mapTemplateName" : null
      },
     "insertOnNoMatch" : true,
     "updateOnMatch" : "REPLACE_ALL",
     "matchColumnName1" : "EMAIL_ADDRESS"
     "matchColumnName2" : ""
    }

Sample Response: Success

RESPONSE NOTES:
  • For each record, if the Audience Scope Code is valid, then system updates the table. The system updates the table with the Profile List member's RIID, Audience Scope Code, and status details (REC_STATUS_).
  • Irrespective of what field names were used to perform the merge, the response will always contain only RIID_ in the fieldNames attribute and the corresponding RIID_ values for the records in the recordsattribute.
  • In case merge failed for a record, the RIID_ of the record is not present in the response. Instead, an error message starting with MERGEFAILED: is returned. Client developers can look for the string MERGEFAILED: in the response for a particular row to determine whether that recipient was merged successfully or not. Reasons for MERGEFAILED include an invalid REC_STATUS_ value, Audience Scope Code provided does not exist, and Audience Scope Code provided does not exist AND the member is not found in the Profile List.
  • The order of records in the response matches the order of records specified in the request payload. Furthermore, other attributes in the response like mapTemplateName, insertOnNoMatch, updateOnMatch and matchColumn will mirror the valid values specified in the request payload or default to null/false in case of invalid values.

In the sample response below, the first record was merged successfully, but the second record failed to merge because it had the incorrect REC_STATUS_ value. Also, the request was sent to the endpoint using the Profile List contacts_list as the {list_name} value. The list name is used in the endpoints provided in the links array in the response. 

    {
      "recordData": 
        { "fieldNames": [ "RIID_" ],
          "records": [ 
            [ "8381" ],
            [ "MERGEFAILED: Invalid REC_STATUS_ provided - should be 'A' or 'D' " ]
          ], 
        "mapTemplateName": null },
      
	  "insertOnNoMatch": true,
      "updateOnMatch": "REPLACE_ALL",
      "matchColumn": "EMAIL_ADDRESS",

	  "links": [
	    { "rel": "self", "href": "/rest/api/v1.3/lists/contacts_list/orgListExtensions/members", "method": "PUT" },
		{ "rel": "retrieveProfileExtensionRecipientsRIID", "href": "/rest/api/v1.3/lists/contacts_list/listExtensions//members/<riid>}", "method": "GET"}
      ]
    }

Sample Response: Failure

In the following sample response body, the request attempted to send more than 200 recipients in a single request.

    {
      "type": "",
      "title": "Record limit exceeded",
      "errorCode": "RECORD_LIMIT_EXCEEDED",
      "detail": "Record limit exceeded, maximum of 200 records are allowed per each api call",
      "errorDetails": []
    }

The following table shows common errors when this type of request fails.

Error Code Detail
RECORD_LIMIT_EXCEEDED Record limit exceeded, maximum of 200 records are allowed per each API call.
INVALID_PARAMETER Match column name is not in fieldNames.
INVALID_PARAMETER Match column name is empty or is not a system column.
INVALID_PARAMETER fieldNames should have REC_STATUS_ and AUDIENCE_SCOPE.
PROFILE_EXTENSION_NOT_FOUND No Organization Profile Extensions Found For List <list_name>.
Back to Top