RetrieveSalesforceObjects

This function retrieves fields from a record in a Sales or Service Cloud standard or custom object. The function returns a row set of fields.

NOTE: This function should only be used in applications that do not require a high volume of requests or return a large number of records; for example, an email send to a small audience, a Triggered Send, or the retrieval of a single record on a landing page.

The function may take several seconds to execute, impacting email send performance and may result in a timeout if the request volume is high for example; using a process loop to execute the function multiple times or returning a large number of rows. Unlike other AMPscript functions that return a row set — for example, LookupRows which limits the number of rows to 2000 — there is not the same type of limitation on the number of rows returned by this function.

Arguments

RetrieveSalesforceObjects(1,2,3,4,5,[6a,6b,6c...])

Ordinal Type Required Description
1 String True API name of the Salesforce object
2 String True Comma-separated array of API field names to retrieve
3 String True API field name to match record
4 String True

Comparison operator for matching records. Valid operators include:

  • = equal to
  • < less than
  • > greater than
  • != not equal to
  • <= less than or equal to
  • >= greater than or equal to
5 String True Value to match record using comparison operator in ordinal 4
6a String False Additional API field name to match record (see note)
6b String False Additional comparison operator to match record (see note)
6c String False Additional value to match record (see note)

NOTE: Additional API field name, comparison operator and value sets can be appended as arguments. However the function joins these additional sets using and clauses.

Example 1

The following example retrieves a record from the Sales Cloud Contact object and displays values on a page for a matching record Id.

%%[

var @subscriberRows

set @subscriberRows = RetrieveSalesforceObjects(
   "Contact",
   "FirstName,LastName,Email",
   "Id", "=", _subscriberKey )

if RowCount(@subscriberRows) == 1 then /* there should only be one row */
  var @subscriberRow, @firstName, @lastName, @email
  set @subscriberRow = Row(@subscriberRows, 1)
  set @firstName = Field(@subscriberRow, "FirstName")
  set @lastName = Field(@subscriberRow, "LastName")
  set @email = Field(@subscriberRow, "Email")
endif

]%%
<!DOCTYPE html>
<html>
   <body>
      <h2>Your Details</h2>

      %%[ if RowCount(@subscriberRows) == 1 then ]%%
      <ul>
         <li><strong>First Name:</strong> %%=v(@firstName)=%%</li>
         <li><strong>Last Name:</strong> %%=v(@lastName)=%%</li>
         <li><strong>Email:</strong> %%=v(@email)=%%</li>
      </ul>
      %%[ else ]%%
      <p>You are not registered.</p>
      %%[ endif ]%%
   </body>
</html>

Output

If a matching Contact record is found, the above code will result in the following output:

<!DOCTYPE html>
<html>
   <body>
      <h2>Your Details</h2>
      <ul>
         <li><strong>First Name:</strong> Sam</li>
         <li><strong>Last Name:</strong> Jones</li>
         <li><strong>Email:</strong> [email protected]</li>
      </ul>
   </body>
</html>

Example 2


Not a subscriber? Subscribe now.