retrieve

---

Retrieves one or more objects based on the specified object IDs.

Syntax

sObject[] result = sfdc.retrieve(string fieldList, string sObjectType, ID ids[]); 

Usage

Use the retrieve call to retrieve individual objects from an sforce API object. The client application passes the list of fields to retrieve, the object, and an array of object IDs to retrieve. The retrieve call does not return objects that have been deleted.

In general, you use retrieve when you know in advance the IDs of the objects to retrieve. Use query instead to obtain objects when you do not know the IDs or when you want to specify other selection criteria.

Client applications can use retrieve to perform a client-side join. For example, a client application can run a query to obtain a set of Opportunity objects, iterate through the returned Opportunity objects, obtain the accountId for each Opportunity, and then call retrieve to obtain Account information for those accountIds.

Certain objects cannot be retrieved via the sforce API. To retrieve an object via the retrieve call, its object must be configured as retrieveable (retrieveable=True). To determine whether an object can be retrieved, your client application can invoke the describeSObject call on the object and inspect its retrieveable property.

Your client application must be logged in with sufficient access rights to retrieve individual objects within the specified object and to retrieve the fields in the specified field list. For more information, see Factors that Affect Data Access.

Sample Code-Java

private void retrieveSample() { 
// Invoke the retrieve call and save results in an array of SObjects 
SObject[] sObjects = binding.retrieve("Id, AccountNumber, Name, Website", 
"Account", accounts); 
// Verify that some objects were returned. 
// Even though we began with valid object Ids, 
// someone else might have deleted them in the meantime. 
if (sObjects != null) { 
   // Loop through the array and print out some properties 
   for (int i=0;i<sObjects.length;i++) { 
      // Cast the SObject into an Account object 
      Account retrievedAccount = (Account)sObjects[i]; 
      System.out.println("Account: " + retrievedAccount.getId().getValue()); 
      System.out.println("    AccountNumber = " + 
retrievedAccount.getAccountNumber()); 
      System.out.println("    Name          = " + retrievedAccount.getName()); 
      System.out.println("    Website       = " + retrievedAccount.getWebsite()); 
      } 
   } 
} 

Sample Code-C#

private void retrieve() 
{ 
   // Invoke retrieve call and save results in an array of SObjects 
   sObject[] records = binding.retrieve("FirstName, LastName", "Contact", new 
String[] {"", ""}); 
    
   // Iterate through the results 
   for (int i=0;i<records.Length;i++)  
   { 
      Contact contact = (Contact)records[i]; 
      // Get the contact properties 
      System.Diagnostics.Trace.WriteLine("Name is: " + contact.FirstName + " " + 
contact.LastName); 
   } 
} 

Arguments

Name	Type	Description
fieldList	string	List of one or more fields in the specified object, separated by commas. You must specify valid field names and must have read-level permissions to each specified field. The fieldList defines the ordering of fields in the result.
from	string	Object from which to retrieve data. The specified value must be a valid object for your organization. For a complete list of sforce objects, see List of sforce Objects.
ids	ID[]	Array of one or more IDs of the objects to retrieve. You can pass a maximum of 2000 object IDs to the retrieve call.

Response

Name	Type	Description
result	sObject[]	Array of one or more sObjects representing individual objects of the specified object. The number of sObjects returned in the array matches the number of object IDs passed into the retrieve call. If you do not have access to an object or if a passed ID is invalid, the array returns null for that object.

Fault

InvalidSObjectFault

InvalidFieldFault

UnexpectedErrorFault

See Also

Sample SOAP Messages-retrieve

Concepts