salesforce: Winter '12

Web Services API Developer's Guide

Last updated: October 7, 2011 Copyright 2000-2011 salesforce.com, inc. All rights reserved. Salesforce.com is a registered trademark of salesforce.com, inc., as are other

names and marks. Other marks appearing herein may be trademarks of their respective owners.

Table of Contents

Table of ContentsGetting Started..................................................................................................................................13 Chapter 1: Introducing the API.................................................................................................13When to Use the Web Services API...........................................................................................................................14 Customize, Integrate, and Extend Your Salesforce Solutions.....................................................................................15 Supported Salesforce Editions.....................................................................................................................................15 Standards Compliance.................................................................................................................................................16 Development Platforms...............................................................................................................................................16 API Support Policy.....................................................................................................................................................16 Choosing a WSDL......................................................................................................................................................17 Related Resources .......................................................................................................................................................18 Whats New in Version 23.0........................................................................................................................................18 Quick Start..................................................................................................................................................................20 Step 1: Obtain a Salesforce Developer Edition Organization..........................................................................21 Step 2: Generate or Obtain the Web Service WSDL......................................................................................21 Step 3: Import the WSDL File Into Your Development Platform.................................................................22 Step 4: Walk Through the Sample Code........................................................................................................23

Chapter 2: Standard and Custom Object Basics..........................................................................40Primitive Data Types...................................................................................................................................................41 Field Types..................................................................................................................................................................43 API Data Types and Salesforce Field Types...............................................................................................................47 Core Data Types Used in API Calls...........................................................................................................................48 sObject.............................................................................................................................................................48 API Fault Element..........................................................................................................................................49 ExceptionCode................................................................................................................................................49 Error................................................................................................................................................................54 StatusCode.......................................................................................................................................................55 System Fields...............................................................................................................................................................66 Required Fields............................................................................................................................................................68 Frequently-Occurring Fields.......................................................................................................................................68 API Field Properties....................................................................................................................................................69 Relationships Among Objects.....................................................................................................................................70 Relabeling Fields and Tabs and the API.....................................................................................................................71 Force.com AppExchange Object Prefixes and the API...............................................................................................71 Custom Objects...........................................................................................................................................................71

Chapter 3: API Call Basics.........................................................................................................75Characteristics of API Calls........................................................................................................................................76 Factors that Affect Data Access..................................................................................................................................76 Package Version Settings.............................................................................................................................................78

i

Table of Contents

Chapter 4: Error Handling.........................................................................................................80Error Handling for Session Expiration .......................................................................................................................81 More About Error Handling.......................................................................................................................................81

Chapter 5: Security and the API.................................................................................................82User Authentication....................................................................................................................................................83 User Profile and Permission Sets Configuration.........................................................................................................83 Security Token.............................................................................................................................................................83 Sharing........................................................................................................................................................................84 Implicit Restrictions for Objects and Fields................................................................................................................85 API Access in Force.com AppExchange Packages......................................................................................................85 Outbound Port Restrictions........................................................................................................................................87

Chapter 6: Using the Partner WSDL..........................................................................................88Obtaining the Partner WSDL File.............................................................................................................................89 Calls and the Partner WSDL .....................................................................................................................................89 Objects, Fields, and Field Data and the Partner WSDL.............................................................................................90 Queries and the Partner WSDL..................................................................................................................................90 Namespaces in the Partner WSDL.............................................................................................................................91 Package Versions and the Partner WSDL..................................................................................................................91 User Interface Themes.................................................................................................................................................92 Examples.....................................................................................................................................................................92 Sample query Calls..........................................................................................................................................92 Sample search Call...........................................................................................................................................94 Sample create Call...........................................................................................................................................96 Sample update Call..........................................................................................................................................97

Reference.........................................................................................................................................100 Chapter 7: Data Model............................................................................................................100Sales Objects..............................................................................................................................................................101 Task and Event Objects.............................................................................................................................................102 Support Objects.........................................................................................................................................................103 Document, Note, and Attachment Objects...............................................................................................................104 User and Profile Objects............................................................................................................................................104 Record Type Objects.................................................................................................................................................105 Product and Schedule Objects...................................................................................................................................106 Sharing and Team Selling Objects............................................................................................................................107 Customizable Forecasting Objects............................................................................................................................108 Territory Management..............................................................................................................................................109 Process Objects..........................................................................................................................................................110 Content Objects........................................................................................................................................................111 Salesforce Chatter Objects.........................................................................................................................................112

Chapter 8: Standard Objects....................................................................................................113Account.....................................................................................................................................................................124

ii

Table of Contents AccountContactRole.................................................................................................................................................138 AccountFeed..............................................................................................................................................................139 AccountHistory.........................................................................................................................................................144 AccountOwnerSharingRule.......................................................................................................................................146 AccountPartner..........................................................................................................................................................148 AccountShare............................................................................................................................................................150 AccountTag...............................................................................................................................................................153 AccountTeamMember..............................................................................................................................................154 AccountTerritoryAssignmentRule............................................................................................................................156 AccountTerritoryAssignmentRuleItem.....................................................................................................................158 AccountTerritorySharingRule...................................................................................................................................159 ActivityHistory..........................................................................................................................................................162 AdditionalNumber....................................................................................................................................................168 ApexClass..................................................................................................................................................................169 ApexComponent.......................................................................................................................................................171 ApexLog....................................................................................................................................................................174 ApexPage...................................................................................................................................................................176 ApexTestQueueItem.................................................................................................................................................179 ApexTestResult.........................................................................................................................................................181 ApexTrigger..............................................................................................................................................................183 Approval....................................................................................................................................................................188 Article Type__DataCategorySelection......................................................................................................................190 Article Type__Feed...................................................................................................................................................192 Asset..........................................................................................................................................................................196 AssetFeed..................................................................................................................................................................200 AssetTag....................................................................................................................................................................204 AssignmentRule........................................................................................................................................................206 AsyncApexJob...........................................................................................................................................................207 Attachment................................................................................................................................................................209 Bookmark..................................................................................................................................................................213 BrandTemplate..........................................................................................................................................................214 BusinessHours...........................................................................................................................................................216 BusinessProcess.........................................................................................................................................................220 CallCenter.................................................................................................................................................................222 Campaign..................................................................................................................................................................224 CampaignFeed..........................................................................................................................................................233 CampaignMember.....................................................................................................................................................238 CampaignMemberStatus...........................................................................................................................................241 CampaignOwnerSharingRule...................................................................................................................................243 CampaignShare.........................................................................................................................................................244 CampaignTag............................................................................................................................................................245 Case...........................................................................................................................................................................247 CaseArticle................................................................................................................................................................255 CaseComment...........................................................................................................................................................256 CaseContactRole ......................................................................................................................................................258

iii

Table of Contents CaseFeed...................................................................................................................................................................259 CaseHistory...............................................................................................................................................................264 CaseMilestone...........................................................................................................................................................266 CaseOwnerSharingRule............................................................................................................................................268 CaseShare..................................................................................................................................................................270 CaseSolution..............................................................................................................................................................272 CaseStatus.................................................................................................................................................................273 CaseTag.....................................................................................................................................................................274 CaseTeamMember....................................................................................................................................................275 CaseTeamRole..........................................................................................................................................................276 CaseTeamTemplate...................................................................................................................................................277 CaseTeamTemplateMember.....................................................................................................................................278 CaseTeamTemplateRecord.......................................................................................................................................279 CategoryData............................................................................................................................................................280 CategoryNode...........................................................................................................................................................281 CategoryNodeLocalization........................................................................................................................................282 ChatterActivity..........................................................................................................................................................286 ChatterConversation.................................................................................................................................................288 ChatterConversationMember....................................................................................................................................288 ChatterMessage.........................................................................................................................................................289 CollaborationGroup..................................................................................................................................................290 CollaborationGroupFeed...........................................................................................................................................294 CollaborationGroupMember.....................................................................................................................................299 CollaborationGroupMemberRequest........................................................................................................................300 CollaborationInvitation.............................................................................................................................................301 Community...............................................................................................................................................................304 Contact......................................................................................................................................................................305 ContactFeed..............................................................................................................................................................314 ContactHistory..........................................................................................................................................................319 ContactOwnerSharingRule.......................................................................................................................................320 ContactShare.............................................................................................................................................................321 ContactTag................................................................................................................................................................323 ContentDocument.....................................................................................................................................................325 ContentDocumentFeed.............................................................................................................................................327 ContentDocumentHistory........................................................................................................................................332 ContentDocumentLink.............................................................................................................................................334 ContentVersion.........................................................................................................................................................335 ContentVersionHistory.............................................................................................................................................344 ContentWorkspace....................................................................................................................................................346 ContentWorkspaceDoc.............................................................................................................................................348 Contract.....................................................................................................................................................................349 ContractContactRole ...............................................................................................................................................356 ContractFeed.............................................................................................................................................................358 ContractHistory.........................................................................................................................................................363 ContractLineItem......................................................................................................................................................364

iv

Table of Contents ContractLineItemHistory..........................................................................................................................................368 ContractStatus...........................................................................................................................................................370 ContractTag..............................................................................................................................................................371 CronTrigger..............................................................................................................................................................372 CurrencyType............................................................................................................................................................375 Custom Object__Feed...............................................................................................................................................377 Dashboard.................................................................................................................................................................382 DashboardComponent..............................................................................................................................................386 DashboardComponentFeed......................................................................................................................................387 DashboardFeed..........................................................................................................................................................391 DashboardTag...........................................................................................................................................................396 DatedConversionRate...............................................................................................................................................398 Division.....................................................................................................................................................................399 DivisionLocalization..................................................................................................................................................401 Document..................................................................................................................................................................402 DocumentAttachmentMap.......................................................................................................................................406 DocumentTag...........................................................................................................................................................408 EmailMessage............................................................................................................................................................409 EmailServicesAddress................................................................................................................................................412 EmailServicesFunction..............................................................................................................................................414 EmailStatus...............................................................................................................................................................420 EmailTemplate..........................................................................................................................................................421 Entitlement................................................................................................................................................................426 EntitlementContact...................................................................................................................................................429 EntitlementFeed........................................................................................................................................................430 EntitlementHistory...................................................................................................................................................435 EntitlementTemplate................................................................................................................................................436 EntityHistory.............................................................................................................................................................438 EntitySubscription.....................................................................................................................................................440 Event.........................................................................................................................................................................441 EventAttendee...........................................................................................................................................................452 EventFeed..................................................................................................................................................................453 EventTag...................................................................................................................................................................458 FeedComment...........................................................................................................................................................460 FeedItem...................................................................................................................................................................462 FeedLike....................................................................................................................................................................468 FeedPost....................................................................................................................................................................469 FeedTrackedChange..................................................................................................................................................473 FiscalYearSettings......................................................................................................................................................477 Folder........................................................................................................................................................................480 ForecastShare.............................................................................................................................................................482 GoogleDoc................................................................................................................................................................484 Group........................................................................................................................................................................485 GroupMember...........................................................................................................................................................488 Holiday......................................................................................................................................................................489

v

Table of Contents Idea............................................................................................................................................................................492 IdeaComment............................................................................................................................................................497 KnowledgeArticle......................................................................................................................................................498 KnowledgeArticleVersion..........................................................................................................................................500 KnowledgeArticleViewStat.......................................................................................................................................506 KnowledgeArticleVoteStat........................................................................................................................................508 Lead...........................................................................................................................................................................509 LeadFeed...................................................................................................................................................................523 LeadHistory...............................................................................................................................................................528 LeadOwnerSharingRule............................................................................................................................................530 LeadShare..................................................................................................................................................................531 LeadStatus.................................................................................................................................................................533 LeadTag....................................................................................................................................................................534 LineitemOverride......................................................................................................................................................535 LoginHistory.............................................................................................................................................................538 MailmergeTemplate..................................................................................................................................................541 MilestoneType...........................................................................................................................................................543 Name.........................................................................................................................................................................544 NewsFeed..................................................................................................................................................................547 Note...........................................................................................................................................................................553 NoteAndAttachment.................................................................................................................................................554 NoteTag....................................................................................................................................................................556 OpenActivity.............................................................................................................................................................557 Opportunity...............................................................................................................................................................563 OpportunityCompetitor............................................................................................................................................572 OpportunityContactRole...........................................................................................................................................573 OpportunityFeed.......................................................................................................................................................575 OpportunityFieldHistory...........................................................................................................................................580 OpportunityHistory...................................................................................................................................................582 OpportunityLineItem................................................................................................................................................584 OpportunityLineItemSchedule..................................................................................................................................590 OpportunityOverride.................................................................................................................................................593 OpportunityOwnerSharingRule................................................................................................................................597 OpportunityPartner...................................................................................................................................................598 OpportunityShare......................................................................................................................................................599 OpportunitySplit.......................................................................................................................................................601 OpportunityStage......................................................................................................................................................604 OpportunityTag........................................................................................................................................................606 OpportunityTeamMember........................................................................................................................................607 Organization..............................................................................................................................................................609 OrgWideEmailAddress.............................................................................................................................................627 Partner.......................................................................................................................................................................628 PartnerNetworkConnection......................................................................................................................................630 PartnerNetworkRecordConnection...........................................................................................................................632 PartnerRole................................................................................................................................................................636

vi

Table of Contents Period........................................................................................................................................................................637 PermissionSet............................................................................................................................................................639 PermissionSetAssignment.........................................................................................................................................641 Pricebook2.................................................................................................................................................................642 PricebookEntry..........................................................................................................................................................646 ProcessInstance..........................................................................................................................................................648 ProcessInstanceHistory..............................................................................................................................................650 ProcessInstanceStep...................................................................................................................................................652 ProcessInstanceWorkitem.........................................................................................................................................654 Product2....................................................................................................................................................................655 Product2Feed............................................................................................................................................................661 ProductEntitlementTemplate....................................................................................................................................666 Profile........................................................................................................................................................................667 PushTopic.................................................................................................................................................................669 QuantityForecast.......................................................................................................................................................673 QuantityForecastHistory...........................................................................................................................................681 Question....................................................................................................................................................................684 QuestionDataCategorySelection...............................................................................................................................686 QueueSobject.............................................................................................................................................................688 Quote.........................................................................................................................................................................689 QuoteDocument........................................................................................................................................................698 QuoteLineItem..........................................................................................................................................................700 RecordType...............................................................................................................................................................704 RecordTypeLocalization............................................................................................................................................707 Reply..........................................................................................................................................................................708 Report........................................................................................................................................................................710 ReportFeed................................................................................................................................................................712 ReportTag.................................................................................................................................................................717 RevenueForecast........................................................................................................................................................718 RevenueForecastHistory............................................................................................................................................727 Scontrol.....................................................................................................................................................................730 ScontrolLocalization..................................................................................................................................................733 SelfServiceUser..........................................................................................................................................................737 ServiceContract.........................................................................................................................................................740 ServiceContractFeed..................................................................................................................................................747 ServiceContractHistory.............................................................................................................................................751 ServiceContractOwnerSharingRule...........................................................................................................................752 ServiceContractShare................................................................................................................................................754 Site.............................................................................................................................................................................755 SiteDomain...............................................................................................................................................................760 SiteHistory.................................................................................................................................................................761 SlaProcess..................................................................................................................................................................762 Solution.....................................................................................................................................................................764 SolutionFeed..............................................................................................................................................................767 SolutionHistory.........................................................................................................................................................772

vii

Table of Contents SolutionStatus............................................................................................................................................................773 SolutionTag...............................................................................................................................................................775 StaticResource...........................................................................................................................................................776 TagDefinition............................................................................................................................................................779 Task...........................................................................................................................................................................780 TaskFeed...................................................................................................................................................................789 TaskPriority...............................................................................................................................................................794 TaskStatus.................................................................................................................................................................795 TaskTag.....................................................................................................................................................................796 Territory....................................................................................................................................................................798 User...........................................................................................................................................................................800 UserAccountTeamMember.......................................................................................................................................819 UserFeed....................................................................................................................................................................822 UserLicense...............................................................................................................................................................827 UserPreference...........................................................................................................................................................829 UserProfileFeed.........................................................................................................................................................830 UserRole....................................................................................................................................................................836 UserTeamMember....................................................................................................................................................839 UserTerritory.............................................................................................................................................................840 Vote...........................................................................................................................................................................842 WebLink...................................................................................................................................................................843 WebLinkLocalization................................................................................................................................................849

Chapter 9: Core Calls...............................................................................................................853convertLead().............................................................................................................................................................854 LeadConvertResult........................................................................................................................................858 create().......................................................................................................................................................................859 SaveResult......................................................................................................................................................864 delete().......................................................................................................................................................................865 DeleteResult..................................................................................................................................................867 emptyRecycleBin().....................................................................................................................................................867 EmptyRecycleBinResult................................................................................................................................869 getDeleted()...............................................................................................................................................................870 GetDeletedResult..........................................................................................................................................873 getUpdated()..............................................................................................................................................................874 GetUpdatedResult.........................................................................................................................................876 invalidateSessions()....................................................................................................................................................877 InvalidateSessionsResult................................................................................................................................878 login()........................................................................................................................................................................879 LoginResult...................................................................................................................................................881 logout()......................................................................................................................................................................882 merge()......................................................................................................................................................................883 MergeResult..................................................................................................................................................886 process().....................................................................................................................................................................886 ProcessResult.................................................................................................................................................888

viii

Table of Contents query().......................................................................................................................................................................889 QueryResult...................................................................................................................................................892 QueryLocator.................................................................................................................................................895 Salesforce Object Query Language (SOQL).................................................................................................895 queryAll()...................................................................................................................................................................947 queryMore()...............................................................................................................................................................949 QueryResult...................................................................................................................................................952 QueryLocator.................................................................................................................................................952 retrieve()....................................................................................................................................................................952 search()......................................................................................................................................................................954 SearchResult..................................................................................................................................................957 Salesforce Object Search Language (SOSL)..................................................................................................957 undelete()...................................................................................................................................................................977 UndeleteResult...............................................................................................................................................978 update()......................................................................................................................................................................979 SaveResult......................................................................................................................................................983 upsert().......................................................................................................................................................................984 UpsertResult..................................................................................................................................................988

Chapter 10: Describe Calls.......................................................................................................989describeDataCategoryGroups().................................................................................................................................989 DescribeDataCategoryGroupResult..............................................................................................................991 describeDataCategoryGroupStructures()...................................................................................................................992 DescribeDataCategoryGroupStructureResult...............................................................................................995 describeGlobal().........................................................................................................................................................996 DescribeGlobalResult....................................................................................................................................997 describeLayout()........................................................................................................................................................999 DescribeLayoutResult..................................................................................................................................1002 describeSObject().....................................................................................................................................................1008 describeSObjectResult.................................................................................................................................1010 describeSObjects()...................................................................................................................................................1010 DescribeSObjectResult................................................................................................................................1012 describeSoftphoneLayout()......................................................................................................................................1022 describeTabs()..........................................................................................................................................................1025 describeTabSetResult...................................................................................................................................1027

Chapter 11: Utility Calls.........................................................................................................1028getServerTimestamp().............................................................................................................................................1028 getServerTimestampResult..........................................................................................................................1029 getUserInfo()...........................................................................................................................................................1029 getUserInfoResult........................................................................................................................................1031 resetPassword()........................................................................................................................................................1032 sendEmail().............................................................................................................................................................1033 SendEmailResult.........................................................................................................................................1041 setPassword()...........................................................................................................................................................1042

ix

Table of Contents

Chapter 12: SOAP Headers....................................................................................................1044AllOrNoneHeader...................................................................................................................................................1045 AllowFieldTruncationHeader.................................................................................................................................1046 AssignmentRuleHeader...........................................................................................................................................1047 CallOptions.............................................................................................................................................................1048 DisableFeedTrackingHeader...................................................................................................................................1050 EmailHeader...........................................................................................................................................................1051 LocaleOptions.........................................................................................................................................................1052 LoginScopeHeader..................................................................................................................................................1053 MruHeader..............................................................................................................................................................1054 PackageVersionHeader............................................................................................................................................1054 QueryOptions..........................................................................................................................................................1056 SessionHeader.........................................................................................................................................................1056 UserTerritoryDeleteHeader.....................................................................................................................................1057

Using the API with Salesforce Features............................................................................................1058 Chapter 13: Implementation Considerations...........................................................................1058Choosing a User for an Integration.........................................................................................................................1059 Login Server URL...................................................................................................................................................1059 Log in to the Login Server......................................................................................................................................1060 Typical API Call Sequence......................................................................................................................................1060 Salesforce Sandbox..................................................................................................................................................1061 Multiple Instances of Salesforce.com Database Servers...........................................................................................1061 Content Type Requirement.....................................................................................................................................1061 Monitoring API Traffic...........................................................................................................................................1061 API Usage Metering................................................................................................................................................1061 Compression............................................................................................................................................................1063 HTTP Persistent Connections................................................................................................................................1064 HTTP Chunking....................................................................................................................................................1064 Internationalization and Character Sets..................................................................................................................1065 XML Compliance...................................................................................................................................................1065 .NET, Non-String Fields, and the Enterprise WSDL............................................................................................1065

Chapter 14: Outbound Messaging..........................................................................................1067Understanding Outbound Messaging......................................................................................................................1068 Understanding Notifications...................................................................................................................................1069 Setting Up Outbound Messaging............................................................................................................................1069 Setting Up User Profiles..............................................................................................................................1070 Defining Outbound Messaging...................................................................................................................1070 Downloading the Salesforce Client Certificate............................................................................................1071 Viewing Outbound Messages......................................................................................................................1071 Tracking Outbound Message Status............................................................................................................1072 Important Security Considerations..........................................................................................................................1072 Understanding the Outbound Messaging WSDL..................................................................................................1073

x

Table of Contents Building a Listener..................................................................................................................................................1074

Chapter 15: Data Loading and Integration..............................................................................1076Choosing the Right API.........................................................................................................................................1077 Client Application Design.......................................................................................................................................1077 Salesforce Settings...................................................................................................................................................1078 Best Practices with Any Data Loader .....................................................................................................................1079 Integration and Single Sign-On..............................................................................................................................1080

Chapter 16: Data Replication.................................................................................................1081API Calls for Data Replication................................................................................................................................1082 Scope of Data Replication.......................................................................................................................................1082 Data Replication Steps............................................................................................................................................1082 Object-Specific Requirements for Data Replication...............................................................................................1083 Polling for Changes.................................................................................................................................................1083 Checking for Structural Changes in the Object.......................................................................................................1084

Chapter 17: Feature-Specific Considerations..........................................................................1085Archived Activities..................................................................................................................................................1086 Person Account Record Types.................................................................................................................................1086 Opportunity Forecast Override Business Rules.......................................................................................................1087 OpportunityOverride Lifecycle....................................................................................................................1088 LineitemOverride Object Lifecycle ............................................................................................................1090 Call Centers and the API........................................................................................................................................1091 Implementing Salesforce Integrations on Force.com...............................................................................................1093 Articles.....................................................................................................................................................................1094 Data Categories.......................................................................................................................................................1099 Chatter Object Relationships..................................................................................................................................1101

Glossary.........................................................................................................................................1103 Index..............................................................................................................................................1119

xi

Table of Contents

xii

GETTING STARTED

Chapter 1Introducing the APIIn this chapter ... When to Use the Web Services API Customize, Integrate, and Extend Your Salesforce Solutions Supported Salesforce Editions Standards Compliance Development Platforms API Support Policy Choosing a WSDL Related Resources Whats New in Version 23.0 Quick StartSalesforce.com provides programmatic access to your organizations information using simple, powerful, and secure application programming interfaces. To use this document, you should have a basic familiarity with software development, Web services, and the Salesforce user interface. Any functionality described in this guide is available if your organization has the API feature enabled. This feature is enabled by default for Unlimited, Enterprise, and Developer Editions. Some Professional Edition organizations may also have the API enabled. If you cannot access the features you see in this guide, contact salesforce.com. Note: Salesforce.com Education Services offers a suite of training courses to enable developers to design, create, integrate, and extend applications built on the Apex platform. Be sure to visit http://www.salesforce.com/training to learn more.

13

Introducing the API

When to Use the Web Services API

When to Use the Web Services APIThe Salesforce prebuilt applications provide powerful CRM functionality. In addition, Salesforce provides the ability to customize the prebuilt applications to fit your organization. However, your organization may have complex business processes that are unsupported by the existing functionality. When this is the case, the Force.com platform includes a number of ways for advanced administrators and developers to implement custom functionality. These include the Web services API, Apex, and Visualforce.

SOAP Web Services APIUse the SOAP API to create, retrieve, update or delete records, such as accounts, leads, and custom objects. With more than 20 different calls, the API also allows you to maintain passwords, perform searches, and much more. Use the API in any language that supports Web services.

REST APIThe REST API provides a powerful, convenient, and simple Web services interface for interacting with Salesforce. Its advantages include ease of integration and development, and it is an excellent choice of technology for use with mobile applications and Web 2.0 projects. However, if you have large numbers of records to process, you may wish to use the Bulk API, which is based on REST principles and optimized for large sets of data.

Bulk APIThe Bulk API is based on REST principles, and is optimized for loading or deleting large sets of data. It allows you to query, insert, update, upsert, or delete a large number of records asynchronously by submitting a number of batches which are processed in the background by Salesforce. The SOAP-based API, in contrast, is optimized for real-time client applications that update small numbers of records at a time. Although the SOAP-based API can also be used for processing large numbers of records, when the data sets contain hundreds of thousands of records it becomes less practical. The Bulk API is designed to make it simple to process data from a few thousand to millions of records.

Metadata APIUse the Metadata API to retrieve, deploy, create, update or delete customization information, such as custom object definitions and page layouts, for your organization. The most common usage is to migrate changes from a sandbox or testing organization to your production organization. The Metadata API is intended for managing customizations and for building tools that can manage the metadata model, not the data itself. To create, retrieve, update or delete records, such as accounts or leads, use the API to manage your data. The easiest way to access the functionality in the Metadata API is to use the Force.com IDE or Force.com Migration Tool. These tools are built on top of the Metadata API and use the standard Eclipse and Ant tools respectively to simplify the task of working with the Metadata API. Built on the Eclipse platform, the Force.com IDE provides a comfortable environment for programmers familiar with integrated development environments, allowing you to code, compile, test, and deploy all from within the IDE itself. The Force.com Migration Tool is ideal if you want to use a script or a command-line utility for moving metadata between a local directory and a Salesforce organization.

ApexUse Apex if you want to: Create Web services Create email services

14

Introducing the API

Customize, Integrate, and Extend Your Salesforce Solutions

Perform complex validation over multiple objects Create complex business processes that are not supported by workflow Create custom transactional logic (logic that occurs over the entire transaction, not just with a single record or object) Attach custom logic to another operation, such as saving a record, so that it occurs whenever the operation is executed, regardless of whether it originates in the user interface, a Visualforce page, or from the Web Services API.

For more information, see the Force.com Apex Code Developer's Guide.

VisualforceVisualforce consists of a tag-based markup language that gives developers a more powerful way of building applications and customizing the Salesforce user interface. With Visualforce you can: Build wizards and other multistep processes Create your own custom flow control through an application Define navigation patterns and data-specific rules for optimal, efficient application interaction

For more information, see the Visualforce Developer's Guide.

Customize, Integrate, and Extend Your Salesforce SolutionsThe Force.com platform allows you to customize, integrate, and extend your Salesforce organization using the language and platform of your choice: Customize Salesforce with custom fields, links, objects, page layouts, buttons, record types, s-controls, and tabs to meet specific business requirements. Integrate Salesforce with your organizations ERP and finance systems, deliver real-time sales and support information to company portals, and populate critical business systems with customer information. Extend Salesforce in presentation, business logic, and data services with new functionality that reflects the business requirements of your organization.

For more information about Force.com solutions, developer resources, and community resources, go to Developer Force.

Supported Salesforce EditionsTo use the API, your organization must use Enterprise Edition, Unlimited Edition, or Developer Edition. If you are an existing Salesforce customer and want to upgrade to either Enterprise or Unlimited Edition, contact your account representative. To develop Web service client applications, it is strongly recommended that you use Developer Sandbox, which is an exact replica of your Salesforce deployment, including all customization and data. For more information, see http://www.salesforce.com/products/sandbox.jsp. Developer Edition provides access to all of the features available with Enterprise Edition. Developer Edition is constrained only by the number of users and the amount of storage space. Developer Edition provides a development context that allows you to build and test your solutions without affecting your organizations live data. Developer Edition accounts are available for free at http://wiki.developerforce.com/index.php/Getting_Started.

15

Introducing the API

Standards Compliance

Standards ComplianceThe API is implemented to comply with the following specifications: Standard Name Simple Object Access Protocol (SOAP) 1.1 Web Service Description Language (WSDL) 1.1 WS-I Basic Profile 1.1http://www.w3.org/TR/2001/NOTE-wsdl-20010315 http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html

Website

Development PlatformsThe API works with current SOAP development environments, including, but not limited to, Visual Studio .NET 2005, and . In this document, we provide examples in Java and C# (.NET). The Java examples are based on WSC 20.0 (WSC) and JDK 6 (Java Platform Standard Edition Development Kit 6). For more information about WSC, go to http://code.google.com/p/sfdc-wsc/. To see a complete list of compatible development platforms and more sample code, go to developer.force.com. Note: Development platforms vary in their SOAP implementations. Implementation differences in certain development platforms might prevent access to some or all of the features in the API. If you are using Visual Studio for .NET development, we recommend that you use Visual Studio 2003 or higher.

API Support PolicySalesforce.com recommends that your new client applications use the most recent version of the Force.com WSDL file to fully exploit the benefits of richer features and greater efficiency. You can navigate to the most recent WSDL for your organization by clicking Your Name > Setup > Develop > API. When a new version is released, use the following steps in Quick Start to update your WSDL: Regenerate the WSDL file (see Step 2: Generate or Obtain the Web Service WSDL) Import it into your environment (see Step 3: Import the WSDL File Into Your Development Platform)

Backward CompatibilitySalesforce.com strives to make backward compatibility easy when using the Force.com platform. Each new Salesforce release consists of two components: A new release of platform software that resides on salesforce.com systems A new version of the API

For example, the Winter 07 release included API version 9.0 and the Summer 07 release included API version 10.0.

16

Introducing the API

Choosing a WSDL

We maintain support for each API version across releases of the platform software. The API is backward compatible in that an application created to work with a given API version will continue to work with that same API version in future platform software releases. Salesforce.com does not guarantee that an application written against one API version will work with future API versions: Changes in method signatures and data representations are often required as we continue to enhance the API. However, we strive to keep the API consistent from version to version with minimal if any changes required to port applications to newer API versions. For example, an application written using API version 9.0 which shipped with the Winter 07 release will continue to work with API version 9.0 on the Summer 07 release and on future releases beyond that. However, that same application may not work with API version 10 without modifications to the application.

API End-of-LifeSalesforce.com is committed to supporting each API version for a minimum of three years from the date of first release. In order to improve the quality and performance of the API, versions that are more than three years old may cease to be supported. When an API version is scheduled to be unsupported, an advance end-of-life notice will be given at least one year before support for the API version is ended. Salesforce.com will directly notify customers using API versions scheduled for end of life.

Choosing a WSDLThere are two Force.com Web services for which you can obtain WSDL files for API access: Force.com Enterprise WSDLThis API is for most enterprise users who are developing client applications for their organization. The enterprise WSDL file is a strongly typed representation of your organizations data. It provides information about your schema, data types, and fields to your development environment, allowing for a tighter integration between it and the Force.com Web service. This WSDL changes if custom fields or custom objects are added to, renamed, or removed from, your organizations Salesforce configuration. If you are downloading an enterprise WSDL and you have managed packages installed in your organization, you need to take an extra step to select the version of each installed package to include in the generated WSDL. Note the following when generating the enterprise WSDL: If new custom fields or objects are added to, renamed, or removed from your organizations information, you need to regenerate the WSDL file in order to access them. The generated WSDL contains the objects and fields in your organization, including those available in the selected versions of each installed package. If a field or object is added in a later package version, you must generate the enterprise WSDL with that package version to work with the object or field in your API integration. Force.com Partner WSDLThis API is for salesforce.com partners who are developing client applications for multiple organizations. As a loosely-typed representation of the Salesforce