Salesforce Docs Portal

Retrieve Data from a Data Extension

Use the retrieve method to get data from a data extension. You can retrieve up to 2,500 records per request.

Keep these considerations in mind when you use SOAP API to retrieve data from data extensions.

  • If you issue one or fewer calls per hour, you can achieve better performance and efficiency by using a data extract activity to deliver the data to your Enhanced FTP location.
  • The data extension object doesn’t support LIKE operators in filters for the retrieve method.
  • When you retrieve a column that contains the Date data type, SOAP API returns a value that’s rounded to the nearest second, followed by AM or PM. This behavior occurs even when the source timestamp contains millisecond data. As a result, if you use a Date column as a primary key, it can prevent you from retrieving unique rows. For this reason, we recommend against using Date values as primary keys.

Sample SOAP Request

This sample SOAP envelope represents a request to retrieve several fields from a data extension based on the value of the MemberId column.

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
  xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing"
  xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <s:Header>
    <a:Action s:mustUnderstand="1">Retrieve</a:Action>
    <a:To s:mustUnderstand="1">
      https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</a:To>
    <fueloauth xmlns="http://exacttarget.com">YOUR_ACCESS_TOKEN</fueloauth>
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <RetrieveRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
      <RetrieveRequest>
        <ObjectType>DataExtensionObject[MembershipRewardsProgramme]</ObjectType>
        <Properties>FirstName</Properties>
        <Properties>Surname</Properties>
        <Properties>Area</Properties>
        <Properties>RewardsPoints</Properties>
        <Filter xsi:type="SimpleFilterPart">
          <Property>MemberId</Property>
          <SimpleOperator>equals</SimpleOperator>
          <Value>dc415965-f672-4381-993f-1ffd00a9dab6</Value>
        </Filter>
      </RetrieveRequest>
    </RetrieveRequestMsg>
  </s:Body>
</s:Envelope>

Sample SOAP Response

If the information from the request is found in the data extension, the response contains that information.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <env:Header xmlns:env="http://www.w3.org/2003/05/soap-envelope">
    <wsa:Action>RetrieveResponse</wsa:Action>
    <wsa:MessageID>urn:uuid:a8496aed-18c2-4eaf-b10b-0784aa6f8fd4</wsa:MessageID>
    <wsa:RelatesTo>urn:uuid:67ab5548-912e-4c51-9d53-d9f68d0370e6</wsa:RelatesTo>
    <wsa:To>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous
    </wsa:To>
    <wsse:Security>
      <wsu:Timestamp wsu:Id="Timestamp-faa7151b-48c9-498d-b690-8035c5202d95">
        <wsu:Created>2024-07-10T19:03:56Z</wsu:Created>
        <wsu:Expires>2024-07-10T19:08:56Z</wsu:Expires>
      </wsu:Timestamp>
    </wsse:Security>
  </env:Header>
  <soap:Body>
    <RetrieveResponseMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
      <OverallStatus>OK</OverallStatus>
      <RequestID>4f7cc213-3b96-4c5c-9684-f23f0d7c1fcd</RequestID>
      <Results xsi:type="DataExtensionObject">
        <PartnerKey xsi:nil="true" />
        <ObjectID xsi:nil="true" />
        <Type>DataExtensionObject</Type>
        <Properties>
          <Property>
            <Name>FirstName</Name>
            <Value>Pooja</Value>
          </Property>
          <Property>
            <Name>Surname</Name>
            <Value>Chatterjee</Value>
          </Property>
          <Property>
            <Name>Area</Name>
            <Value>Hammersmith</Value>
          </Property>
          <Property>
            <Name>RewardsPoints</Name>
            <Value>201042</Value>
          </Property>
        </Properties>
      </Results>
    </RetrieveResponseMsg>
  </soap:Body>
</soap:Envelope>