Sforce API Reference Manual

sforce Web Services
API Reference
Version 2.0
Last Update: July 16, 2003
Copyright© 2002-2003 SalesForce.com, Inc. All rights reserved.
sforce API
Ta ble of Contents
List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
Chapter 1: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Supported Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Supported Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
General Form of the sforce API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
XML-RPC Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
SOAP Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Chapter 2: sforce API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Requirements for All Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
The login Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
The logout Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
The global describe Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
The describe Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
The insert Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
The update Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
The delete Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
The query Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
The batch Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
The search Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
The set_password Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
The reset_password Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
The get_server_timestamp Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Chapter 3: Protocol Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Variable-Length Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Unicode and Character Encoding Support . . . . . . . . . . . . . . . . . . . . . .27
Use of XML-RPC Fault Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
XML Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Use of Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Use of Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Client Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Chapter 4: Multiple Instance Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

XML-RPC Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
SOAP Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Chapter 5: Field-Specific Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Field-Level Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Numeric Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Enumerated Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Date/Time Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Custom Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Owner Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Currency Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
The ID Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Cross-Reference ID Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page i

sforce API
Long Text Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

SystemModstamp Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Chapter 6: Entity-Specific Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
AccountShare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Attachment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Campaign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
CampaignMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
CaseComment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
CaseHistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
CaseSolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
CustomFieldDefinition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
GroupMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Lead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Opportunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
OpportunityContactRole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
OpportunityLineItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
OpportunityLineItemSchedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
OpportunityShare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
OpportunityTeamMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Partner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
PriceBook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
ProfileRecordType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
RecordType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
RecordTypePicklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
UserTeamMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Chapter 7: Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Rate Limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Streaming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Batching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
HTTP Persistent Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
HTTP Chunking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Appendix A: Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Appendix B: Entity Relationship Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Major Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Task and Event Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Support Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Document, Note, and Attachment Entities . . . . . . . . . . . . . . . . . . . . .74
User, Record Types, and Custom Field Entities . . . . . . . . . . . . . . . . . .74
Product and Schedule Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page ii

sforce API
Sharing and Team Selling Entities . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Appendix C: Fault Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

HTTP, XML, and XML-RPC Level Faults . . . . . . . . . . . . . . . . . . . . . . . .79
HTTP Headers and XML-RPC Parameter Faults . . . . . . . . . . . . . . . . . . .79
Argument Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
User-Level Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
Fault Codes Common to Specific Calls . . . . . . . . . . . . . . . . . . . . . . . .82
Appendix D: XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

login Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
logout Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
global describe Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . .87
describe Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
insert Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
update Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
delete Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
query Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
batch Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
search Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
set_password Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . 112
reset_password Call XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . 113
get_server_timestamp Call XML-RPC Examples . . . . . . . . . . . . . . . . . 114
Appendix E: SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

login Call SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
describe Call SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
insert Call SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
update Call SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
delete Call SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
query Call SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
batch Call SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
search Call SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
set_password Call SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 126
reset_password Call SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . 127
get_server_timestamp Call SOAP Examples . . . . . . . . . . . . . . . . . . . 128
Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page iii

sforce API
List of Tables
Table 1: List of sforce API Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

Table 2: Supported Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Table 3: Supported Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Table 4: Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Table 5: SOAP Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Table 6: SOAP Response Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Table 7: Standard Arguments for All sforce API Calls . . . . . . . . . . . . . . . . . . . 5
Table 8: Standard Arguments for All Calls except the login Call ........... 5
Table 9: login Request Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Table 10: login Response Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Table 11: global describe Response Members . . . . . . . . . . . . . . . . . . . . . . . . 7
Table 12: describe Response Members ............................ 7
Table 13: “fields” Substructure Members . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Table 14: “display” Substructure Members . . . . . . . . . . . . . . . . . . . . . . . . . 10
Table 15: describe Request Members for Page Layouts . . . . . . . . . . . . . . . . 12
Table 16: describe Response Members for Page Layouts . . . . . . . . . . . . . . . 12
Table 17: “section” Substructure Members . . . . . . . . . . . . . . . . . . . . . . . . . 13
Table 18: “components” Substructure Members . . . . . . . . . . . . . . . . . . . . . 13
Table 19: “display” Substructure Members for Page Layouts . . . . . . . . . . . . 14
Table 20: insert Request Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Table 21: insert Response Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Table 22: update Request Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Table 23: update Response Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Table 24: query Request Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Table 25: “filter” Substructure Members for Equality Comparisons . . . . . . . . 20
Table 26: “operator” Substructure Members for Equality Comparisons . . . . . . 20
Table 27: “filter” Substructure Members for AND or OR Filters . . . . . . . . . . . 21
Table 28: “filter” Substructure Members for NOT Filters . . . . . . . . . . . . . . . . 21
Table 29: batch Request Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 30: search Request Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Table 31: set_password Request Members . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 32: reset_password Request Members . . . . . . . . . . . . . . . . . . . . . . . 25
Table 33: Illegal XML Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Table 34: Allowable HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 35: describe Attributes that Enforce Numeric Field Bounds . . . . . . . . . 32
Table 36: Additional Members for currencyISOCode Picklist Fields . . . . . . . . 36
Table 37: Codes to Determine Entity Type . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table 38: AccountShare Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Table 39: Attachment Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Table 40: Case Comment Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Table 41: CaseHistory Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page iv

sforce API
Table 42: CaseSolution Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Table 43: CustomFieldDefinition Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Table 44: Document Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Table 45: Folder Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Table 46: Group Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Table 47: GroupMember Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Table 48: Fields on Converted Leads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Table 49: Additional “value” Members for Opportunity Stage . . . . . . . . . . . . 52
Table 50: Allowable type Values for Opportunity Line Item Schedules . . . . . . 56
Table 51: Allowable quantity and revenue Values for Line Item Schedules . . . 57
Table 52: OpportunityShare Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Table 53: OpportunityTeamMember Fields . . . . . . . . . . . . . . . . . . . . . . . . . 59
Table 54: Partner Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Table 55: Default Schedule Fields on Products . . . . . . . . . . . . . . . . . . . . . . 62
Table 56: ProfileRecordType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Table 57: RecordType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Table 58: RecordTypePicklist Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Table 59: UserTeamMember Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Table 60: HTTP, XML, and XML-RPC Fault Responses . . . . . . . . . . . . . . . . . . 79
Table 61: HTTP Headers and XML-RPC Parameter Fault Responses . . . . . . . . 79
Table 62: Argument-Level Fault Responses . . . . . . . . . . . . . . . . . . . . . . . . 80
Table 63: User-Level Fault Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Table 64: Common login Fault Responses . . . . . . . . . . . . . . . . . . . . . . . . . 82
Table 65: Common insert Fault Responses . . . . . . . . . . . . . . . . . . . . . . . . . 83
Table 66: Common update Fault Responses . . . . . . . . . . . . . . . . . . . . . . . . 83
Table 67: Common delete Fault Responses . . . . . . . . . . . . . . . . . . . . . . . . 83
Table 68: Common query Fault Responses . . . . . . . . . . . . . . . . . . . . . . . . . 84
Table 69: Common batch Fault Responses . . . . . . . . . . . . . . . . . . . . . . . . . 84
Table 70: Common search Fault Responses . . . . . . . . . . . . . . . . . . . . . . . . 84
Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page v

sforce API
Re vision Histor y
List of sforce API Revisions

Date API Version Revisions
July 2003 2.0 • Added information about the systemModstamp field; see SystemModstamp Fields
on page 38.
• Added the URL for SOAP login calls to Requirements for All Calls on page 5.
• Added a sample set of HTTP headers; see Use of Headers on page 29.
June 2003 2.0 • New sharing model entities - The API now contains several entities for
representing account and opportunity sharing:
• accountShare entity - See AccountShare on page 39.
• opportunityShare entity - See OpportunityShare on page 57.
• group entity - See Group on page 50.
• groupMember entity - See GroupMember on page 51.
• New team selling entities - The API now contains new entities to represent the
team selling functionality of the salesforce.com user interface:
• opportunityTeamMember entity - See OpportunityTeamMember on page 59.
• userTeamMember entity - See UserTeamMember on page 67.
• New group entities - The API has two new entities to represent groups:
• group entity - See Group on page 50.
• groupMember entity - See GroupMember on page 51.
• New case entities - The API has two new entities to describe information about a
case:
• caseSolution entity - See CaseSolution on page 45.
• caseHistory entity - See CaseHistory on page 44.
• Other new entities - The following new entities are also included in version 2.0:
• document entity - See Document on page 47.
• folder entity - See Folder on page 49.
• customFieldDefinition entity - See CustomFieldDefinition on page 45.
• New entities for multiple business processes and record types - The API
supports new functionality that lets organization’s define different sets of picklist
values for different users:
• profileRecordType entity - See ProfileRecordType on page 63.
• recordType entity - See RecordType on page 63.
• recordTypePicklist entity - See RecordTypePicklist on page 64.
• Campaign entity no longer read-only - You can now insert, update, delete, and
query all standard and custom fields for a campaign. See Campaign on page 42
for more information.
• New get_server_timestamp call - The API has a new call that gives you the
exact time on the sforce API server. See The get_server_timestamp Call on
page 26 for more information.
• Unique IDs for all entities - All entities now have unique IDs. See The ID Fields
on page 36 for more information.
See the following page for more new features and enhancements.
Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page vi

sforce API

June 2003 2.0 • New case-insensitive ID support - The API can now return either a case-
(continued) (continued) sensitive or a case-insensitive id field value. See The ID Fields on page 36 and
Cross-Reference ID Fields on page 37 for more information.
• Auto-insert-or-update - For certain types of entities, the API will automatically
perform an update when you attempt an insert of a record that already exists. See
The insert Call on page 15 for more information.
• SOAP single login server - The SOAP API now provides a single login server to
access all worldwide sforce instances. See Multiple Instance Support on page 31
• batch call now available for SOAP - See The batch Call on page 22 for more
information.
• New advanced search option for search call - See The search Call on page 23
• New operators for “filter” parameter of query call - The “filter” parameter of
the query call now includes “greater than or equals” and a “less than or equals”
operators. Also in API versions 2.0 and higher, the “greater than” and “less than”
operators perform accurate greater than or less than comparisons. See The query
Call on page 19 for more information.
• New describe response members for record types - The “picklistName,”
“recordTypes,” and “recordTypeMappings” members give record type information
for picklist fields. See The describe Call on page 7 for more information.
• Updating case comments - The published field on case comments can now be
updated via the API. See CaseComment on page 44 for more information.
• Activating and deactivating users - You can now set a user’s active flag via the
API. See User on page 66 for more information.
• New requirement for username field - The username field for a user must be in
the form of an email address. See Username Field on page 66 for more
information.
• Empty cross-reference IDs - For cross-reference fields that are empty, the API
now returns an empty value rather than '000000000000000.’ See Cross-
Reference ID Fields on page 37 for more information.
June 2003 1.9 • The SOAP API in versions 1.9 and above requires that all custom field names be
prefixed with the string “cf_” in both requests and responses. See Custom Fields
May 2003 1.8 • The SOAP API can accept Date/Time types of dateTime or dateTime.iso8601.
Previously, only “dateTime.iso8601” was recognized as a valid Date/Time type.
See Date/Time Fields on page 33 for more information.
• The API includes two new calls that allow you to set a user’s password. See The
set_password Call on page 25 and The reset_password Call on page 25 for more
information.
• When filtering on fields that have a value of “id” or “reference” for the “type”
member of the “display” substructure in the describe response, the only valid
“operator” value is “equals.” See The query Call on page 19 for more information.
• The API now supports account partners and opportunity partners. See Partner on
• The HTTP header “RateLimitAdd” can be used to simulate rate limit conditions. See
Simulating Rate Limit Conditions on page 69.
Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page vii

sforce API

April 2003 1.8 • The sforce Entity Relationship Diagram has been added to the appendices. See
Entity Relationship Diagrams on page 74.
• The documentation has been updated to clarify that SOAP requests can be sent to
a secure or insecure URL. See SOAP Implementation on page 31 in the Multiple
Instance Support chapter for more information.
• Inserting and updating opportunity line items now does verification checking
against the price book on the opportunity. See Effects on Opportunities on
• The section about campaign members has been augmented to clarify how the
status field and responded flag are affected in an insert or update. See
CampaignMember on page 42 for more information.
• Appendix C now includes an example of an XML-RPC search call. See search Call
XML-RPC Examples on page 111 for more information.
February 1.8 • The API now supports attachments. See Attachment on page 41 for more
2003 information.
• The API now supports case comments. See CaseComment on page 44 for more
information.
• Archived tasks and events are not accessible via the API. See Archived Activities
• The API now supports custom fields, page layouts, and field-level security for
tasks and events. See Custom Fields and Page Layouts on page 49 for more
information.
• New dueDateTime and dueDateOnly fields contain due date information for tasks
and events. See Event on page 48 and Tasks on page 66 for more information.
• All Day date/time fields are obsolete as of version 1.8. See Date/Time Fields on
• The API now supports quantity-based annuity schedules, in addition to the
existing revenue schedules.
• The hasSchedule field has been replaced by the hasQuantitySchedule and
hasRevenueSchedule fields. See OpportunityLineItem on page 54 for more
information.
• Opportunity line item schedules have been augmented to support the new
quantity schedules. See OpportunityLineItemSchedule on page 56 for more
information.
• Quantity and revenue schedules can be turned on and off at the product level
via the new revenueScheduleEnabled and quantityScheduleEnabled flags.
See Product on page 61 for more information.
September 1.7 • The API search call supports a subset of the search functionality available in the
2002 Web-based application. See The search Call on page 23 for more information.
• The API now supports a SOAP implementation. See SOAP Implementation on
• The opportunityContactRole entity has been added to the API. See
OpportunityContactRole on page 54 for more information.
• The describe call can now provide page layout information for a user on an entity.
See Page Layout Information on page 11 for more information.
Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page viii

sforce API

May 2002 1.6 • All numeric custom fields are now handled as type “double.” See Numeric Fields on
• The top level structure of the describe response is now a struct or a map. See
The describe Call on page 7 for more information.
• The API now rejects insert and update calls that have extra field values. See The
insert Call on page 15 and The update Call on page 16 for more information.
• The API now provides a single login server to access all worldwide sforce
instances. See Multiple Instance Support on page 31 for more information.
• You can now update the Owner field for all major entities via the API.
• The API now enforces field-level security as specified in the page layouts. See
Field-Level Security on page 32 for more information.
• Display types for percent, text area, and date/time fields are now explicitly
indicated.
Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page ix

sforce API Chapter 1: Overview
CHAPTER 1: O v er v ie w
The sforce API documentation provides the information necessary to access the sforce API. The
API provides a programmatic means of interacting with the sforce platform to access and change
data for the main entities represented in the sforce system. The sforce API is a Web service that
supports both XML-RPC and SOAP protocols.
Backwards- The API functionality described here applies to version 2.0 of the sforce API. Previous versions of
Compatibility the API may have slightly different behaviors.
SUPPORTED ENTITIES
You can use the sforce API to access and change the following entity types:
Table 1: Supported Entities

account opportunity
accountShare opportunityContactRole
attachment opportunityLineItem
campaign opportunityLineItemSchedule
campaignMember opportunityShare
case opportunityTeamMember
caseSolution partner
caseComment pricebook
caseHistory product
contact profile
customFieldDefinition profileRecordType
document recordType
event recordTypePicklist
folder role
group solution
groupMember task
lead user
note userTeamMember
The list of supported entities may change in the future. The global describe call returns a list of
supported entities (see The global describe Response on page 7). Some of the entities may not
be accessible to a particular user, depending on the organization’s and user’s permissions.
See Also:
Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page 1

Entity-Specific Issues on page 39
SUPPORTED OPERATIONS
Table 2: Supported Operations

Operation Description
login Start a session
logout Finish a session
describe Obtain a description of each entity, including the list of fields and
their attributes. Also, obtain a list of the valid entity types and
other global information.
Clients may not need to make a describe call if they know the
entities and columns they want to access.
insert Create a new record with the specified information
update Modify an existing record
delete Delete an existing record
query Retrieve specified fields for record that meet specified criteria.
The query call has different scopes that determine the type of
criteria you can specify.
batch Perform multiple insert, update, or delete operations in one call
search Search for entities based on specified keywords
set_password Set a user’s password to a specified value
reset_password Reset a user’s password to a server-generated value
get_server_timestamp Obtain the exact time from the API server
See Also:
Chapter 2: sforce API Calls on page 5
GENERAL FORM OF THE SFORCE API

Each API call is initiated by a request from a client and has a response from the server. API calls
are never initiated from the server to the client. Each API call has a method name, which is one
of the operations described in Supported Operations on page 2.
The sforce API allows you to encode calls using either SOAP (Simple Object Access Protocol) or
XML-RPC, a simple RPC mechanism encoded in XML.
See Also:
XML-RPC Implementation on page 2
SOAP Implementation on page 3
XML-RPC IMPLEMENTATION
The sforce API allows you to encode your calls using XML-RPC. XML-RPC is “Remote Procedure
Calling” using HTTP and XML encoding. It is a simple mechanism that allows the transfer of
complex data structures. See www.xmlrpc.org for a detailed description of XML-RPC, and in

particular, see www.xml-rpc.org/spec for the specification that essentially forms the DTD for
XML-RPC.
For XML-RPC calls, the method name is preceded by “sfdc.” For example, the method name to
insert an entity is sfdc.insert. Each XML-RPC call always uses exactly one argument, which is a
struct of name-value pairs. A response is always either a single value (which could be a struct or
an array), or a fault response that contains a fault code and fault message.
Each call must be made to an sforce application server hostname with a servlet name of
servlet/servlet.Api. See Chapter 4: Multiple Instance Support on page 31 for more information
about the URL to which calls should be made.
The sforce API uses several enhancements to the base XML-RPC specification. Those
enhancements are detailed in Chapter 3: Protocol Description on page 27.
SOAP IMPLEMENTATION
The sforce API allows you to encode your calls using SOAP. SOAP (Simple Object Access
Protocol) is an XML-based protocol for exchanging information. See www.w3.org/TR/SOAP/ for a
detailed description of SOAP.
All of the supported operations are available in the SOAP implementation. See Supported
Operations on page 2.
Each SOAP call must be made to an sforce application server hostname with a servlet name of
servlet/servlet.SoapApi. See Chapter 4: Multiple Instance Support on page 31 for more
information about the URL to which calls should be made.
This section outlines the high-level SOAP specification for the sforce API. See the sforce WSDL at
http://www.sforce.com/us/docs/sforce.wsdl for a more technical specification.
SOAP Namespaces
SOAP uses different namespaces for different elements and attributes depending on the role that
the data plays in the message formatting, handling, or encoding. The namespaces reflect how all
data type definitions in SOAP are delegated to XML schema. The sforce API uses the following
namespaces:
Table 3: Namespaces
Namespace Value
name salesforce.com
targetNameSpace salesforce.com
xmlns:tns salesforce.com
xmlns http://schemas.xmlsoap.org/wsdl/
xmlns:soap http://schemas.xmlsoap.org/wsdl/soap/
xmlns:xsd http://www.w3.org/2001/XMLSchema
xmlns:wsdl http://schemas.xmlsoap.org/wsdl/
xmlns:SOAP-ENC http://schemas.xmlsoap.org/soap/encoding/

SOAP Data Types

Sforce uses several standard and custom types for its SOAP implementation, including:
Table 4: SOAP Data Types

Type Description
array An array of any type
ArrayOfString An array of type string
headerStruct A header element that contains request information. It has the following
elements:
• session_id - Contains the string value of the session ID.
• version - Contains the string value of the client/API version.
mapEntry A name-value pair containing these elements:

• key - the name
• value - the value
map An array of mapEntry elements
SOAP Response Types

The following response types are returned for each sforce API call:
Table 5: SOAP Response Types

Call Response Type
login tns:array
logout tns:array
describe tns:array
insert tns:array
update tns:array
delete xsd:string
query tns:array
search tns:array

sforce API Chapter 2: sforce API Calls
CHAPTER 2: sforce AP I Ca l l s
REQUIREMENTS FOR ALL CALLS

All sforce API calls must be contained in an HTTP request with appropriate HTTP headers. Each
XML-RPC login call must be made to the URL: https://www.salesforce.com/servlet/
servlet.Api, and each SOAP login call must be made to the URL: https://
www.salesforce.com/servlet/servlet.SoapApi. Note that the insecure versions of these
URLs are also supported - http://www.salesforce.com/servlet/servlet.Api and http://
www.salesforce.com/servlet/servlet.SoapApi. Subsequent calls are made to the URL returned by
the login call (see Chapter 4: Multiple Instance Support on page 31 for more information).
All sforce API calls require the following standard arguments:
Table 6: Standard Arguments for All sforce API Calls

Argument Description
HTTP headers Each call requires HTTP header fields for Content-Type and Content-
Length.
version Specifies the sforce API version. The current version is 2.0.
All calls, except the login call, also require an authenticated session and the following standard
set of arguments:
Table 7: Standard Arguments for All Calls except the login Call
Argument Description
session ID A valid session ID as returned by the login call. This ID must be passed
using the HTTP header “Cookie” in all subsequent calls in the current
session.
type A valid entity type as returned by the global describe call, or a special
keyword as defined in the description for each call.
Partner Solutions
For Partner solutions (i.e., product extensions), an additional parameter is required to identify
the API request as coming from an approved (SFDC Ready) solution. All sforce API requests from
partners must have:
• A valid User-Agent HTTP header. The User-Agent must match a list of valid User-Agent
values. Check with the sforce API team to obtain a valid User-Agent value for your
application.
• A “client name” argument for each call to the sforce API. The “client name” argument is
similar to the User-Agent header; it must match a valid list obtained from salesforce.com.
Only approved product extensions require the User-Agent header and “client name” parameter.
It is ignored in all other circumstances.

T HE LOGIN CALL
The login call takes a username and password and validates them. To access an organization via
the sforce API, you must first authenticate the session via a login request. Each login call must
be made to the URL: https://www.salesforce.com/servlet/servlet.Api (note that the
insecure version of the URL is also supported - http://www.salesforce.com/servlet/servlet.Api).
In addition to the Content-Type and Content-Length headers, the login request requires the
following arguments:
Table 8: login Request Members

Member Description
username sforce username of the user
password Password of the user
version sforce API version number
secure Boolean. Specifies whether the login response should return a secure
URL in the “server_url” member. In API versions 2.0 and later, if the
“secure” parameter is not specified, the response sends a secure URL by
default.
A successful response to the XML-RPC login call is a struct. A successful response to the SOAP
login call is an array. The login call returns the following members:
Table 9: login Response Members

Member Description
session_id Session ID for all subsequent requests in the session. This value should
be passed in the HTTP cookie header or SOAP request in all future API
requests in this session. IDs are case-sensitive.
server_url Specifies the URL for the instance on which the organization resides. All
future requests to the API in this session must be sent to this URL. The
URL may or may not be secure, depending on the value of the “secure”
member in the request. In API versions 2.0 and later, if the “secure”
parameter is not specified, the response sends a secure URL by default.
userID The ID of the user
See Also:
Chapter 4: Multiple Instance Support on page 31
login Fault Codes on page 82
login Call XML-RPC Examples on page 86
login Call SOAP Examples on page 115
T HE LOGOUT CALL
The logout call does not require any arguments beyond the basic set (see Requirements for All
Calls on page 5).
See Also:
logout Fault Codes on page 82
logout Call XML-RPC Examples on page 87

T HE GLOBAL DESCRIBE CALL

The global describe call returns a list of valid entity types and other information. To send a
global describe call, you must specify the describe call with the additional “type” value of
“global.”
The global describe Response

When you send a describe request with a “type” value of “global,” the sforce API returns a
response with the following members. The global describe response can vary based on the
organization and user permissions, and the instance it is performed on.
Table 10: global describe Response Members

Member Description
types Provides an array of the valid entity types for other sforce API calls. This
list may change in the future if more entities are added. It may also be
different for different users and organizations.
maxBatchSize The maximum array size allowed for the batch call.
encoding The supported character encoding, either ISO-8859-1 or UTF-8.
See Also:
global describe Call XML-RPC Examples on page 87
T HE DESCRIBE CALL
The describe call is used to obtain metadata about entity types, page layouts, and global
metadata. You can use the describe call with a specific entity type to get a list of standard and
custom fields, their attributes for that entity type, and the page layout information for that entity
type.
The describe Request

The describe request uses the standard set of arguments (see Requirements for All Calls on
page 5). For details on requesting page layout information, see Page Layout Information on
page 11.
The describe Response

Top-level The top-level structure of a standard XML-RPC describe response is a struct with the following
members. The top-level structure of a standard SOAP describe response is an array with the
describe
following members. For details about additional page layout members, see Table 15: describe
Members Response Members for Page Layouts on page 12.
Table 11: describe Response Members

Members Description
fields For XML-RPC: An array of structs in which each struct represents a field
for the entity type. The struct for each field may contain some or all of
the members listed in Table 12: “fields” Substructure Members on
page 8.
For SOAP: An array of maps in which each map represents a field for the
entity type. The map for each field may contain some or all of the
members listed in Table 12: “fields” Substructure Members on page 8.

Table 11: describe Response Members

Members Description
access An array of access rights for the user on the entity type. This specifies
the maximum access rights that the user has for that entity type, as
restricted by their profile and by the restrictions inherent in sforce.
The array contains a set of these values:
• query - Always present for entities that are accessible via the API.
• insert - User has access to create the entity type.
• update - User has access to modify the entity type.
• delete - User has access to delete the entity type.
• search - User has access to search the entity type.
• idList - User can use a list of IDs to query the entity type.
•
“fields” Each field struct or map in the “fields” member array may contain some or all of the following
Substructure members to describe the field:
Members Table 12: “fields” Substructure Members
Member Description
field The canonical name of the field. This name must be used in insert,
update, and query calls to refer to the field. The value is unique for all
fields on this entity type, is always simple ASCII, and does not change
over time.
The names for the standard fields are the same across organizations,
even organizations using different languages or locales. The name for
each standard field is in English, although custom fields have names that
are not meaningful. In the SOAP API versions 1.9 and above, the custom
field names are prefixed with “cf_”.
For user displays, you usually want to use the “label” member for that
field.
access Indicates access restrictions on the field. If this member is absent, the
user has all permissions for that field without restriction. If it is present,
its value is an array containing one or more of the following values:·
• select - The field can be specified in the select list of a query call.
• filter - The field can be specified in the filter list of a query call.
• insert - The field can be specified in an insert call.
• update - The field can be specified in an update call.
type The type of the field. The value is one of the following types:
• string
• i4
• double
• Boolean
• dateTime (or dateTime.iso8601 in XML-RPC)
label The localized label for the field. This may be non-unique, even within an
entity type. It may contain the full range of Unicode characters, and it
may change over time.
length For string fields, the maximum size of the field in Unicode characters, not
bytes.

Table 12: “fields” Substructure Members

Member Description
custom Indicates that this is a custom field. Clients of the sforce API normally do
not need to know whether a field is a standard field or a custom field for
the organization, but they can determine it if they want by checking for
this member. If present, the value is always Boolean ‘1’. Custom fields
also have a unique field ID, rather than an English-readable ID name. In
the SOAP API versions 1.9 and above, this unique field ID is prefixed with
“cf_”.
referenceTo For fields that refer to other entities, this value is the type of the entity to
which the field refers. If the value is a string, then the value is an entity
type name, which must be one of the names returned by the global
describe call. If the value is an array of strings, then each string is an
entity type name, and the value of the field on an entity can be any of
those types. See Cross-Reference ID Fields on page 37 for more
information.
nullable Indicates whether the field must have a value. If this member is present
and contains the Boolean value ‘0’, the field must have a value. On
insert, the client must provide a value, or the insert is rejected. On
update, the record must already have a value, so the client is not
required to provide a value, but the client cannot null out a field that is
marked as non-nullable.
display A struct or a map that contains additional information about the field,
primarily for display purposes. See Table 13: “display” Substructure
Members on page 10 for the list of “display” members.
restricted If this member is present and contains the Boolean value ‘1’, the values
for the field are restricted to the set of values listed in the “values”
member of the “display” substructure. See Table 13: “display”
Substructure Members on page 10.
picklistName An English-descriptive name for a picklist field. This member is returned

only for fields of “type” picklist (as specified in the “display” substructure
of the describe response; see “display” Substructure Members on
page 10).
The value of the “picklistName” member corresponds to the field field in
the recordTypePicklist entity. You can use the value of the “picklistName”
member to query the field field in the recordTypePicklist entity to
determine which picklist values are valid values for a particular record
type. See RecordTypePicklist on page 64 for more information.
Alternatively, you can specify the “layout” member of the describe
request to obtain the valid values for record types from the “recordTypes”
and “recordTypeMappings” members. See Page Layout Information on

“display” The “display” member of the “fields” struct or map can contain the following members. For
details about additional page layout members, see Table 18: “display” Substructure Members for
Substructure Page Layouts on page 14.
Members
Table 13: “display” Substructure Members
Member Description
type Additional information about the type of the field. This can have these
values:
• id - The field is the primary key field for this entity.
• reference - The field is a cross-reference field that refers to a
different entity. See the “referenceTo” member described in Table 12:
“fields” Substructure Members on page 8.
• picklist - The field has a list of values. The field may be restricted to
those values, as indicated by the “restricted” member of the “fields”
array for the field. See also the “values” member in this table.
• percent - The field contains percentage values. It is specified for all
percentage fields.
• currency - The field contains currency values. For multi-currency
organizations, the currencyISOCode field indicates the currency for
this entity. If the currencyISOCode field is changed, the currency field
values will automatically be changed to reflect the conversion to the
new currency.
• phone - The field contains a phone number. Note that phone numbers
may contain any valid string character, not just numeric characters.
Also, the salesforce.com user interface formats phone numbers when
they are entered via a browser. The sforce API, however, does not
automatically format phone numbers. You should specify phone
numbers via the API with any necessary formatting.
• email - The field contains an email address. Email addresses are
forced to lowercase upon saving.
• url - The field contains a URL. These fields should commonly be
displayed as hyperlinks.
• textarea - The field is a string field that should be displayed as a
multi-line text field.
• date - The field is a dateTime field (represented as a
dateTime.iso8601 type in XML-RPC), but is used internally as a date-
only value with no time portion. The time portion of the field is
ignored, and no time zone conversion is done.
• allday -The allday field is obsolete as of sforce API version 1.8. Older
versions of the API continue to support it. The field is a dateTime field
(represented as a dateTime.iso8601 type in XML-RPC), but the time
must fall on midnight in the entity owner's local time zone. Normally,
this restriction is difficult for external applications to model. The value
specified for the field is automatically truncated to the appropriate
time, after applying the time zone conversion.
• datetime - The field is a dateTime field (represented as a
dateTime.iso8601 type in XML-RPC) that is a regular date/time field,
as opposed to “dateonly” fields.
precision For fields of type double, the “precision” and “scale” indicate the numeric
scale limits of the field.
• The “precision” is the maximum number of digits that can be stored,
including all numbers to the left and right of the decimal point.
• The “scale” indicates the number of digits to the right of the decimal
point.
The server silently truncates any extra digits to the right of the decimal
point, but it returns a fault response if the number has too many digits to
the left of the decimal point.

Table 13: “display” Substructure Members

Member Description
digits For fields of type integer, this indicates the maximum number of digits.
The server returns a fault response if the number has too many digits.
values For fields of “type” picklist, this is an array of the predefined values. If
the field has a value of ‘1’ in the top level “restricted” member, then only
those values are allowed. If the “restricted” member is absent or has the
value ‘0’, then the values are suggested values, but any other value is
acceptable, as long as it meets the maximum field length restrictions.
Each element of the “values” array is a struct or a map with the following
members:
• value: Each element always has a “value” member, indicating the
allowed or suggested value.
• label: Each element may have a “label” member, indicating the
preferred display label value.
• default: At most one element may have a “default” member. If
present, its value is always the Boolean value ‘1’. It indicates that this
element is the default value.
The “values” array for some fields may have additional members that
indicate additional information about each value. See Chapter 6: Entity-
Specific Issues on page 39 for details about specific fields.
If an organization is using record types, you can use the value of the
“picklistName” member (see “fields” Substructure Members on page 8)
to query the field field in the recordTypePicklist entity to determine
which picklist values are valid values for a particular record type. See
RecordTypePicklist on page 64 for more information. Alternatively, you
can specify the “layout” member of the describe request to obtain the
valid values for record types from the “recordTypes” and
“recordTypeMappings” members. See Page Layout Information on
Page Layout Information

The describe call optionally provides page layout information for a user on an entity. The page
layout information is used to create the detail and edit pages for the user in the salesforce.com
user interface. You can use the layout information from the sforce API to construct pages similar
to the salesforce.com user interface pages, such as in an offline device. You can also use a
subset of the layout information to provide a partial layout, such as specifying the order of the
fields.
The layout information does not alter how the rest of the sforce API functions. Specifically, the
additional layout information does not provide information that is necessary to call the insert,
update, or delete methods for an entity.
Each display and edit page in the user interface is divided into sections. A section is typically
comprised of a visual section break indicator, a section label, and a list of fields for that section,
in either one or two columns. The fields in any column of a section are ordered in the same order
on both the detail and edit page. On detail pages, some consecutive fields are combined into one
field for display, e.g., name and address fields. The merging of fields is not done for edit pages.
For this reason, the detail page and the edit page for the same entity may have a different
number of rows for display, and the horizontal alignment of the fields may be different from the
display page to the edit page.
Page layouts also impose field-level security on detail and edit pages. See Field-Level Security on

NOTE In sforce API versions 1.6 and higher, page layout information is available for campaigns, leads,
accounts, contacts, opportunities, and cases. In API versions 1.8 and higher, page layout
information is also available for task and event entities.
describe To receive page layout information, the following parameter must be added to the describe
Request request:
Members for Table 14: describe Request Members for Page Layouts
Page Layouts
Member Description
layout Optional Boolean parameter. If the value is ‘1’, the response returns
page layout information for that entity type. Page layout information is
not available unless you also specify a “version” of 1.6 or greater.
Top-level When you request page layout information via the “layout” parameter, the top-level structure of
describe a describe response includes the following additional members:
Response Table 15: describe Response Members for Page Layouts
Members for
Page Layouts Members Description
sections An array of structs or maps containing page layout information about the
section headers for detail and edit pages. Each element represents a
section that contains the members listed in Table 16: “section”
Substructure Members on page 13. The “section” parameter is contained
in the response only if you specify “layout” with a value of ‘1’ in the
describe request.
components An array of structs or maps containing page layout information about

which fields are merged for display purposes on detail pages. Each
element represents a set of fields that should be merged. Each element
contains the members listed in Table 17: “components” Substructure
Members on page 13.
The “components” member is included only for those entities that have
fields that are grouped into components. The fields that are currently
grouped are:
• salutation, firstName, and lastName - These fields are merged into
a single fullname component for display.
• various address fields - These fields are merged into an address
component for display.
The “components” parameter is contained in the response only if you
specify “layout” with a value of ‘1’ in the describe request.
recordTypes An array of structs containing the active and inactive record types for an
entity. The following members are returned for every record type:
• id - The ID of the record type.
• name - The name of the record type.
• available - Boolean. Indicates whether the record type is available to
the user.
• default - Boolean. Indicates whether the record type is available to
the user.
• description - The description of the record type.

“section” The “section” member of the top-level describe response contains page layout information in
Substructure the following members:
Members for Table 16: “section” Substructure Members
Page Layouts
Member Description
label A label for the section in the page layout.
columns The number of columns the section contains in the page layout. The
value is either '1' or '2'. Sections should be the same width regardless of
whether they contain '1' or '2' columns. Fields in sections with 2 columns
should be about half as wide as fields in sections with only 1 column.
id A unique string identifier for the section in the page layout. This is used
in the “section” member of the “display” substructure of each field to
indicate the section for the field (see Table 18: “display” Substructure
Members for Page Layouts on page 14.)
type If present, this member indicates optional special handling for the section
in the page layout. Currently, this is only used to indicate the address
section, and it has the value “address”, if present. The address section
has special buttons to copy address values in some edit pages.
“components” The “components” member of the top-level describe response contains page layout information
Substructure in the following members:
Members for Table 17: “components” Substructure Members
Page Layouts
Member Description
id A unique string which identifies this component within this describe

response. This is used in the “componentOf” member of the “display”
substructure of each field to indicate component membership (see Table
18: “display” Substructure Members for Page Layouts on page 14).
label A label for the component in the page layout. This label should be used
on a display page in which the merged component is displayed instead of
each individual field.
displayFormat An array of elements that indicates how to merge the individual field
values in the page layout.
Each element will be a string or an integer. Each string value indicates a
component field ID, as specified by the “component” member of the
“display” substructure of each field (see Table 18: “display” Substructure
Members for Page Layouts on page 14. Each integer value indicates a
Unicode character code. The values of each field and the Unicode
characters should be concatenated to form the new display value for the
merged component.
The “displayFormat” currently contains a format appropriate for the
United States. It does not reflect the Locale setting of the user. In the
future, it will correctly provide a different response depending on the
Locale of the user.

“display” When you request page layout information via the “layout” parameter, the “display” member of
Substructure the “fields” struct or map includes the following additional members:
Members for Table 18: “display” Substructure Members for Page Layouts
Page Layouts
Member Description
section The page layout section to which this field belongs. The “section”
value should match the “id” value of one of the sections in the
“sections” array (see Table 16: “section” Substructure Members on
page 13). The field should be displayed in that section.
This member is contained in the response only if you specify
“layout” with a value of ‘1’ in the describe request.
tabOrder The tab order for this field in the page layout. It is expressed as an
integer. As the user tabs through the fields, the fields should be
selected in numerically ascending tab order. This order may be
different than the physical order of the fields.
column The column in which the field is located within the page layout
section. The value is an integer - ‘0' or '1'. Fields in sections with
only one column always have the value ‘0' for this member.
required Indicates that the field is required in the page layout of the user
interface. If present, this member will have the Boolean value '1'.
This value does not mean that the field is required in the database,
as is indicated by the “nullable” member that is also part of the
describe response. The sforce API does not enforce fields that are
marked as “required”, unless they are also marked as non-
nullable. Any user interface page should enforce a required field,
though. In some cases, it may be acceptable for the user interface
to not enforce the “required” attribute. It is also possible, although
very rare, for a field to be marked as non-nullable, but not
required. Most non-nullable fields are automatically marked as
required.
rows The number of rows the field should occupy in the page layout.
This member is present only for multi-line text fields. It indicates
how many rows of text should be displayed for this field on an edit
page. An individual field value may contain more or less rows than
the “rows” value indicates.
componentOf The section to which this field belongs in the page layout. The
“componentOf” value should match the “id” value of one of the
components in the “components” array, if this value is present (see
Table 17: “components” Substructure Members on page 13).

Table 18: “display” Substructure Members for Page Layouts

Member Description
component The component type of this field within the section of the page
layout. This is the component field ID, as used in the
“displayFormat” member of the “components” description (see
Table 17: “components” Substructure Members on page 13).
label An alternate display label for this field in the page layout, if any.
For many cross-reference fields, the normal display label includes
“ID” at the end, such as “Contact ID”. This is appropriate in
integration tools. Any user interface will typically want to resolve
the ID into a name for the associated entity, and then display that
value instead. This label is appropriate when that resolution is
done. For example, the normal label may be “Contact ID”, but the
layout label may be just “Contact.”
recordTypeMappings For fields of “type” picklist, this field contains an array of record
types and the predefined values for each. For each record type,
this field returns the record type ID and a struct or map containing
the following information:
• value: The allowed value for the record type picklist.
• default: At most one value may have a “default” member. If
present, its value is always the Boolean value ‘1’. It indicates
that this element is the default value.
NOTE Fields should be physically ordered in a page layout column in the order they are provided in the
describe response.
See Also:
describe Fault Codes on page 82
describe Call XML-RPC Examples on page 88
describe Call SOAP Examples on page 116
T HE INSERT CALL
The insert call is used to create a new entity of a specified type with specified values.
The insert Request

Beyond the normal “version” and “type” arguments (see Requirements for All Calls on page 5),
the insert call also requires the following:
Table 19: insert Request Members

Members Description
record A struct or a map with name-value pairs containing the data for the new
entity. The names in the struct or map must be field IDs, as returned by
the describe call for that entity. The values must be values of the type
specified for that field in the describe response.
During an insert, you do not need to specify all fields for that entity type. Most fields are
optional, except for those marked as required in the describe response, indicated by the

attribute “nullable” with the Boolean value ‘0’. Fields that are not specified are set to blank or to
default values. Fields that are too long are truncated.
If you send extra, unrecognized fields in the insert request, the sforce API rejects the call and
sends fault code 1236 “bad field names on insert/update call.” The API applies a strict definition
of unrecognized fields such that all fields in the call must be valid for the user for that operation.
For example:
• The API rejects calls that specify a value for a custom field that has been deleted or removed
from a user’s access.
• The API rejects calls that specify read-only fields.
Inserting Existing For some types of entities, if you try to insert a new record that already exists, the API does not
Records insert a new record. Instead, it updates any editable fields on the existing record. This applies to
the groupMember, accountShare, opportunityShare, userTeamMember, opportunityTeamMember,
and profileRecordType entities.
The insert Response

The response to an insert call is a struct or a map, or a fault response if there is an error. The
insert response struct or map may contain the following members:
Table 20: insert Response Members

Member Description
id The ID of the entity just inserted.
changed The value is a struct of name-value pairs or a map, indicating which

fields were modified as part of the insert operation. The name of each
member is the field ID that was specified in the insert. The value of each
member is the new value for that field.
added The value is a struct of name-value pairs or a map, indicating additional

fields that were assigned values based on some implicit condition of the
values that were specified. The name of each member is the field ID, and
the value is the new value for that field.
ignored The value is an array of strings or a map listing the valid field IDs that
were specified in the insert request but were ignored in the inserted
record because their value was implicitly overridden by another field
value or other condition.
trimmed The value is a struct of name-value pairs or a map listing the fields that
were truncated because their values were too long. This does not cause
an error. The name of each member is the field ID and the value is the
new truncated value for the field.
See Also:
insert Fault Codes on page 83
insert Call XML-RPC Examples on page 106
insert Call SOAP Examples on page 118
T HE UPDATE CALL
The update call is used to change the values of existing entities. The form of the call is very
similar to the insert call.

The update Request

Beyond the normal “version” and “type” arguments, the update request requires the following
arguments:
Table 21: update Request Members

Member Description
record A struct with name-value pairs or a map containing the data for the
updated entity. The names in the struct or map must be field IDs, as
returned by the describe call for that entity. The values must be of the
type specified for that field in the describe response.
id A required field of the “record” struct or map. Specifies a valid ID of that

entity type, as returned by an insert call or a query call.
During an update, you do not need to specify all fields for that entity type. You cannot update
fields to “null” if those fields are marked as required in the describe response, as indicated by
the attribute “nullable” with the Boolean value ‘0’. Fields that are not specified are not modified.
Fields that are too long are truncated.
For the fields that you specify in the update request, the user must have update rights to those
fields. Field access is indicated in the describe response; the “access” attribute must have the
“update” option. Note that some fields cannot be updated, even though they can be inserted.
If you send extra, unrecognized fields in the update call, the sforce API rejects the call and
sends fault code 1236 “bad field names on insert/update call.” The API applies a strict definition
of unrecognized fields such that all fields in the call must be valid for the user for that operation.
For example:
• The API rejects calls that specify a value for a custom field that has been deleted or removed
from a user’s access.
• The API rejects calls that specify read-only fields.
• The API rejects update calls that specify fields that can be inserted but not updated.
Note that some records are not editable by some users. This information is usually only known
once an update request is attempted. If the user does not have edit rights to that record, fault
code 1205 is returned.
The update Response

The response to an update call is a struct or a map, or a fault response if there is an error. The
response is the same as for an insert call:
Table 22: update Response Members

Member Description
id The ID of the entity just updated. This member is not very useful, as the
“id” was already specified in the update request.
changed The value is a struct of name-value pairs or a map, indicating which

fields were modified as part of the update operation. The name of each
member is the field ID that was specified in the update. The value of
each member is the new value for that field.
added The value is a struct of name-value pairs or a map, indicating additional

fields that were assigned values based on some implicit condition of the
values that were specified. The name of each member is the field ID, and
the value is the new value for that field.

Table 22: update Response Members

Member Description
ignored The value is an array of strings or a map listing the valid field IDs that
were specified in the update request but were ignored in the updated
record because their value was implicitly overridden by another field
value or other condition.
trimmed The value is a struct of name-value pairs or a map listing fields that were
truncated because their values were too long. This does not cause an
error. The name of each member is the field ID and the value is the new
truncated value for the field.
Setting Non-String Fields to Null

In an update call, a special format is needed to set non-string fields to null. XML-RPC has a
limitation that it does not provide a null value. For string fields, you can simply specify the value
as an empty string, which is equivalent to null. However, if you specify an empty value for a
date/time, integer, double, or Boolean field, the response returns fault code 0.
To set non-string field values to null, you need to specify a string value that is blank. For
example, to update the value of a double field to null, you would specify the value:
XML-RPC Example:
<string></string>
SOAP Example:
<amount type=string></amount>
This is a special exception to the rule that the field type of each value must match the field type
for that field. This special null value is available in the insert and update calls, although it is
rarely needed for the insert call.
Updating Currency Fields

Another special case concerns currency fields and the currencyISOCode field. The
currencyISOCode field is only available for organizations that are enabled for multi-currency
use. For multi-currency organizations, the currencyISOCode indicates the ISO currency code for
all currency values on that record. For example, if the currencyISOCode field has the value
“USD”, and a revenue currency field has the value 500.0, then the revenue field value is
interpreted as five hundred US dollars, and is usually displayed as USD 500.00. If you update the
currencyISOCode field to a different value, such as “GBP” (British pounds), the value of the
revenue field changes also, based on the conversion rate between USD and GBP. See Currency
Fields on page 35 for more details.
See Also:
update Fault Codes on page 83
update Call XML-RPC Examples on page 107
update Call SOAP Examples on page 119
T HE DELETE CALL
The delete call is used to delete an entity of the specified type. The entity is placed into the
recycle bin for the user and can be manually undeleted later. In addition to the normal “version”
and “type” parameters, the delete call requires only one parameter - the “id” parameter, which
contains the ID of the entity to delete.
The delete call always returns an empty response, or a fault response if there is an error.
See Also:
delete Fault Codes on page 83
delete Call XML-RPC Examples on page 107

delete Call SOAP Examples on page 120
T HE QUERY CALL
The query call allows you to obtain a list of entities that meet specified criteria, and to retrieve
specific fields for those entities. The query call has different scopes that determine the type of
criteria you can specify.
The query Request

In addition to the standard parameters, the query request also contains the following members:
Table 23: query Request Members

Member Description
scope A string value specifying one of the following predefined scopes:

• filter: Allows you to specify filter criteria to obtain a list of entities.
This scope is useful if you do not already know the IDs of the records
you want. If you use this “scope” value, you must also specify the
“filter” parameter.
• idList: Allows you to specify a list of record IDs. This scope is usually
faster, and is useful if you already know the record IDs you want. It is
often used after executing a search call, which returns a list of record
IDs. If you use this “scope” value, you must also specify the “idList”
parameter.
filter An array of filter criteria. The filter criteria can be a simple equality
comparison of a field to a fixed value (see Equality Comparison Filters on
page 20), or it can be any arbitrary combination of AND, OR, and NOT
Boolean statements comparing different fields to fixed values (see
Boolean Combination Filters on page 21).
The top-level filter criteria elements of the “filter” parameter must all
match for a record to be returned in the query response. In other words,
the top-level array of filter criteria are implicitly joined together by AND.
If you want to specify a filter that only has OR criteria, or only a NOT
criterion, then you must specify a single top-level filter criterion of that
type.
The “filter” parameter is required if you specify a “scope” value of “filter.”
The “select” parameter must be used in conjunction with the “filter”
parameter.
idList An array of IDs of a specific entity type. This parameter is used to make
a bulk ID query call.
The “idList” parameter is required if you specify a “scope” value of
“idList.” The “select” parameter must be used in conjunction with the
“idList” parameter.
select An array of strings in which each string is a valid field ID as returned by

the describe call for that entity type. The user must have “select”
privilege on the field, as indicated by the “access” attribute for that field
in the describe response for that entity type.
The “select” array must be specified and cannot be zero length if you
specify a “scope” value of “filter” or “idList.” If you want all fields
returned in the response, you must specify each of those fields.

Table 23: query Request Members

Member Description
maxRows An optional parameter that indicates the maximum number of records to

return. If “maxRows” is specified, the response is limited to that size. The
subset of records returned with the “maxRows” parameter is
indeterminate, and may change on subsequent requests with the same
query. You should only use the “maxRows” parameter if you want a
random sampling of records.
useCaseSafeIDs Available only in API versions 2.0 and higher. Boolean. An optional
parameter to specify that the query response should return 18 character
case-insensitive record IDs, rather than 15 character case-sensitive
record IDs. See The ID Fields on page 36 for more information.
Detailed Structure of “filter” Parameter

Equality For simple equality comparison filters in the “filter” parameter, each filter criterion is a struct or a
Comparison map with the following members:
Filters Table 24: “filter” Substructure Members for Equality Comparisons
Member Description
field A string value containing a valid field ID to which the user has filter
privileges, as indicated by the “access” attribute in the describe
response for that entity type.
value A value of the appropriate type for the field, as indicated by the describe
response.
operator Optional parameter that contains the members specified in Table 25:
“operator” Substructure Members for Equality Comparisons on page 20.
The “operator” member of the “filter” parameter is optional and can have one of the following
possible values:
Table 25: “operator” Substructure Members for Equality Comparisons

Values Description
equals The default value, if the “operator” member is not specified. The “field”
must equal the “value.” For normal string fields, the comparison is case-
insensitive.
not equals The opposite of equals.
starts with Only valid for fields of type string. The “field” must start with the
specified “value.” This is a case-insensitive comparison.
contains Only valid for fields of type string. The “field” must contain the specified
“value.” This is a case-insensitive comparison.
less than Only valid for fields of type double, i4, or dateTime (for SOAP) or
dateTime.iso8601 (for XML-RPC). The “field” must be strictly less than
the specified “value.”
In API versions prior to 2.0, the “less than” value does not perform a true
less than comparison. It performs a less than or equals comparison. In
API versions 2.0 and later, the “less than” value performs as expected.

Table 25: “operator” Substructure Members for Equality Comparisons

Values Description
less than or Only valid for fields of type double, i4, or dateTime (for SOAP) or
equals dateTime.iso8601 (for XML-RPC). The “field” must be less than or equal
to the specified “value.”
Available in API versions 2.0 and later.
greater than Only valid for fields of type double, i4, or dateTime (for SOAP) or
dateTime.iso8601 (for XML-RPC). The “field” must be greater than or
equal to the specified “value.”
In API versions prior to 2.0, the “greater than” value does not perform a
true greater than comparison. It performs a greater than or equals
comparison. In API versions 2.0 and later, the “greater than” value
performs as expected.
greater than or Only valid for fields of type double, i4, or dateTime (for SOAP) or
equals dateTime.iso8601 (for XML-RPC). The “field” must be greater than or
equal to the specified “value.”
Available in API versions 2.0 and later.
NOTE When filtering on fields that have a value of “id” or “reference” for the “type” member of the
“display” substructure in the describe response, the only valid “operator” value is “equals.”
See Also:
XML-RPC example: “filter” query Request (specifying a single criterion for a contact) on page 108
SOAP example: “filter” query Request (specifying a single criterion for a contact) on page 121
Boolean A filter criterion in the “filter” parameter can also be a Boolean combination of other nested
criteria. To use a Boolean combination filter criterion, you must specify the “operator” and
Combination “value” members for the “filter” parameter. The “field” member is not needed and will be
Filters ignored.
The “filter” parameter contains the following members for an AND or OR Boolean combination
filter:
Table 26: “filter” Substructure Members for AND or OR Filters

Member Description
value The “value” member must be an array of at least one element. Each
element of the array can be a simple comparison filter as described in
Equality Comparison Filters on page 20, or it can be another nested
Boolean combination filter.
operator The value of the “operator” must be “and” or “or.”
The “filter” parameter contains the following members for a NOT Boolean combination filter:
Table 27: “filter” Substructure Members for NOT Filters

Member Description
value The “value” member must be a struct or a map, which can be any valid
filter element, such as a simple comparison filter or a nested Boolean
combination filter element. The evaluation of this filter element will be
the logical negation of the nested filter element struct or map.
operator The value of the “operator” must be “not.”

See Also:
“filter” query Request (specifying a simple OR filter of two fields) on page 109
“filter” query Request (specifying nested Boolean combination filters) on page 109
NOTE Although the filter criteria can be arbitrarily complex in concept, the underlying database engine
can only handle filter criteria of a maximum size. The maximum size is large enough that most
normal filter conditions should be acceptable. A situation which tends to exceed the maximum
size of the filter criteria is a long list of IDs in an OR clause, for example, an account query with
filter (id = '001000000000123' OR id = '0010000000001h6' OR id = '001000000000cbV' OR id =
'00100000000009j' OR id = '001000000000UiO' …). If the OR list is long enough, you may need
to break the query into subqueries which are sent separately. In any case, you should not be
specifying a query with an OR filter of IDs. For such an example, you would use the “idList”
argument instead.
The query Response

A successful response to a query call is an array of records, one for each entity that matches the
specified scope.
For the “filter” and “idList” scopes, each record is a struct or a map of name-value pairs, in which
the name is a field ID as specified in the “select” list, and the value is the value of the field for
that record. Each struct or map may not contain all fields specified in the “select” list; some fields
may be missing in particular records if they have blank values for that record. If the “filter”
criteria are an empty array, all records visible to that user are returned.
A query response can potentially return an unbounded list. You should make sure that the client
can handle the size of the response that is generated for your data. For queries that return large
numbers of results, the server may pause before returning the response.
You cannot specify any sort criteria to the query call. You must sort the records on the client
side, if needed.
The query call returns only those records to which the user has access. Two different users in
the same organization may return a different set of records for the same query. The presence of
a particular record in the response means that the user has at least read access to the record. It
does not indicate whether the user has rights to update, delete, or reference that record.
“idList”
See Also:
query Fault Codes on page 84
query Call XML-RPC Examples on page 108
query Call SOAP Examples on page 121
T HE BATCH CALL
The batch call allows an sforce API client to perform multiple insert, update, or delete operations
in one call. Each batch request must be for a single operation on a single entity type. Each of the
separate elements of a batch call could be done as individual operations. The value of a batch
call is faster, more efficient execution. You should use a batch call whenever you have multiple
change operations to submit in one session.
The batch Request

In addition to the normal “version” and “type” parameters, a batch call requires the following
parameters:
Table 28: batch Request Members

Member Description
operation The type of operation to perform. The value must be one of “insert,”
“update,” or “delete.”

Table 28: batch Request Members

Member Description
arguments An array in which each element of the array is the contents of the
“record” struct or map, if it is an insert or update batch operation; or a
struct or a map that contains a single “id” member, if it is a delete batch
operation.
The batch Response

A successful batch response returns an array of elements with the same number of elements as
in the request. Each response element is the response object for the corresponding element in
the request array. The response elements are returned in the same order as the elements of the
request. Each of those response elements is the normal struct that would be generated by the
individual insert, update, or delete call. If an individual insert, update, or delete encounters a
problem, the other batch items are still processed, and that individual item generates a fault
response.
See Also:
batch Fault Codes on page 84
batch Call XML-RPC Examples on page 110
batch Call SOAP Examples on page 124
T HE SEARCH CALL
The search call allows you to find entities based on specified search keywords. The search call
provides a subset of the search functionality found in the salesforce.com user interface. You can
search just a single entity type, or across all searchable entity types that the user can access.
The search Request

The search request requires the following arguments:
Table 29: search Request Members

Member Description
type String value specifying a single searchable entity type that the
user can access, or the special keyword “all,” which indicates to
search across all searchable entity types that the user can
access. Searchable entity types are indicated by the “search”
attribute in the entity-level “access” member in the describe
response for that entity type.
The searchable entity types currently are: account, contact,
opportunity, case, event, task, note, campaign, lead

Table 29: search Request Members

Member Description
scope String value that indicates the scope of the search. Valid
“scope:” values are:
• all - Search all indexed fields in an entity
• name - Search indexed name fields in an entity. Indexed
name fields are:
• Account: Name, Site
• Contact: Salutation, First Name, Last Name
• Opportunity: Name
• Case: Subject, Name, Company
• Task and Event: Subject
• Lead: Salutation, First Name, Last Name, Company
• Note: Title
• Campaign: Name
• phone - Search indexed phone number fields in an entity.
Indexed phone fields are:
• Contact: Business Phone, Business Fax, Mobile Phone,
Home Phone, Other Phone, Asst. Phone
• Lead: Phone, Mobile Phone, Fax
• Account: Phone, Fax
• Cases: Phone
• email - Search indexed email fields in entity. Indexed email
fields are:
• Cases: Email
• Contact: Email
• Lead: Email
searchValue String value that specifies the search key words.

In API versions 2.0 and higher, the search call performs a
phrase search on this string. Alternatively, you can use the
“advancedSearchValue” parameter to employ more advanced
search syntax. You cannot specify “advancedSearchValue” if you
are using this parameter.
In API versions prior to 2.0, this parameter does not do a phrase
search. It allows you to use advanced search syntax.
See the Search section of the salesforce.com online help for
more information about search syntax.
advancedSearchValue String value that specifies the search key words. This parameter
is available in API versions 2.0 and higher only. You can use
advanced search syntax in this parameter.
You cannot specify “searchValue” if you are using this parameter.
See the Search section of the salesforce.com online help for
more information about search syntax.
maxRows Optional integer parameter that indicates the maximum number

of rows to return from the search.
useCaseSafeIDs Available only in API versions 2.0 and higher. Boolean. An

optional parameter to specify that the search response should
return 18 character case-insensitive record IDs, rather than 15
character case-sensitive record IDs. See The ID Fields on
NOTE In API versions 2.0 and higher, the search call performs a phrase search on the value specified
in the “searchValue” member. Alternatively, you can specify the

The search Response

The search response returns an array of record IDs that match the search string provided in the
request. The results are limited to a maximum of 2000 IDs, although you may not actually
receive 2000 IDs. The sforce API first retrieves up to 2000 IDs and then does an access check to
eliminate the records that the user cannot access. The remaining IDs are returned to the client.
If the request specifies to search all entity types, the client must determine the entity type for
each returned ID; see The ID Fields on page 36 for information on how to determine the entity
type. The API also validates that the user has read access to the returned IDs.
See Also:
search Fault Codes on page 84
search Call XML-RPC Examples on page 111
search Call SOAP Examples on page 125
T HE SET_PASSWORD CALL
The set_password call allows you to set a user’s password to a specified value. You must have
the MANAGE_USERS permission to use this call successfully.
In addition to the standard arguments, the set_password request requires the following
parameters:
Table 30: set_password Request Members

Members Description
userID A string value containing the unique ID of the user whose password is
being set.
password A string value containing the new password for the user.
A successful set_password response simply returns the string value of the new password,
which is identical to the value of the “password” member in the request.
See Also:
set_password Call XML-RPC Examples on page 112
set_password Call SOAP Examples on page 126
T HE RESET_PASSWORD CALL
The reset_password call allows you to set a user’s password to a system-generated value. You
must have the MANAGE_USERS permission to use this call successfully.
In addition to the standard arguments, the reset_password request requires the following
parameters:
Table 31: reset_password Request Members

Members Description
userID A string value containing the unique ID of the user whose password is
being reset.
A successful reset_password response returns a random, system-generated string for the new
password.
See Also:
reset_password Call XML-RPC Examples on page 113
reset_password Call SOAP Examples on page 127

T HE GET_SERVER_TIMESTAMP CALL
The get_server_timestamp call allows you to get the exact time used by the server. This can
be useful for clients that need to synchronize data using exact timestamps.
The get_server_timestamp request does not require any additional parameters.
A successful get_server_timestamp response returns a timestamp of the current server time.
See Also:
get_server_timestamp Call XML-RPC Examples on page 114
get_server_timestamp Call SOAP Examples on page 128

sforce API Chapter 3: Protocol Description
CHAPTER 3: Protocol Descr i pt ion
The sforce API uses several enhancements to the base XML-RPC specification. Those
enhancements are detailed in this chapter, and in most cases, apply to both the XML-RPC and
SOAP implementations of the sforce API.
VARIABLE-LENGTH RESPONSES
The XML-RPC specification states that all responses must specify a predetermined response
length using the HTTP Content-Length: header. For the XML-RPC implementation of the API,
sforce uses a more generalized form that allows the content length of the response to be
specified in any way that is valid for the version of HTTP that is being used.
For HTTP 1.0, the content length of the response may be specified using a Content-Length
header, or it may be omitted and the end of the response indicated by the close of the
connection.
For HTTP 1.1, the content length of the response may be specified using either of the
aforementioned methods, or by using HTTP 1.1 chunking. In particular, large responses from
sforce, such as commonly are returned from the query and batch calls, frequently respond
using HTTP 1.1 chunking. However, it is not guaranteed that they will use chunking; the calls
may also respond using Content-Length or Connection: close. If your code cannot handle
chunking, you should specify HTTP 1.0 in the request, which will force the response to use either
Content-Length or by closing the connection.
SOAP NOTE The SOAP specification does not restrict the use of the valid means to specify content length in
HTTP. All of the above methods are valid according to the SOAP specification.
NOTE Using HTTP 1.0 in the request disables the use of HTTP 1.1 connection keep-alive, and may
reduce performance. For more information on HTTP 1.1 chunking, refer to the HTTP 1.1 spec,
particularly the section on chunked transfer encoding, at www.w3.org/Protocols/rfc2616/
rfc2616-sec3.html#sec3.6.1.
UNICODE AND CHARACTER ENCODING SUPPORT

The XML-RPC specification states that all requests and responses must be in plain ASCII,
whereas the XML and SOAP specifications allow multiple encodings to be used. The sforce API
follows the conventions of XML character encoding. This means that any character encoding
specified in the HTTP header is ignored. You must specify an encoding in the XML header line.
The sforce server specifies the encoding of the response in both the XML header and the HTTP
header, in case any clients only support the HTTP encoding form.
The supported encodings for requests are ISO-8859-1, UTF-8, or UTF-16. The response is always
in ISO-8859-1 or UTF-8 and cannot be controlled by the client. You can determine the encoding
ahead of time using the global describe call. The encoding specified by the describe call is also
the character set that is supported by that sforce instance. You may send a request using ISO-
8859-1 encoding on an instance that supports the UTF-8 character set, since every ISO-8859-1
character also has an equivalent UTF-8 encoding. If you send a UTF-8 request to an instance that
only supports ISO-8859-1 characters, you should not send any data that is not representable in
the ISO-8859-1 character set. If you do, you may receive API fault code 1221 (“text data is
outside of supported character set”), or the character codes may be arbitrarily truncated to the
valid ISO-8859-1 range.

NOTE Refer to the XML specification for information on specifying and interpreting the encoding
specifier in an XML document. In particular, see www.w3.org/TR/REC-xml#charencoding.
USE OF XML-RPC FAULT CODES

The XML-RPC specification does not dictate any predefined set of fault codes and their meanings.
Some clients may return XML-RPC fault indicators if there are problems while attempting to
connect to the sforce servers. The fault codes are designed to not interfere with common fault
handling practices. See Appendix C: Fault Codes on page 79 for the full list of fault codes.
XML COMPLIANCE
XML-RPC and SOAP are based on XML, which requires all documents to be well formed. Part of
that requirement is that certain Unicode characters are not allowed in an XML document, even in
an escaped form, and that others must be encoded according to their location. Clients must be
able to parse any normal XML escape sequence.
Some characters, as mentioned, are illegal even if they are escaped. The illegal characters
include the Unicode surrogate blocks and a few other Unicode characters. All are seldom-used
control characters that are usually not important in any data, and tend to cause problems with
many programs. Although they are not allowed in XML documents, they are allowed in HTML
documents and may be present in sforce data. The illegal characters will be stripped from any
API response. The illegal characters are:
Table 32: Illegal XML Characters

0xFFFE
0xFFFF
Control characters 0x0 - 0x19

(Not including 0x9, 0xA, 0xD, tab, newline, and carriage return)
0xD800 - 0xDFFF
For UTF-8 encoding, sforce supports only the basic UCS-2 plane and does not support any of the
extended UCS-4 characters. UCS-4 support is extremely rare in any system; UCS-2 is the set
that Java and Windows NT support.
See Also:
www.w3.org/TR/REC-xml#charsets
USE OF COMPRESSION
The sforce API allows the use of compression on the request and the response, using the
standards defined by the HTTP 1.1 specification. Compression is not used unless the client
specifically indicates that it supports compression. For better performance, we suggest that
clients accept and support compression as defined by the HTTP 1.1 specification.
To indicate that the client supports compression, you should include the HTTP header “Accept-
Encoding: gzip, deflate” or a similar heading. The server compresses the response if the client
properly specifies this header. The response includes the header “Content-Encoding: deflate” or
“Content-Encoding: gzip,” as appropriate. You can also compress any request by including a
“Content-Encoding: deflate” or “gzip” header.
See Also:
Content-Encoding - www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11
Accept-Encoding - www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
Content Codings - www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.5
Compression on page 70

USE OF HEADERS
The sforce API requires certain HTTP headers and optionally allows the use of others. The use of
these headers is neither restricted nor required in the XML-RPC or SOAP specifications.
Table 33: Allowable HTTP Headers

Header Description
Session ID For non-login XML-RPC requests, the sforce API requires a session ID
cookie. The session ID is obtained via a login request and is used for
authentication for subsequent requests in that session. SOAP
requests do not require this header.
Accept-Encoding The API supports the use of HTTP 1.1 compression with requests and
responses.
Content-Encoding The API supports the use of HTTP 1.1 compression with requests and
responses.
PrettyPrint As a special debugging feature of the sforce API, you can specify the
header “PrettyPrint: Yes” in the request. This header requests that
the response be broken into multiple lines at boundaries that are
designed to be easier to read. You should only use this header for
development and debugging. It is not necessary in a production
system. It causes performance degradation and may cause time-
outs. It has not been thoroughly tested to ensure that the formatting
does not invalidate the XML, SOAP, or XML-RPC formatting
requirements.
A sample set of headers might look like the following:

POST /servlet/servlet.Api HTTP/1.0
user-agent: DTl/1.0
sessionid: ExCXJ5VWYxoULC0rLxAREhMUFRYRTGIeISwisy8Ns3jRKBU=
Accept-Language: en-us
Content-Length: 558
Accept: */*
Host: na1-api.salesforce.com
Connection: Keep-Alive
Cookie: sid=ExCXJ5VWYxoULC0rLxAREhMUFRYRTGIeISwisy8Ns3jRKBU=
CLIENT SUPPORT
Several different HTTP, XML, XML-RPC, and SOAP clients exist that may reduce development
effort. Sforce neither endorses nor restricts the use of these clients. Some clients, particularly
XML-RPC clients, may not support all of the XML-RPC features that sforce requires or suggests.
You may choose to use a standard client library, or you can write custom code to implement
these features. In either case, sforce cannot provide debugging support with client code.
SOAP Clients
Any standards-based SOAP client will work, including Microsoft .NET clients.
HTTP Clients
Most standard HTTP clients will work well. For better performance, we recommend using an HTTP
client that supports HTTP 1.1, chunking, and compression. Note that you will need a client that
supports chunking if the client also specifies HTTP 1.1 as the request protocol.

XML Clients
Most standard XML parsers will work well.
XML-RPC Clients
Many XML-RPC implementations have limitations that may make them incompatible or
suboptimal when used with sforce. However, most of the clients are open-source, so you can
modify the client as needed. Limitations include:
• Many XML-RPC clients use HTTP clients that do not fully support HTTP or HTTP 1.1, or do not
allow access to the HTTP headers (see HTTP Clients on page 29 for more information).
• Many XML-RPC clients do not expose methods that allow for chunked responses or for
compressed requests and responses.
• Many XML-RPC clients make no particular provisions for Unicode or character set support,
although in many cases the XML parser handles this automatically.
• Many XML-RPC clients do not perform well with large responses, as are possible from sforce
query calls.

sforce API Chapter 4: Multiple Instance Support
CHAPTER 4: Multiple Instance S uppor t
The sforce API provides access to all worldwide sforce servers, including US/North America 0,
US/North America 1, EMEA/Europe, and AP/Japan. The different sets of servers are referred to
as “instances.”
NOTE An organization is not guaranteed to be on a particular instance, just because that organization
is located in a particular region, although that is generally true. Also, additional instances may be
added in the future.
XML-RPC IMPLEMENTATION
The XML-RPC implementation of the sforce API provides a single login server for accessing all
sforce instances. You can log in to any organization via a single entry point, without having to
hard-code which instance your organization is on. To access an organization via the sforce API,
you must first authenticate the session by sending a login request to the login server at the
following URL:
• https://www.salesforce.com/servlet/servlet.Api
NOTE The insecure version of the URL is also supported:

http://www.salesforce.com/servlet/servlet.Api.
All subsequent calls to the server during the session should be made to the URL specified in the
login response. See the “server_url” member in Table 9: login Response Members on page 6.
See Also:
The login Call on page 6
SOAP IMPLEMENTATION
The SOAP implementation of the sforce API also provides a single login server. You can log in to
any organization via a single entry point, without having to hard-code which instance your
organization is on. To access an organization via the sforce API, you must first authenticate the
session by sending a login request to the login server at the following URL:
• https://www.salesforce.com/servlet/servlet.SoapApi
NOTE The insecure version of the URL is also supported:

http://www.salesforce.com/servlet/servlet.SoapApi.
All subsequent calls to the server during the session should be made to the URL specified in the
login response. See the “server_url” member in Table 9: login Response Members on page 6.
See Also:
The login Call on page 6

sforce API Chapter 5: Field-Specific Issues
CHAPTER 5: F i eld-S pecific Issues
Most sforce fields are fully explained by their metadata, but some fields have special handling or
characteristics that are not fully explained by the metadata.
NOTE Some numeric fields have precision and scale limits. In addition, certain text fields have length
restrictions. These restrictions are enforced when inserting or updating data. However, the sforce
API may return data that does not meet these restrictions.
See Also:
Chapter 6: Entity-Specific Issues on page 39
F IELD-LEVEL SECURITY
The sforce API enforces the field-level security model that an organization sets up using page
layouts in the salesforce.com user interface. In the user interface, the administrator can create
different page layouts, mark certain fields as read-only or hidden in the page layouts, and then
assign different users to different page layouts. For a particular user, the API can access only
those fields that are accessible to that user in their assigned page layout.
The following restrictions apply:
• The API can query read-only fields, but cannot insert or update them for that user.
• The API cannot query, insert, or update fields that are marked as hidden for that user.
With the sforce API, hidden fields are not visible to any users, even users with the
MODIFY_ALL_DATA permission. However, read-only fields can be modified by users with the
EDIT_READ_ONLY_FIELDS permission. This behavior is consistent with how the application
functions.
The describe call provides information about page layouts for specific entities. See Page Layout
Information on page 11.
NUMERIC F IELDS
Numeric fields include fields of type i4 and double. The standard, predefined fields are of type i4
or double, according to criteria explained in Determining the Type of Standard Fields on page 33.
All numeric custom fields are handled as type double.
Numeric fields must be transferred as i4 or double types, as appropriate, with the exception that
you can set a numeric field to null by setting it to a blank string value. The type is indicated in
the describe response for an entity. The type must be respected in all future calls that refer to
that field, including the insert and update calls. The type for the field is also returned from the
query call.
Numeric field bounds are enforced when inserting or updating records. The bounds are indicated
in the describe response by the “digits” attribute to an i4 field, or by the “scale” and “precision”
attributes to a double field.
Table 34: describe Attributes that Enforce Numeric Field Bounds

Member Description
digits Specifies the maximum number of digits that an integer can have

Table 34: describe Attributes that Enforce Numeric Field Bounds

Member Description
scale For double fields, specifies the maximum number of digits to the right of
the decimal place
precision For double fields, specifies the total number of digits, including those to
the left and the right of the decimal place
NOTE The maximum number of digits to the left of the decimal place is equal to “precision” minus
“scale.” In the salesforce.com user interface, precision is defined differently; it is the maximum
number of digits allowed to the left of the decimal place.
NOTE The limits for numeric fields are enforced when inserting or updating data. However, the sforce
API may return data that does not meet these restrictions.
Determining the Type of Standard Fields

The server determines whether a standard, predefined numeric field should be handled as a
double XML-RPC type or as an i4 XML-RPC type. Normally, the server chooses to use type i4
when the scale is zero, and type double when the scale is greater than zero. The i4 type in XML-
RPC is limited to a four-byte integer, so it cannot handle the full range of integer values that are
supported by sforce integer fields. Because of this, the server indicates a type of double for
numeric fields with a scale greater than zero, or with a precision greater than nine. However,
there will not be any loss of precision for very large integer values (greater than 15 or 16 digits)
that are transferred via the sforce API. Clients should not encode this logic themselves, but
should use the type specified in the describe response. The decision of when to use double or i4
type may change in the future, but any change will be reflected in the describe response.
ENUMERATED F IELDS
In the sforce API, enumerated fields are fields that are restricted to a defined list of values. They
are indicated in the describe response with a Boolean value of ‘1’ for the “restricted” member of
the “fields” substructure. The allowed values for an enumerated field are specified in the “values”
array of the “display” substructure of the describe response.
Note that the “values” member is present for any field of type picklist, and picklist fields that do
not have the “restricted” member are advisory. The sforce API does not enforce the list of values
for advisory picklist fields on insert or update.
Enumerated fields support localization of the values to the language of the user. For example, the
value “Omitted” for the Forecast Category field on an opportunity may be translated to various
languages. The enumerated field values are fixed and do not change with a user’s language.
However, each value may have an additional “label” member that provides the localized label for
that value. You must always use the value when inserting or updating a field. The query call
always returns the value, not the label. The corresponding label for a value in the describe
response should be used when displaying the value to the user in any user interface.
See Also:
The describe Call on page 7
DATE/TIME F IELDS
All Date/Time fields are transferred via the sforce API using the XML-RPC type dateTime.iso8601
or the SOAP type dateTime. However, sforce has two different ways of handling dates and times
internally. In some cases you can handle these identically, but in other cases you may need to
treat them differently.

Regular Date/Time Fields

Regular Date/Time fields are XML-RPC dateTime.iso8601 or SOAP dateTime fields that have a
“type” attribute of “datetime” in the “display” substructure of the describe response. Regular
Date/Time fields are full timestamps with a precision of one second. They are always transferred
in the GMT/UTC time zone. You may need to translate the timestamp to or from a local time zone
for the user or application, as appropriate.
Examples of regular Date/Time fields include all Create Date fields and the event dueDateTime
field. See Due Date Time and Due Date Only Fields on page 48 for more information about event
due date fields.
Date-Only Fields
Some fields in sforce are Date-Only fields. The time portion of a Date-Only field is not relevant
and is always set to midnight in the GMT/UTC time zone. Date-Only fields are transferred in the
API as dateTime types for SOAP and as dateTime.iso8601 types for XML-RPC calls, since XML-
RPC does not have a Date-Only type. They are indicated in the describe response with a “type”
attribute of “date” in the “display” substructure.
You should handle Date-Only field values differently than regular Date/Time values:
• You should ignore any time portion.
• You should always send a time portion of all zeroes. The sforce server accepts Date-Only
values that have a non-zero time portion, but the time portion is always truncated to zero.
• You should not alter any Date-Only values to account for time zone changes, since the time
portion is not relevant.
Examples of Date-Only fields are Opportunity Close Date, Contact Birth Date, all custom
field dates, and the event and task dueDateOnly fields. See Event on page 48 and Tasks on
page 66 for more information about event and task due date fields.
All Day Fields
NOTE All Day fields are obsolete as of sforce API version 1.8. Previous API versions continue to support
All Day fields.
Some Date/Time fields in sforce are All Day fields. These fields have a time portion and are
relative to a time zone, but the time portion is set to midnight in the owner's local time upon
saving. These fields are indicated in the describe response with a “type” attribute of “allday” in
the “display” substructure. They are transferred as dateTime.iso8601 values in XML-RPC and as
dateTime values in SOAP because they do have a full time portion, and they are time zone
shifted.
The sforce server does not reject values for All Day fields that do not fall on a midnight boundary.
Instead, it truncates the value to the greatest midnight boundary which is less than or equal to
the timestamp. The modified value, if any, is included in the “changed” structure as part of the
insert or update response.
Normally, clients do not need to deal with these fields any differently than normal Date/Time
fields, other than possibly looking for the changed value in the response. The knowledge of how
to truncate the value is too complex for most clients.
The two fields that are All Day fields are Task Due Date and Event Due Date. The Event Due
Date is treated as an All Day field only if the “allDay” flag on the event is “true.”
Event Duration Field

The event duration is not a date or time field, although it may be confused with one. The
duration field on an event is the duration of the event, expressed as an integer for the number of
minutes of the event.

CUSTOM F IELDS
In the salesforce.com user interface, organizations can define a set number of custom fields for
different entities. For the most part, clients of the sforce API do not need to know whether a field
is a standard field or a custom field for the organization. If desired, you can determine if a
particular field is a custom field by checking the “custom” member of the “fields” substructure in
the describe response. See the “fields” Substructure Members on page 8 for more information.
The customFieldDefinition entity describes the configuration of a custom field. See
CustomFieldDefinition on page 45 for more information.
Custom fields have a unique field ID, rather than an English-readable ID name. If you are using
the SOAP API with version 1.9 or higher, this unique field ID is always prefixed with “cf_” in all
calls. When making requests, you must also prefix any custom field IDs with the string “cf_”. This
restriction does not apply to the XML-RPC implementation of the sforce API.
Note that all numeric custom fields are handled as type double. See Numeric Fields on page 32
See Also:
The describe Call on page 7
O WNER F IELDS
Most entities have an ownerID field that is an entity reference field to the user that owns that
entity. Ownership is an important concept that affects the security model and has other
implications throughout the system. Any user can query the owner field for any record they can
access. However, the ownerID field has limitations when being set:
• For most users and most entities, the ownerID field cannot be set directly upon insert. It is
implicitly set to the current user when inserting an entity.
• Administrators (those with the MANAGE_ALL_DATA permission) can specify an ownerID
when inserting or updating any entity. The ownerID field value must be a valid user in the
organization.
• When inserting or updating cases and leads, an administrator can set the ownerID field to
any valid user in the organization or to any valid queue of the appropriate type in the
organization. Queues are not currently exposed in the sforce API as entities, but you can use
a queue ID for the ownerID field when inserting or updating a case or lead.
• Updating the ownerID field via the API only changes the owner of that record. The change of
ownership does not cascade to associated records as it does when you transfer record
ownership in the application.
• Updating the ownerID field on an account deletes the existing sharing information and
reapplies the default sharing model and autoshare rules.
CURRENCY F IELDS
The currencyISOCode field only exists for those organizations that have enabled multi-currency
support. For multi-currency organizations, the currencyISOCode field is defined for any entity
that can have currency fields. Currency fields are marked by a “type” attribute of “currency” in
the “display” substructure for the field in the describe response. The currencyISOCode field and
the currency fields are linked in a special way. On any specific record, the currencyISOCode field
defines the currency of that record, and thus, the values of all currency fields on that record will
be expressed in that currency.
For most cases, clients do not need to consider the linking of the currencyISOCode field and the
currency fields on an entity. However, clients may need to consider the following:
• The currencyISOCode field only exists for organizations that have enabled multi-currency
support. An organization either has it enabled or disabled; it cannot be partially enabled.
• When displaying the currency values in a user interface, it is preferred to prepend each
currency value by the currencyISOCode value, separating the two by a space.

• The currencyISOCode field is a restricted picklist field. It has certain defined values, which
may change from organization to organization, and it can only be set to those fields.
Attempting to set it to a value that is not defined for that organization causes the operation
to be rejected.
• If you update the currencyISOCode field on an entity, it implicitly converts all currency
values on that entity to the new currency code, using the conversion rates that are defined
for that organization in the salesforce.com user interface. If you specify currency values in
that same update call, the new currency values you specify are interpreted in the new
currencyISOCode field value, without conversion.
• For the currencyISOCode field in any entity, each element of the “values” array in the
“display” member of the “fields” struct or map of the describe response has several
additional members:
Table 35: Additional Members for currencyISOCode Picklist Fields

Member Description
corporate This attribute, if present, always has the Boolean value ‘1’. It indicates
that this currencyISOCode value is the corporate currency for this
organization.
conversionRate This attribute is always present and has a value of type double. The value
indicates the conversion rate for this currency to the corporate currency.
active This attribute is always present and has a Boolean value. It indicates
whether the currency is considered an active currency for this
organization, or if it is a currency that is only used for historical
purposes.
scale This attribute is always present and has an integer value. It indicates the
scale to be used for currency values when stored with this
currencyISOCode.
T HE ID F IELDS
For all entity types, every record has an id field that uniquely identifies that record. The value for
the id field is created automatically upon insert, and it cannot change over the lifetime of that
record, even if the record is deleted and then undeleted. Each id value is guaranteed to be
globally unique. The id of a record is the best way to uniquely identify that record.
In API versions prior to 2.0, the id of a record is always a 15 character case-sensitive ID and
should not be compared in a case-insensitive manner.
In API versions 2.0 and higher, the API can return either a case-sensitive or a case-insensitive id
field value. The case-insensitive ID is identical to the 15 character case-sensitive ID with three
extra characters appended to indicate the case of each of the original 15 characters. When
inserting or updating records, the API accepts either the 15 character case-sensitive ID or the 18
character case-insensitive ID. When querying or searching records using the API, you must
specify a value of ‘1’ for the “useCaseSafeIDs” parameter to indicate that you want the API to
return case-insensitive IDs. If you do not specify the “useCaseSafeIDs” parameter, you
automatically receive case-sensitive IDs.
The ID of a record also indicates what type of entity it is. This is useful for the search response
that returns a list of record IDs but does not include the entity type for each record (see The

search Response on page 25 for more information). Every record ID begins with a three
character code that identifies the entity type. The three character codes are:
Table 36: Codes to Determine Entity Type

Entity Type Code Entity Type Code
account 001 opportunity 006
accountShare 00r opportunityContactRole 00K
attachment 00P opportunityLineItem 00k
campaign 701 opportunityLineItemSchedule 00o
campaignMember 00v opportunityShare 00t
case 500 opportunityTeamMember 00q
caseSolution 010 partner 00I
caseComment 00a pricebook 00i
caseHistory 017 product 00j
contact 003 profile 00e
customFieldDefinition 00N profileRecordType 014
document 015 recordType 012
event 00U recordTypePicklist 013
folder 00l role 00E
group 00G solution 501
groupMember 011 task 00T
lead 00Q user 005
note 002 userTeamMember 00p
CROSS-REFERENCE ID F IELDS
Many entities have cross-reference ID fields, which are similar to foreign key fields in a database
table. Cross-reference ID fields are indicated in the describe response for that field, as follows:
• In the “display” substructure, the “type” attribute has the value “reference” (see Table 13:
“display” Substructure Members on page 10)
• The field description has a “referenceTo” attribute that indicates the entity type name, or an
array of possible entity type names, to which this field can refer (see Table 12: “fields”
Substructure Members on page 8).
In some cases, an entity can refer to another entity of its same type. For example, accounts
have a parent link that can point to another account.
You can also describe and query each cross-referenced entity. When you query a cross-reference
ID field, it returns an entity ID of the appropriate type. You can then query that ID to get
additional information about the entity, using the ID in the id field for that query. The cross-
reference ID field value is either a valid record in your organization, or an empty value, which
indicates an empty reference. In API versions prior to 2.0, empty references will have the value
'000000000000000.’
The cross-reference ID field value, if non-empty, is guaranteed to be an entity in your
organization. However, it is not guaranteed that you can query that entity. Users with the

MANAGE_ALL_DATA permission can always query that entity. Other users may be restricted from
viewing or editing the referenced entity.
Specifying a value for a cross-reference ID field when inserting or updating a record has specific
limitations also. The value must be a valid entity of the appropriate type, and the user must have
appropriate access to that entity. The exact requirements vary from field to field.
In API versions prior to 2.0, each cross-reference ID field has a 15 character alphanumeric, case-
sensitive value. In API versions 2.0 and higher, the API can return either a case-sensitive or a
case-insensitive cross-reference ID. The case-insensitive cross-reference ID is identical to the 15
character case-sensitive cross-reference ID with three extra characters appended to indicate the
case of each of the original 15 characters. When inserting or updating records, the API accepts
either the 15 character case-sensitive cross-reference ID or the 18 character case-insensitive
cross-reference ID. When querying or searching records using the API, you must specify a value
of ‘1’ for the “useCaseSafeIDs” parameter to indicate that you want the API to return case-
insensitive IDs. If you do not specify the “useCaseSafeIDs” parameter, you automatically receive
case-sensitive IDs.
LONG TEXT F IELDS

Several entities have long text fields (greater than 4000 bytes) that cannot be filtered. The long
text fields are generally normal text fields, except that you cannot specify the fields in the “filter”
criteria of a query call. However, you can filter the records on the client after you retrieve a
superset of the records that match your criteria. Fields that have this restriction are missing the
“filter” value in the “access” member of the “fields” substructure of a describe response (see
Table 12: “fields” Substructure Members on page 8).
SYSTEMMODSTAMP F IELDS
Most entities have a standard systemModstamp field that contains a timestamp of when the
record was last changed. This field is automatically maintained; you cannot insert, update or
delete it. The accountShare, opportunityShare, and partner entities do not have a
systemModstamp field.

sforce API Chapter 6: Entity-Specific Issues
CHAPTER 6: Entit y -S pecific Issues
Most entities are fully explained by their metadata, but some entity-specific characteristics
warrant further explanation.
See Also:
Chapter 5: Field-Specific Issues on page 32
ACCOUNT
No special considerations.
ACCOUNTSHARE
The accountShare entity represents a sharing entry on an account. In the salesforce.com user
interface, “sharing” refers to the act of granting access to a user or group to view and/or edit a
record owned by another user, if the default organization access levels do not otherwise permit
such access. So the accountShare entity allows you to determine which users and groups can
view and/or edit accounts owned by other users.
The describe, insert, update, query, and delete calls support the accountShare entity. You
must have the VIEW_ALL_DATA permission to view this entity and the MODIFY_ALL_DATA
permission to update it.
If you attempt to insert an accountShare that matches an existing accountShare record, the
insert call updates any modified fields and returns the existing record.
Backwards- The accountShare entity is useful for organization setup and configuration, but the form of the
Compatibility entity may change in the future. Salesforce.com cannot guarantee future backwards-
compatibility for this entity.
AccountShare Fields
The following accountShare fields are available in the sforce API:
Table 37: AccountShare Fields

Field Description
id String. The ID of the entity. This field is read-only.
accountID String. The ID of the account associated with this sharing

entry. This field cannot be updated.
userOrGroupID String. The ID of the user or group that has been given
access to the account. This field cannot be updated.

Table 37: AccountShare Fields

Field Description
accountAccessLevel String. The level of access that the user or group has to the
account. Valid values are:
• None - User or group cannot access the account.
• Read - User or group can only view the account.
• Edit - User or group can view or edit the account.
• All - User or group can view, edit, delete, and share the
account with other users. This value is not valid for inserts
and updates.
This field must be set to an access level that is at least equal
to the organization’s default account access level. In
addition, either this field or the opportunityAccessLevel
field must be set higher than the organization’s default
access level for accounts and opportunities.
opportunityAccessLevel String. The level of access that the user or group has to
opportunities associated with the account. Valid values are:
• None - User or group cannot access the associated
opportunities.
• Read - User or group can only view the associated
opportunities.
• Edit - User or group can view or edit the associated
opportunities.
This field must be set to an access level that is at least equal
to the organization’s default opportunity access level. In
addition, either this field or the accountAccessLevel field
must be set higher than the organization’s default access
level for accounts and opportunities.
This field cannot be updated via the API if the
accountAccessLevel field is set to “All.”
Using the API, you cannot update this field for the associated
account owner. You must update the account owner’s
opportunity access level via the salesforce.com user
interface.
rowCause String. The reason that this sharing entry exists. This field is
read-only. Valid values are:
• Owner - The user is the owner of the account or is in a
role above the account owner in the role hierarchy.
• Manual - The user or group has access because a user
with “All” access manually shared the account with them.
• Rule - The user or group has access via an account
sharing rule.
• ImplicitParent - The user or group has separate access
to an opportunity associated with this account, and so they
are automatically given “Read” access to the account.
lastModifiedByID String. The ID of the user who last updated the sharing
entry.
lastModifiedDate dateTime.iso8601 (for XML-RPC) or dateTime (for SOAP).

Date and time when the sharing entry was last modified.
See Also:
Group on page 50
OpportunityShare on page 57

ATTACHMENT
Attachments are files that users have uploaded and attached to a parent entity. The describe,
insert, update, query, and delete calls support attachments. The sforce API sends and
receives the binary file attachment data encoded as a base64 data type. Prior to insert, clients
must encode the binary attachment data as base64. Upon receiving an API response, clients
must decode the base64 data to binary.
Maximum The insert call restricts attachments to a maximum size of 5MB. For a file attached to a solution,
Attachment Size the limit is 1.5MB. The maximum email attachment size is also 1.5MB.
Attachment Fields
The following attachment fields are available in the sforce API:
Table 38: Attachment Fields

Field Description
name String. The name of the attached file.
parentID String. The ID of the parent entity of the attachment. See also
parentID Field on page 41.
body Base64. Encoded file data.
bodyLength Integer. Size of the file in bytes.
private Boolean. Indicates whether the attachment is viewable only by the

owner and administrators. See also private Field on page 42.
ownerID String. The ID of the user who owns the attachment.
createdByID String. The ID of the user who created the attachment.
createdDate dateTime.iso8601 (for XML-RPC) or dateTime (for SOAP). Date and

time when the attachment was created.
lastModifiedByID String. The ID of the user who last updated the attachment.
lastModifiedDate dateTime.iso8601 (for XML-RPC) or dateTime (for SOAP). Date and

time when the attachment was last modified.
All of the attachment fields are accessible in the describe and query calls. Using the insert call,
you can insert the name, parentID, body, private, and ownerID fields. For modifying
attachments, the update call gives you access to change the name, parentID, private, and
ownerID fields.
NOTE You can access all of the attachment fields in a query call. However, if you query the body field,
the response returns only the first attachment from the result list. You cannot receive the body
field for multiple attachments in a single query call.
parentID Field
The following entity types are supported as parents of attachments:
• account
• contact
• opportunity
• case

• solution
• campaign
• email
NOTE Note that the API supports attachments on emails in insert, update, and delete calls. The
query call does not return attachments parented by emails, unless the user performing the
query has the MODIFY_ALL_DATA permission.
private Field
If the private field is set to ‘1’ for an attachment, the attachment can be viewed only by the
attachment owner and administrators. During an insert or update, it is possible to mark an
attachment as “private” even if you are not the attachment owner. This can create a situation in
which you can no longer access the attachment that you just inserted or updated.
CAMPAIGN
The campaign entity represents and tracks a marketing effort, for example, a direct mail
promotion, webinar, or trade show. Using the API, you can insert, update, delete, and query
standard and custom fields for a campaign. The campaign statistics fields are read-only, as in the
salesforce.com user interface, and you cannot update the statistics via the sforce API.
The campaign entity is defined only for those organizations that have the Marketing feature
enabled and valid Marketing licenses. In addition, it is accessible only to those users that are
enabled as Marketing Users. If the organization does not have the Marketing feature or valid
Marketing licenses, the campaign entity type does not appear in the global describe call, and
you cannot describe or query the campaign entity.
NOTE The main constituents of campaigns are campaignMembers. You will commonly need to update
campaigns with campaignMembers. See CampaignMember on page 42.
CAMPAIGNMEMBER
The campaignMember entity defines the relationship between a campaign entity and either a
lead or a contact entity. Each campaignMember record has a unique ID.
Each individual campaignMember record must contain either a contactID or a leadID, but cannot
contain both. Any attempt to create a single campaignMember with both a contactID and a
leadID results in fault code 1231 “field integrity exception.” However, you can create separate
campaignMember records on a campaign, one for the lead and one for the contact.
The campaignMember entity is defined only for those organizations that have the Marketing
feature and valid Marketing licenses. In addition, the entity is accessible only to those users that
are enabled as Marketing Users. If the organization does not have the Marketing feature or valid
Marketing licenses, the campaignMember entity type does not appear in the global describe
call, and you cannot describe or query the campaignMember entity.
Status Field and Responded Flag

The status field is a picklist that directly controls the responded flag on a campaignMember. You
cannot directly set the responded flag, as it is read-only, but you can set it indirectly by setting
the status field. Each predefined status field value implies a responded flag value. Each time
you update the status field, you implicitly update the responded flag on the campaignMember.
In the salesforce.com user interface, Marketing Users can define the valid campaign member
status values for the status picklist. They can choose one status as the “default” campaign
member status. For each status field value, they can also select which values should be counted
as “Responded,” meaning that the responded flag will be set to “true” for those status values.

Inserting, Updating, and Deleting Campaign Members

The sforce API currently does not provide any way to update or delete campaignMember records.
You must use the salesforce.com user interface to delete campaignMembers.
You can indirectly update campaignMembers by sending an insert request. An insert call for
campaignMembers is interpreted as an auto-insert-or-update call. The sforce API automatically
determines whether a campaignMember exists with the specified campaign ID and contact or
lead ID. If the campaignMember does not exist for the given contact or lead ID, then an insert is
performed. If the campaignMember already exists, the call is interpreted as an update and the
status field and responded flag on the existing record are updated. Thus, you cannot create
duplicate campaignMember records, since any attempt to create a duplicate record simply
updates the existing record.
During an insert or update, the sforce API verifies whether the status field value specified in the
call is a valid campaign member status for the given campaign. If the specified status value is a
valid campaign member status, the API assigns that value to the campaignMember status field
and updates the responded flag with the associated value. If the specified status value is not a
valid campaign member status, the API assigns the default campaign member status to the
status field and updates the responded flag with the associated value. However, if the given
campaign does not have a default campaign member status, the API assigns the value specified
in the call to the status field, and the responded flag is set to “false.”
CASE
Case Number Field

The caseNumber field is assigned automatically when each case is inserted. It cannot be set
directly, and it cannot be modified after the case is created.
Insert-Only Fields
Cases have several fields that can only be set on insert. They cannot be updated after the case
has been created. Those fields are name, email, phone, and company.
Status Field and Closed Flag

The status field is a picklist that also directly controls the closed flag. You cannot directly set
the closed flag, but you can set it indirectly by setting the status field. Each predefined status
field value implies a closed flag value. Those values are indicated by the “closed” attribute in the
struct or map for each element in the “values” attribute for the status field.
Escalated Flag
Cases can have a special status called “escalated.” (See the salesforce.com online help
documentation for more information on case escalation.) A case's escalated state does not affect
how you can use a case, or whether you can query, update, or delete it. However, you cannot set
the escalated flag via the sforce API.
Description Field
The case description field is a special text field. The field description indicates a maximum
length of 4000, but it applies in a special way to the case description field. Normally, a field
length is expressed in characters, but the actual field length may be longer when measured in
bytes, depending on which character encoding is used. However, the case description field
length of 4000 indicates the maximum length of the field in bytes. The character encoding is
indicated by the “encoding” member of the global describe call.

CASECOMMENT
A case comment is an internal comment that provides additional information about a specific
case. In the online user interface, comments are generally entered by users working on a case.
The describe, insert, query, update, and bulk “idList” query calls support the caseComment
entity. All users have access to create and view case comments. In the salesforce.com user
interface, case comments cannot be modified after insertion. Using the API, you can update the
published field only.
The following caseComment fields are available in the sforce API:
Table 39: Case Comment Fields

Field Description
id String. The ID of the record. This field is read-only.
parentID String. The ID of the parent case of the case comment.
published Boolean. Indicates whether the case comment is visible to customers in

the Self-Service portal.
This is the only field that can be updated via the API. All of the other case
comment fields cannot be updated.
commentBody String. The text of the comment. The maximum size of the comment
body is 4000 bytes.
createdByID String. The ID of the user who created the case comment. This field is
read-only.
createdDate DateTime.iso8601. Date and time when the case comment was created.
This field is read-only.
CASEHISTORY
The caseHistory entity contains historical information about changes that have been made to a
case. The caseHistory entity is read-only via the API. The describe and query calls support
caseHistory.
CaseHistory Fields
The following caseHistory fields are available read-only in the sforce API:
Table 40: CaseHistor y Fields

Field Description
caseId String. The ID of the case associated with the case history entry.
field String. The name of the case field that was modified, or a special
value to indicate some other modification to the case. The possible
values, in addition to the case field names, are:
• ownerAssignment - The owner of the case was changed.
• ownerAccepted - A user took ownership of a case from a queue.
• ownerEscalated - The owner of the case was changed due to
case escalation.
• external - A user made the case visible to customers in the
Customer Self-Service Portal.

Table 40: CaseHistor y Fields

Field Description
oldValue String. The previous value of the modified case field.
newValue String. The new value of the modified case field.
createdByID String. The ID of the user who created the caseHistory record.

time when the caseHistory record was created.
CASESOLUTION
The caseSolution entity represents a relationship between a case and a solution. The describe,
insert, delete, and query calls support caseSolutions. You cannot update caseSolutions via the
sforce API.
If you attempt to insert a caseSolution that matches an existing caseSolution record, the insert
call simply returns the existing record.
CaseSolution Fields
The following caseSolution fields are available in the sforce API:
Table 41: CaseSolution Fields

Field Description
caseId String. The ID of the case associated with the solution.
solutionID String. The ID of the solution associated with the case.
createdByID String. The ID of the user who created the caseSolution record.

time when the caseSolution record was created.
CONTACT
No special considerations.
CUSTOMF IELDDEFINITION
The customFieldDefinition entity describes the configuration of a custom field.
The describe, insert, update, query, and delete calls support the customFieldDefinition
entity. You must have the CUSTOMIZE_SALESFORCE.COM permission to insert, update, and
delete this entity.
Backwards- The customFieldDefinition entity is useful for organization setup and configuration, but the form
Compatibility of the entity may change in the future. Salesforce.com cannot guarantee future backwards-

CustomFieldDefinition Fields
The following customFieldDefinition fields are available in the sforce API:
Table 42: CustomFieldDefinition Fields

Field Description
id String. The ID of the customFieldDefinition. This field is read-only.
tableName String. The name of the entity to which the custom field applies. The
valid values are listed in the describe response and include “lead,”
“contact,” “account,” and other entity types that support custom
fields.
A particular custom field can apply to only one type of entity.
label String. The name of the custom field.
dataType String. The type of the custom field. The value of this field must be
one of the following restricted values, which are similar to the “type”
values in the describe response:
• text - The field is a string field that does not have a “type”
specified in the describe response.
• number - The field is a numeric field that does not have a “type”
specified in the describe response.
• picklist - The field has a list of values. The field may be restricted
to those values, as indicated by the “restricted” member of the
“fields” array in the describe response. See also “fields”
Substructure Members on page 8.
• percent - The field contains percentage values.
• currency - The field contains currency values.
• phone - The field contains a phone number. Note that phone
numbers may contain any valid string character, not just numeric
characters. Also, the salesforce.com user interface formats phone
numbers when they are entered via a browser. The sforce API,
however, does not automatically format phone numbers. You
should specify phone numbers via the API with any necessary
formatting.
• email - The field contains an email address. Email addresses are
forced to lowercase upon saving.
• url - The field contains a URL. These fields should commonly be
displayed as hyperlinks.
• textarea - The field is a string field that should be displayed as a
multi-line text field.
• date - The field is a dateTime field (represented as a
dateTime.iso8601 type in XML-RPC), but is used internally as a
date-only value with no time portion. The time portion of the field
is ignored, and no time zone conversion is done.
length For string fields, the maximum size of the field in Unicode characters,
not bytes.

Table 42: CustomFieldDefinition Fields

Field Description
precision For number, percent, and currency fields, the “precision” and “scale”
scale indicate the numeric limits of the field.
• The “precision” is the maximum number of digits that can be
stored, including all numbers to the left and right of the decimal
point.
• The “scale” indicates the number of digits to the right of the
decimal point.
The server silently truncates any extra digits to the right of the
decimal point, but it returns a fault response if the number has too
many digits to the left of the decimal point.
createdByID String. The ID of the user who created the custom field.

time when the custom field was first created.
lastModifiedByID String. The ID of the user who last updated the custom field
definition.

time when the custom field definition was last modified.
DOCUMENT
Documents are files that users have uploaded. They are not attached to a parent entity, as
attachments are.
The describe, insert, update, query, and delete calls support documents. You must have the
EDIT_DOCUMENT permission and the appropriate access to the folder that contains a document
in order to insert or update a document in that folder. The sforce API sends and receives the
binary file data encoded as a base64 data type. Prior to insert, clients must encode the binary
file data as base64. Upon receiving an API response, clients must decode the base64 data to
binary.
Maximum The insert and update calls restrict documents to a maximum size of 5MB.
Document Size
Document Fields
The following document fields are available in the sforce API:
Table 43: Document Fields

Field Description
id String. The ID of the document. This field is read-only.
folderID String. The ID of the folder that contains the document. See Folder
on page 49.
name String. The name of the document.
type String. The file type of the document. The possible values for the
type field are indicated in the describe response. In general, the
values match the file extension for the type of document, e.g., “pdf”
or “jpg.”
body Base64. Encoded file data.

Table 43: Document Fields

Field Description
bodyLength Integer. Size of the file in bytes.
description String. A text description of the document.
author String. The ID of the user who is responsible for the document.
createdByID String. The ID of the user who first uploaded the document.

time when the document was first uploaded.
lastModifiedByID String. The ID of the user who last updated the document.

time when the document was last modified.
EVENT
whoID and whatID Fields

The event entity has whoID and whatID cross-reference ID fields. These are cross-reference
fields that can each point to one of several other entities, as indicated by the describe response.
The whoID field can point to a contact or lead, and the whatID field can point to an account,
opportunity, campaign, or case. In addition, if the whoID field refers to a lead, then the whatID
field must be empty.
Due Date Time and Due Date Only Fields

The salesforce.com user interface has a single Due Date field for events. However in the sforce
API, the due date information is contained in either the dueDateTime field or the dueDateOnly
field, depending on the value of the event allDay flag.
• dueDateTime - If the event allDay flag is set to “false” (indicating that it is not an all day
event), then the event due date information is contained in the dueDateTime field. This field
is a regular Date/Time field with a relevant time portion. The time portion is always
transferred in the GMT/UTC time zone. You need to translate the time portion to or from a
local time zone for the user or the application, as appropriate.
• dueDateOnly - If the event allDay flag is set to “true” (indicating that it is an all day event),
then the event due date information is contained in the dueDateOnly field. This field is a
Date-Only field with a timestamp that is always set to midnight in the GMT/UTC time zone.
The timestamp is not relevant, and you should not attempt to alter it to account for any time
zone differences. See Date-Only Fields on page 34 for more information.
When querying for events with a specific due date, you must filter on both the dueDateTime and
dueDateOnly fields. For example to find all events with a due date of February 14, 2003, you
need two filters:
• one filter with the dueDateOnly field equal to midnight GMT on February 14, 2003
• one filter with the dueDateTime field greater than or equal to midnight on February 14, 2003
in the user’s local time zone AND less than or equal to midnight on February 15, 2003 in the
user’s local time zone
Backwards- In sforce API versions prior to 1.8, the event due date information is contained in a single
Compatibility dueDate field. The dueDate field is a regular Date/Time field. However, if the allDay flag is set to
“true,” the dueDate field is treated as a local time midnight field. If you are using a version prior
to 1.8, the API automatically accounts for the changes in the event due date fields.

Archived Activities
Sforce archives older events and tasks, according to the criteria listed below. In the
salesforce.com user interface, users can view archived activities only in the Printable View or
by clicking View All on the Activity History related list or by doing an advanced search. However
in the sforce API, archived activities are not accessible.
Sforce archives activities according to the following criteria.
• Events with a dueDateTime or dueDateOnly value greater than or equal to 365 days old
• Tasks with a closed flag value of Boolean ‘1’ and a dueDateOnly value greater than or equal
to 365 days old
• Tasks with a closed flag value of Boolean ‘1’, a blank dueDateOnly field, and a create date
greater than or equal to 365 days ago
If you use the sforce API to insert activities that meet these criteria, the activities will be
archived during the next run of the archival background process.
Custom Fields and Page Layouts

In version 1.8, the sforce API added support for:
• Custom fields on tasks and events
• Page layouts for tasks and events; see Page Layout Information on page 11
• Field-level security for tasks and events; see Field-Level Security on page 32
You must specify a “version” of at least 1.8 to utilize this functionality.
FOLDER
A folder is a repository for documents, email templates, or reports. Only one type of item can be
contained in a particular folder. The describe, insert, update, query, and delete calls support
folders.
You must have the MODIFY_ALL_DATA permission to insert, update, and delete document
folders, email template folders, or report folders. To query folders, no special permissions are
needed.
Folder Fields
The following folder fields are available in the sforce API:
Table 44: Folder Fields

Field Description
id String. The ID of the folder. This field is read-only.
name String. The name of the folder.
type String. The type of entities contained in the folder. The type field
cannot be updated. The valid values are:
• Document
• Email template
• Report
accessType String. Indicates who can access the folder. The valid values are:
• Shared - Folder is accessible only by users in a particular group or
role. The API does not allow you to view, insert, or update which
group or role the folder is shared with.
• Public - Folder is accessible by all users.
• Hidden - Folder is hidden from everyone.

Table 44: Folder Fields

Field Description
readOnly Boolean. Indicates whether you can add data to this folder.
createdByID String. The ID of the user who first uploaded the document.

time when the document was first uploaded.
lastModifiedByID String. The ID of the user who last updated the document.

time when the document was last modified.
GROUP
The group entity represents a set of users. Only public groups are accessible via the sforce API.
Personal groups are not available.
The describe, insert, update, and query calls support the group entity. Groups cannot be
deleted. Any user can access the group entity; no special permissions are needed.
Group Fields
The following group fields are available in the sforce API:
Table 45: Group Fields

Field Description
name String. The name of the group.
relatedID String. For groups of type “Role,” the ID of the associated role. This
field is read-only.
type String. The type of the group. Valid values are:

• Reguler - A standard public group. When you insert a group, its
type must be “Regular.”
• Role - A public group that includes all of the users in a particular
role.
• RoleAndSubordinates - A public group that includes all of the
users in a particular role and all of the users in roles below that
role.
• Organization - A public group that includes all of the users in the
organization. This group is read-only.
createdByID String. The ID of the user who created the group.

time when the group was created.
lastModifiedByID String. The ID of the user who last updated the group.

time when the group was last modified.
See Also:
GroupMember on page 51

GROUPMEMBER
The groupMember entity describes users or groups who are members of public groups. A
groupMember record exists for every user or group who is a direct member of a public group
whose type field is set to “Regular.” Users who are indirect members of “Regular” public groups
are not listed as group members. A user can be an indirect member of a group if he or she is in a
role above the direct group member in the hierarchy, or if he or she is a member of a group that
is included as a subgroup in that group.
The describe, insert, delete, and query calls support the groupMember entity. Group
members cannot be updated. Any user can access the groupMember entity; no special
permissions are needed.
If you attempt to insert a groupMember that matches an existing groupMember record, the
insert call simply returns the existing record.
GroupMember Fields
The following groupMember fields are available in the sforce API:
Table 46: GroupMember Fields

Field Description
groupID String. The ID of the group.
userOrGroupID String. The ID of the user or group that is a direct member of the
group.
See Also:
Group on page 50
LEAD
Converted Leads
Leads have a special state to indicate that they have been converted into an account, contact,
and opportunity. (See the salesforce.com online help documentation for additional information
on converting leads.) You can convert leads only through the salesforce.com user interface. Once
a lead has been converted, it is read-only. You cannot update or delete a converted lead.
However, you can query converted leads using the query call.
Leads have several fields that indicate their converted status. These special fields are read-only
via the sforce API. You cannot set these fields directly; they are set when converting the lead in
the salesforce.com user interface. The fields are:
Table 47: Fields on Converted Leads

Field Description
converted Boolean field that indicates whether the lead has been
converted
convertedAccountID Entity reference ID that points to the account into which the
lead has been converted
convertedContactID Entity reference ID that points to the contact into which the
lead has been converted

Table 47: Fields on Converted Leads

Field Description
convertedOpportunityID Entity reference ID that points to the opportunity into which

the lead has been converted
Lead Status Picklist

The Lead Status picklist field has an additional “converted” attribute for each value of the
picklist. The “converted” attribute is a Boolean that specifies whether a Status field value
indicates a lead that has been converted. You cannot convert a lead by simply setting its Status
field to one of the “converted” values.
NOTES
Private Flag
The private flag on a note is a field that influences the access rights for that note. If the note is
marked private, only the note owner or a user with the MODIFY_ALL_DATA permission can view
the note or query it via the sforce API. Because of this, you can create an odd situation for a
regular user that does not have the MODIFY_ALL_DATA permission. If a regular user sets the
private flag to Boolean ‘1’ on a note that they do not own, then they can no longer query,
update, or delete that note.
OPPORTUNITY
Opportunity Stage
The Opportunity Stage field controls several other fields on an opportunity. Each of the fields
can be directly set or implied by changing the Opportunity Stage field. In addition, the
Opportunity Stage field is a picklist, so it has additional members in each element of the
“values” array in the “display” member of the “fields” struct or map of the describe response to
indicate how it affects the other fields.
Table 48: Additional “value” Members for Opportunity Stage

Member Description
forecastCategory The Forecast Category field value implied by this Opportunity

Stage
probability The Probability field value implied by this Opportunity Stage
closed A Boolean value indicating whether an opportunity is marked as

closed when set to this Opportunity Stage
won A Boolean value indicating whether an opportunity is marked as

won when set to this Opportunity Stage
Forecast Category
Forecast Category is a restricted picklist field. It is implied, but not directly controlled, by the
Opportunity Stage field. You can override this field to a different value than is implied by the
Opportunity Stage.

The values of the Forecast Category field are fixed enumerated values. The field labels are
localized to the language of the user performing the operation, if localized versions of those
labels are available for that language in the salesforce.com user interface.
Closed and Won Flags

The Closed and Won flags are directly controlled by the Opportunity Stage field, as indicated by
the extra attributes in the picklist “values” definition. You can query and filter on these fields, but
you cannot directly set them in an insert or update request. Instead, you must set the
Opportunity Stage to a value that has the appropriate Closed and Won flags.
Probability Field
The opportunity Probability field is implied, but not directly controlled, by the Opportunity
Stage field. You can override this field to a different value than what is implied by the
Opportunity Stage.
Expected Amount Field

The Expected Amount field is a read-only field that is equal to the product of the opportunity
Amount field and the Probability. You cannot directly set the Expected Amount field, but you
can indirectly set it by setting the Amount or Probability fields.
Amount Field
The opportunity Amount field is normally a regular field, but it becomes implicitly read-only if the
opportunity has any line items. Any attempt to update the Amount of an opportunity that has line
items will be ignored. The update call will not be rejected, and other fields will be updated as
specified, but the Amount will be unchanged.
Campaign Field
The opportunity campaignID field is a cross-reference field that points to a campaign entity. The
campaignID field is defined only for those organizations that have Campaigns enabled as a
feature.
The user must have read access rights to the cross-referenced campaign entity in order to insert
or update that campaign into the campaignID field on the opportunity.
Has Line Item Field

The opportunity hasLineItem field is a read-only field that indicates whether the opportunity has
associated line items. A value of “true” means that opportunity line items have been created for
the opportunity.
Price Book Field

The opportunity pricebookID field is a cross-reference field that points to a pricebook entity. The
pricebookID field indicates which price book applies to the specific opportunity. The
pricebookID field is defined only for those organizations that have Products enabled as a
feature.
An opportunity can only have opportunity line items if the opportunity has a price book. The
opportunity line items must correspond to products that are listed in the opportunity's price
book. However, you can insert opportunity line items on an opportunity that does not have an
associated price book. For the first opportunity line item that you insert on an opportunity
without a price book, the API automatically sets the pricebookID field, if the opportunity line
item corresponds to a product in an active price book that has a currencyISOCode field that
matches the currencyISOCode field of the opportunity. If the price book is not active or the
currencyISOCode fields do not match, the API returns a fault response.

You cannot update the pricebookID field if opportunity line items exist on the opportunity. You
must delete the line items before attempting to update the pricebookID field.
Currency Field
The currencyISOCode field exists only for multi-currency organizations. If the organization does
not have the multi-currency feature enabled, the currencyISOCode field is not accessible.
If the organization is multi-currency and a price book is not specified on the opportunity (i.e., the
pricebookID field is blank), the currencyISOCode field can have any currency allowed by the
organization.
If the organization is multi-currency and a price book is specified on the opportunity (i.e., the
pricebookID field is not blank), then the currency value of the currencyISOCode field must
match the currency of the price book. If the price book changes, the opportunity currency must
also be changed to be the same as the currency of the price book.
See Also:
OpportunityLineItem on page 54
OpportunityLineItemSchedule on page 56
OpportunityContactRole on page 54
OPPORTUNITYCONTACTROLE
The opportunityContactRole entity is a relationship between opportunities and contacts, with a
specified role name applied to the contact. Opportunity contact roles appear in the
salesforce.com user interface on the Opportunity detail page.
You can create multiple relationships between the same opportunity and a contact. This action is
not recommended, but the application does not prohibit it.
opportunityContactRole records have their own unique ID, like most other entities. You must use
that ID when updating or deleting an opportunityContactRole.
Opportunity ID Field
The opportunityID field of an opportunityContactRole is non-nullable, and it cannot be updated.
You must provide a value for the opportunityID on insert. You cannot change it after it has been
inserted.
Contact ID Field
The sforce API applies user access rights to the associated opportunity for an
opportunityContactRole, but not to the associated contact. As such, the API may return rows
from an opportunityContactRole query that include contactID values for contacts that the user
does not have sufficient rights to access. It may also return contactID values for contacts that
have been deleted. In either case, the client must perform a query on the contact table for that
contactID value to determine whether the contact is accessible to the user and has not been
deleted.
OPPORTUNITYLINEITEM
Opportunity line items are the list of products on an opportunity, along with other information
about those products on that opportunity. The opportunity can only have opportunity line items if
the opportunity has a price book. An opportunity line item must correspond to a product that is
listed in the opportunity's price book. (See Effects on Opportunities on page 55 for information
on how to insert opportunity line items for an opportunity that does not have an associated price
book or any existing line items.)
The opportunityLineItem entity is defined only for those organizations that have Products
enabled as a feature. If the organization does not have the Products feature, the

opportunityLineItem entity type does not appear in the global describe call, and you cannot
describe or query the opportunityLineItem entity.
The user must have edit access rights on the opportunity in order to insert or update opportunity
line items on that opportunity.
Total Price Field

The totalPrice field specified in an insert or update call is the total price of the opportunity
line item. The unit price of an opportunity line item is not accessible via the API. The
salesforce.com user interface calculates the unit price as the total price of the opportunity line
item divided by the quantity listed for that line item. To insert the totalPrice for an opportunity
line item via the API (given only a unit price and the quantity), calculate the totalPrice field as
the unit price multiplied by the quantity.
The totalPrice field is read-only if the opportunity line item has a revenue schedule. If the
opportunity line item does not have a schedule or only has quantity schedule, the totalPrice
field can be updated.
Quantity Field
The quantity field on the opportunityLineItem entity is read-only if the opportunity line item has
a quantity schedule, a revenue schedule, or both a quantity and a revenue schedule.
Has Revenue Schedule and Has Quantity Schedule Fields

The hasRevenueSchedule field on the opportunityLineItem entity is read-only, and is "true" if a
revenue schedule has been created for the opportunity line item.
The hasQuantitySchedule field on the opportunityLineItem entity is read-only, and is "true" if a
quantity schedule has been created for the opportunity line item.
If the opportunity line item has a revenue schedule, the quantity and totalPrice fields cannot
be updated. In addition, the quantity field cannot be updated if the opportunity line item has a
quantity schedule. The sforce API ignores any attempt to update these fields. The update call
will not be rejected; the updated values will simply be ignored.
Effects on Opportunities
Opportunities that have associated opportunity line items are affected in the following ways:
• Inserting an opportunity line item increments the opportunity Amount value by the
totalPrice of the opportunity line item. Additionally, inserting an opportunity line item
increments the Expected Amount on the opportunity by the totalPrice times the
opportunity Probability.
• The opportunity Amount becomes a read-only field when the opportunity has line items. The
API ignores any attempt to update this field on an opportunity with line items. The update
call will not be rejected; the updated value will simply be ignored.
• You cannot update the pricebookID field or the currencyISOCode field on the opportunity if
line items exist. The API rejects any attempt to update these fields on an opportunity with
line items.
• When you insert or update an opportunity line item, the API verifies that the line item
corresponds to a product in the price book that is associated with the opportunity. If the
opportunity does not have an associated price book, the API automatically sets the
pricebookID field on the opportunity if the line item corresponds to a product in an active
price book that has a currencyISOCode field that matches the currencyISOCode field of the
opportunity. If the price book is not active or the currencyISOCode fields do not match, the
API returns a fault response.
• The opportunity hasLineItem field is set to “true” when an opportunity line item is inserted
for that opportunity.
See Also:

OPPORTUNITYLINEITEMSCHEDULE
Opportunity line item schedules provide information about the quantity and revenue distribution
and delivery dates for a particular line item. Sforce supports two types of opportunity line item
schedules - quantity schedules and revenue schedules.
The opportunityLineItemSchedule entity is defined only for those organizations that have the
Products and Annuities features enabled. If the organization does not have the Products and
Annuities features, the opportunityLineItemSchedule entity type does not appear in the global
describe call, and you cannot describe or query the opportunityLineItemSchedule entity.
The user must have edit access rights on the opportunity in order to insert or update line item
schedules on that opportunity.
ID Field
The id field uniquely identifies the opportunity line item schedule. You can specify the id field for
query, update and delete calls.
Type Field
The type field specifies the type of the schedule.You must specify a type value when inserting an
opportunity line item schedule. Valid values are “Quantity,” “Revenue,” or “Both.” However, the
allowable values for a particular opportunity line item schedule depend on the product-level
schedule preferences and whether the line item has any existing schedules. The following criteria
must be met:
• The product on which the opportunity line item is based must have the appropriate
revenueScheduleEnabled and/or quantityScheduleEnabled flags set to “true”.
• When you insert a schedule for a line item that does not have any existing schedules, you
can specify any valid value.
• If you insert a schedule for a line item that already has existing schedules, the new schedule
must be consistent with the existing schedules. The following matrix outlines the allowable
values:
Table 49: Allowable type Values for Opportunity Line Item Schedules
Value of Value of
hasRevenueSchedule hasQuantitySchedule Allowable type Values
on line item on line item
false false Revenue, Quantity, Both
false true Quantity
true false Revenue
true true Both
Quantity and Revenue Fields

The quantity field specifies the total number of units to be scheduled in a quantity schedule.
The revenue field specifies the total price to be scheduled in a revenue schedule.

The allowable quantity and revenue field values depend on the value of the type field:
Table 50: Allowable quantity and revenue Values for Line Item Schedules
type Value Allowable quantity Value Allowable revenue Value
Revenue Null Non-null
Quantity Non-null Null
Both Non-null Non-null
The quantity and revenue fields have the following restrictions in the update call.
• For a schedule of type “Quantity,” you cannot update a null revenue value to non-null.
Likewise for a schedule of type “Revenue,” you cannot update a null quantity value to non-
null.
• You cannot null out the quantity field for a schedule of type “Quantity.” Likewise you cannot
null out the revenue field for a schedule of type “Revenue.”
• You cannot null out either the revenue or quantity fields for a schedule of type “Both.”
Effects on Opportunities and Opportunity Line Items

Opportunity line item schedules affect opportunities and opportunity line items in the following
ways:
• Inserting an opportunityLineItemSchedule of type “Revenue” or “Quantity” increments the
totalPrice field on the opportunity line item by the line item schedule revenue amount.
Inserting an opportunityLineItemSchedule of type “Quantity” or “Both” increments the
quantity field on the opportunity line item by the line item schedule quantity amount.
• The insert call also affects the original opportunity as follows: 1) the opportunity Amount is
incremented the by opportunity line item schedule revenue amount; and 2) the opportunity
Expected Amount is incremented by the line item schedule amount multiplied by the
opportunity Probability.
• Deleting an opportunityLineItemSchedule has a similar effect on the related opportunity line
item and opportunity. Deleting a schedule decrements the opportunity line item totalPrice
by the deleted line item schedule amount. The opportunity Amount is also decremented by
the line item schedule amount, and the opportunity Expected Amount is reduced by the line
item schedule amount multiplied by the opportunity Probability.
Deleting an Opportunity Line Item Schedule

To delete an opportunity line item schedule, you must specify the id in the delete call. Deleting
the last remaining schedule will set the corresponding hasQuantitySchedule and/or
hasRevenueSchedule flags to “false” on the parent line item.
See Also:
Product on page 61
The delete Call on page 18
OPPORTUNITYSHARE
The opportunityShare entity represents a sharing entry on an opportunity. In the salesforce.com
user interface, “sharing” refers to the act of granting access to a user or group to view and/or
edit a record owned by another user, if the default organization access levels do not otherwise
permit such access. So the opportunityShare entity allows you to determine which users and
groups can view and/or edit opportunities owned by other users.

The describe, insert, update, query, and delete calls support the opportunityShare entity.
You must have the VIEW_ALL_DATA permission to view this entity and the MODIFY_ALL_DATA
If you attempt to insert an opportunityShare that matches an existing opportunityShare record,
the insert call updates any modified fields and returns the existing record.
Backwards- The opportunityShare entity is useful for organization setup and configuration, but the form of
Compatibility the entity may change in the future. Salesforce.com cannot guarantee future backwards-
OpportunityShare Fields
The following opportunityShare fields are available in the sforce API:
Table 51: OpportunityShare Fields

Field Description
opportunityID String. The ID of the opportunity associated with this sharing

entry. This field cannot be updated.
userOrGroupID String. The ID of the user or group that has been given
access to the opportunity. This field cannot be updated.
opportunityAccessLevel String. The level of access that the user or group has to the
opportunity. Valid values are:
• None - User or group cannot access the opportunity.
• Read - User or group can only view the opportunity.
• Edit - User or group can view or edit the opportunity.
• All - User or group can view, edit, delete, and share the
opportunity with other users. This value is not valid for
inserts and updates.
This field must be set to an access level that is higher than
the organization’s default access level for opportunities.
rowCause String. The reason that this sharing entry exists. This field is
read-only. Valid values are:
• Owner - The user is the owner of the opportunity or is in a
role above the opportunity owner in the role hierarchy.
• Manual - The user or group has access because a user
with “All” access manually shared the opportunity with
them.
• Rule - The user or group has access via an opportunity
sharing rule.
• ImplicitChild - The user or group has access to the
opportunity via an accountShare record on the account
associated with this opportunity.
• Team - The user has access to the opportunity because
she or he is on the sales team for the opportunity. The
opportunityTeamMember entity for this opportunity sets
the access level. See OpportunityTeamMember on page 59
lastModifiedByID String. The ID of the user who last updated the sharing
entry.

Date and time when the sharing entry was last modified.

See Also:
Group on page 50
AccountShare on page 39
OPPORTUNITYTEAMMEMBER
The opportunityTeamMember entity represents a single user on the sales team of an opportunity.
In the salesforce.com user interface, users can set up a sales team for the opportunities they
own. The sales team includes other users that are working on the opportunity with them. The
opportunityTeamMember entity is available only in organizations that have enabled the team
selling functionality.
The describe, insert, update, query, and delete calls support the opportunityTeamMember
entity. You must have the VIEW_ALL_DATA permission to view this entity and the
MODIFY_ALL_DATA permission to update it.
If you attempt to insert an opportunityTeamMember that matches an existing
opportunityTeamMember record, the insert call updates any modified fields and returns the
existing record.
OpportunityTeamMember Fields
The following opportunityTeamMember fields are available in the sforce API:
Table 52: OpportunityTeamMember Fields

Field Description
opportunityID String. The ID of the opportunity associated with this sales

team. This field cannot be updated.
userID String. The ID of the user who is a member of the

opportunity’s sales team. This field cannot be updated.
opportunityAccessLevel String. The level of access that the team member has to the
opportunity. Valid values are:
• None - User cannot access the opportunity.
• Read - User can only view the opportunity.
• Edit - User can view or edit the opportunity.
• All - User can view, edit, delete, and share the opportunity
with other users. This value is not valid for inserts and
updates.
teamMemberRole String. The role that the team member has on the
opportunity. The valid values are set by the organization’s
administrator in the Sales Team Roles picklist.
lastModifiedByID String. The ID of the user who last updated the record.

Date and time when the record was last modified.
See Also:
UserTeamMember on page 67

PARTNER
The partner entity defines a relationship between two accounts or between an opportunity and
an account. Each account in the relationship is assigned a role (e.g., “Consultant” or
“Distributor”) designating that account’s role towards the related account or opportunity. A
relationship between two accounts is referred to as an account partner, and a relationship
between an opportunity and an account is referred to as an opportunity partner.
The describe, insert, query, and delete calls support partners. All of the partner fields are
accessible in the describe and query calls; see Partner Fields on page 60. Using the insert call,
you can insert the opportunityID or accountFromID, accountToID, primary, and role fields;
see Inserting Partners on page 61. You cannot update partners via the sforce API. You must
have the VIEW_ALL_DATA permission to access partners via the API.
Partner Fields
The following partner fields are available in the sforce API:
Table 53: Partner Fields

Field Description
opportunityID String. The ID of the opportunity in a partner relationship between an

account and an opportunity.
Specifying this field upon insert creates an opportunity partner. If you
specify the accountFromID field, you cannot specify this field as well.
accountFromID String. The ID of the main account in a partner relationship between

two accounts.
Specifying this field upon insert creates an account partner. If you
specify the opportunityID field, you cannot specify this field as well.
accountToID String. The ID of the partner account related to either an opportunity

or an account.
You must specify this field when creating an opportunity partner or an
account partner.
primary Boolean. Valid for opportunity partners only.

Indicates that the account is the primary partner for the opportunity.
Only one account can be marked as “primary” for an opportunity. If
you set the primary flag to ‘1’ upon insert of a new opportunity
partner, any other existing primary partners for that opportunity will
automatically have their primary flag set to ‘0.’
role String. The role that the account has towards the related opportunity
or account (e.g., “Consultant” or “Distributor”).
ID String. The unique ID of the partner record.
createdByID String. The ID of the user who created the partner. Read-only.

time when the partner was created. Read-only.
lastModifiedByID String. The ID of the user who last updated the partner. Read-only.

time when the partner was last modified. Read-only.

Inserting Partners
Using the insert call, you can insert the opportunityID or accountFromID, accountToID,
primary, and role fields. When creating a partner entity, you must specify either the
opportunityID field or the accountFromID field. Specifying the opportunityID field creates an
opportunity partner, and the accountFromID field creates an account partner. You must always
specify a value for the accountToID field.
When you create an account partner, i.e., a relationship between two accounts, the sforce API
automatically creates a reverse partner relationship between those two accounts. For example, if
you create an account partner with “Acme, Inc.” as the accountFromID and “Acme Consulting” as
the accountToID, the API automatically creates a reverse partner with “Acme Consulting” as the
accountFromID and “Acme, Inc.” as the accountToID. In the reverse partner, the value of the
role field is set to the designated reverse role value associated with the value of the role field in
the original account partner. In the salesforce.com user interface, system administrators can set
up the valid role values and their corresponding reverse role values.
If you set the primary flag to ‘1’ upon insert of a new opportunity partner, any other existing
primary partners for that opportunity will automatically have their primary flag set to ‘0.’
PRICEBOOK
The pricebook entity allows you to query information about price books that have been
configured for an organization. You cannot insert, update, or delete price books through the
sforce API. The purpose of the pricebook entity is to allow you to obtain valid pricebook entity
IDs for use when querying or modifying products through the API. See Product on page 61 for
more information.
The pricebook entity is defined only for those organizations that have Products enabled as a
feature. If the organization does not have the Products feature, the pricebook entity type does
not appear in the global describe call, and you cannot describe or query the pricebook entity.
NOTE Products are the main constituents of price books. “Setting up a price book” via the sforce API
usually means loading products into those price books. The usual way to configure price books
via the API is:
1. Manually create the price books using the salesforce.com user interface
2. Query the pricebook table to obtain the pricebook IDs
3. Insert or update the product table using the API to load products into those price books
PRODUCT
The product table is a list of items on price books. The product entity allows you to query, insert,
and update products on price books. These operations constitute the main configuration
necessary for price books (see PriceBook on page 61).
The product entity is defined only for those organizations that have Products enabled as a
feature. If the organization does not have the Products feature, the product entity type does not
appear in the global describe call, and you cannot describe or query the product entity.
Products can be queried, inserted, and updated via the sforce API, but they cannot be deleted
through the API or any other means. See Active Flag on page 62 for more information. Because
products can never be deleted, please exercise caution when creating them.
priceBookID Field
The priceBookID field indicates the price book on which the product is configured. When
inserting products, the pricebookID field must be set, and its value must be valid and non-
blank. You cannot update the pricebookID field during an update call. You can query the
pricebook entity to obtain valid pricebook entity IDs for your organization after they have been
created using the salesforce.com user interface.

Active Flag
The active flag indicates whether a product is active. Although you can never delete products,
you can set a product’s active flag to ‘false.’ Inactive products are hidden in many areas in the
salesforce.com user interface. You can change a product’s active flag as often as necessary.
Schedule Fields
The product entity has several fields that are only used for schedules (a.k.a, annuities). Sforce
supports two types of schedules on products - quantity schedules and revenue schedules.
Schedules are available only for those organizations that have the Products and Annuities
features enabled. If the organization does not have the Annuities feature, the schedule fields do
not appear in the describe response, and you cannot query, insert, or update the fields.
Schedule When enabling the Annuities feature, organizations can decide whether to enable quantity
schedules, revenue schedules, or both. In addition, you can use the sforce API to control
Enabled
quantity and revenue scheduling at the product level via the revenueScheduleEnabled and
Flags quantityScheduleEnabled flags. A value of “true” for either flag indicates that the product and
any opportunity line items can have a schedule of that type. These flags can be set via an insert
or update call.
Default The remaining product schedule fields define default schedules for the entity. Sforce uses the
default schedule values to create an opportunity line item schedule when an opportunity line
Schedule
item is created for the product.
Fields The default schedule fields and their valid values are listed below.
Table 54: Default Schedule Fields on Products

Field Valid Values
revenueScheduleType None, Divide, Repeat
revenueInstallmentPeriod None, Daily, Weekly, Monthly, Quarterly, Yearly
numberOfRevenueInstallments An integer from 1 to 100
quantityScheduleType None, Divide, Repeat
quantityInstallmentPeriod None, Daily, Weekly, Monthly, Quarterly, Yearly
numberOfQuantityInstallments An integer from 1 to 100
When you attempt to set the schedule fields via an insert or update call, the sforce API applies
cross-field integrity checks. The integrity requirements are:
• If the schedule type is set to “None,” the installment period and number of installments must
be null.
• If the schedule type is set to any value other than “None,” the installment period and number
of installments must be non-null.
Inserts or updates that fail these integrity checks are rejected with fault code 1231 “field
integrity violation.”
The revenueScheduleType, revenueInstallmentPeriod, quantityScheduleType, and
quantityInstallmentPeriod fields are restricted picklist fields and are available only if the
organization has the Annuities feature enabled. The permissible values are indicated in the
describe response.
See Also:

PROFILE
The profile entity allows you to query the set of currently configured profiles in the organization.
You cannot insert, update, or delete profiles through the sforce API. The purpose of the profile
table in the API is to allow you to obtain valid profile IDs for use when querying or modifying
users through the API. To set up profiles, you must use the salesforce.com user interface.
Access to the profile table is dependent on the permissions of the user doing the operation. A
user must have the VIEW_SETUP permission to query or describe the profile table.
PROFILERECORDTYPE
The profileRecordType entity represents a relationship between a profile and a record type. The
profileRecordType entity indicates that users with the specified profile can create and update
other entities with the given record type. Record types allow you to offer different business
processes and subsets of picklists values to different users based on their profiles.
The describe, insert, update, delete, and query calls support the profileRecordType entity.
You must have the MANAGE_USERS permission to insert, update, and delete the
profileRecordType entity.
If you attempt to insert a profileRecordType that matches an existing profileRecordType record,
Backwards- The profileRecordType entity is useful for organization setup and configuration, but the form of
ProfileRecordType Fields
The following profileRecordType fields are available in the sforce API:
Table 55: ProfileRecordType Fields

Field Description
id String. The ID of the profileRecordType. This field is read-only.
profileID String. The ID of the associated profile.
recordTypeID String. The ID of the associated record type.
tableName String. The name of the entity to which the specified record type
applies. The valid values are listed in the describe response and
include “lead,” “contact,” “account,” and other entity types that
support record types.
A particular record type can apply to only one type of entity.
default Boolean. Indicates whether the record type is the default record type
for users with this profile.
See Also:
RecordType on page 63
RecordTypePicklist on page 64
RECORDTYPE
The recordType entity represents a record type. Record types allow you to offer different
business processes and subsets of picklists values to different users based on their profiles.

The describe and query calls support the recordType entity. Record types are read-only via the
API.
Backwards- The recordType entity is useful for organization setup and configuration, but the form of the
Compatibility entity may change in the future. Salesforce.com cannot guarantee future backwards-
RecordType Fields
The following recordType fields are available in the sforce API:
Table 56: RecordType Fields

Field Description
id String. The ID of the record type.
active Boolean. Indicates whether the record type is active or not. Only
active record types can be used.
name String. The name of the record type.
tableName String. The name of the entity to which this record type applies. The
valid values are listed in the describe response and include “lead,”
“contact,” “account,” and other entity types that support record
types.
A particular record type can apply to only one type of entity.
createdByID String. The ID of the user who created the record type.

time when the record type was created.
lastModifiedByID String. The ID of the user who last updated the record type.

time when the record type was last modified.
See Also:
ProfileRecordType on page 63
RecordTypePicklist on page 64
RECORDTYPEPICKLIST
The recordTypePicklist entity lists the valid values for a picklist for a given record type. Each
recordTypePicklist entry contains one valid picklist value for the given record type, so normally
there will be multiple recordTypePicklist records for each picklist. Record types allow you to offer
different business processes and subsets of picklists values to different users based on their
profiles.
The describe and query calls support the recordTypePicklist entity. RecordTypePicklists are
read-only via the API.
Backwards- The recordTypePicklist entity is useful for organization setup and configuration, but the form of

RecordTypePicklist Fields
The following recordTypePicklist fields are available in the sforce API:
Table 57: RecordTypePicklist Fields

Field Description
id String. The ID of the recordTypePicklist.
recordTypeID String. The ID of the associated record type.
default Boolean. Indicates whether the picklist value is the default value for
the specified record type.
field String. The name of the picklist field as specified in the

“picklistName” member of the describe response. See “fields”
Substructure Members on page 8 for more information about the
“picklistName” member.
value String. The valid picklist value for the specified record type. When
creating a user interface, this value must appear in the drop-down
menu for the picklist field.
See Also:
ProfileRecordType on page 63
RecordType on page 63
ROLE
The role entity allows you to query the set of currently configured roles in the organization. You
cannot insert, update, or delete roles through the sforce API. The purpose of the role table in the
API is to allow you to obtain the valid role IDs for use when querying or modifying users through
the API. To set up roles, you must use the salesforce.com user interface.
All users have access to query or describe the role table.
SOLUTION
Solution Number Field

The solutionNumber field is assigned automatically when a solution is inserted. It cannot be set
directly, and it cannot be modified after the solution is created.
Published Flag
Solutions can have a special status called “published.” (See the salesforce.com online help
documentation for more information on publishing solutions.) A solution's published state does
not affect how you can use a solution, or whether you can query, update, or delete it.
Status Field and Reviewed Flag

The status field is a picklist field that also directly controls the reviewed flag. You cannot
directly set the reviewed flag, but you can set it indirectly by setting the status field. Each
predefined status field value implies a reviewed flag value. Those values are indicated by the
“reviewed” attribute in the struct or map for each element in the “values” attribute for the
status field.

TASKS
whoID and whatID Fields

The task entity has whoID and whatID fields that function like the same fields on the event entity.
See Event on page 48 for more information.
Status Field and Closed Flag

The status field is a picklist that directly controls the closed flag. You cannot directly set the
closed flag, but you can set it indirectly by setting the status field. Each predefined status field
value implies a closed flag value. The values are indicated by the “closed” attribute in the struct
or map for each element in the “values” attribute for the status field.
Due Date Only Field

The due date information for the task entity is contained in the dueDateOnly field. This field is a
Date-Only field with a timestamp that is always set to midnight in the GMT/UTC time zone. The
timestamp is not relevant, and you should not attempt to alter it to account for any time zone
differences. See Date-Only Fields on page 34 for more information.
Archived Activities
Archived tasks are not accessible via the sforce API. See Archived Activities on page 49.
Custom Fields and Page Layouts

Sforce API versions 1.8 and higher support custom fields, page layouts, and field-level security
for task and event entities. See Custom Fields and Page Layouts on page 49.
USER
Provisioning of Users
The user entity allows you to query information about users and to provision and modify users in
the system. Unlike other tables, the records in the user table represent users, not data owned by
users.
All users have access to query or describe the user table. To insert or update a user entity, you
must have the MANAGE_USERS permission.
You cannot delete users in the salesforce.com user interface or the sforce API. To disable a user,
deactivate that user in the salesforce.com user interface. Because users can never be deleted,
we recommend that you exercise caution when creating them.
Username Field
The username field contains the name that a user enters to log into the sforce API or the
salesforce.com user interface. The username must be in the form of an email address. It must
also be unique across all sforce instances. If you try to insert or update a user with a duplicate
username, the operation is rejected and fault code 1229 “duplicate username” is returned.
Each inserted user also counts as a license in sforce. Every organization has a maximum number
of licenses. If you attempt to exceed the maximum number of licenses by inserting users, the
insert request is rejected and fault code 1230 “license limit exceeded” is returned.

Active Flag
The active flag on the user entity determines whether the user has access to log in. You can
modify a user's active status using the salesforce.com user interface or via the sforce API.
Passwords
For security reasons, you cannot query users' passwords via the API or the salesforce.com user
interface. However, the sforce API allows you to set and “reset” users’ passwords using the
set_password and reset_password calls. See The set_password Call on page 25 and The
reset_password Call on page 25 for more information.
The password lockout status and the ability to reset a user's locked-out status is not available via
the API. You must check and reset a user's password lockout status using the salesforce.com
user interface.
Timezone Field
The timezone field is a restricted picklist field. The describe response indicates the valid values
for this field. A user's time zone affects the offset used when displaying or entering times in the
user interface. However, the sforce API does not use a user's time zone when querying or setting
values.
The timezone field values are named using region and key city, according to ISO standards. It
can often be more convenient to manually set a user's time zone in the user interface, and then
use that value for inserting or updating other users via the API.
Locale Field
The locale field is a restricted picklist field. The describe response indicates the valid values for
this field. The value of the locale field affects formatting and parsing of values, especially
numeric values, in the user interface. It does not affect the operation of the sforce API.
The locale field values are named according to the language, and country if necessary, using
two-letter ISO codes. The set of names is based on the ISO standard. It can often be more
convenient to manually set a user's locale in the user interface, and then use that value for
inserting or updating other users via the sforce API.
USERTEAMMEMBER
The userTeamMember entity represents a single user on the default sales team of another user.
Users can set up their default sales team to include the other users that typically work with them
on opportunities. The userTeamMember entity is available only in organizations that have
enabled the team selling functionality.
The describe, insert, update, query, and delete calls support the userTeamMember entity.
You must have the VIEW_ALL_DATA permission to view this entity and the MODIFY_ALL_DATA
If you attempt to insert a userTeamMember that matches an existing userTeamMember record,
UserTeamMember Fields
The following userTeamMember fields are available in the sforce API:
Table 58: UserTeamMember Fields

Field Description

Table 58: UserTeamMember Fields

Field Description
owner String. The ID of the user who owns the default sales team.
This field cannot be updated.
userID String. The ID of the user who is a member of the default

sales team. This field cannot be updated.
opportunityAccessLevel String. The level of access that the team member has to
opportunities for which the user has added his or her default
sales team. Valid values are:
• None - User cannot access the opportunity.
• Read - User can only view the opportunity.
• Edit - User can view or edit the opportunity.
• All - User can view, edit, delete, and share the opportunity
with other users. This value is not valid for inserts and
updates.
teamMemberRole String. The role that the team member has on opportunities
for which the user has added his or her default sales team.
The valid values are set by the organization’s administrator in
the Sales Team Roles picklist.
lastModifiedByID String. The ID of the user who last updated the record.

Date and time when the record was last modified.
See Also:
OpportunityTeamMember on page 59

sforce API Chapter 7: Performance Considerations
CHAPTER 7: Per for mance Consider at ions
The sforce API is designed to provide high performance under most conditions. Several optional
and required features help you optimize the performance of the API. You can initially develop a
client without using many of these features, but you may want to take advantage of most or all
of these features when using clients in production use.
RATE LIMITING
All clients are required to use rate limiting. Clients are metered according to the server resources
they consume which is measured by the amount of time each call takes. Clients that exceed their
instantaneous allowed resources are rate-limited for a period of time. Clients that have been
rate-limited receive fault code 1010 until the rate limit period has expired. The fault message
that accompanies fault code 1010 always starts with an integer, followed by “ms delay:”. The
integer is the number of milliseconds that the client must wait before the rate limit period
expires. Clients should normally wait for the indicated period of time and then retry the request.
Rate limiting is calculated per user based on an estimate of the resource “cost” of each request.
The accumulated cost is stored and updated with each request and declines according to
exponential decay. Rate limits are used to meter server resources, so that one user's actions do
not significantly reduce other users' performance.
Rate limits can be a normal, acceptable response in production use, if the operation you are
performing is relatively expensive. However, they may also indicate that the manner in which
the client is being used may be obtrusively expensive. For example, frequent queries of
excessive number of records or use of inefficient queries can quickly cause rate limiting. The rate
limits can often be reduced by using more focused, efficient queries, especially using sforce
internal IDs, or using last modified timestamps to retrieve just a set of recently modified records.
Most fields in sforce are not indexed, so querying them does not provide fast query times. Sforce
does not index custom fields or most standard fields; ID fields are indexed, though. For example,
if you send a query request that filters on a custom field, the server loads all records that the
user can access to determine which records meet that criteria. This type of request is marginally
faster than returning all records to the client and having the client filter the records itself.
Depending on the server load, the request may still be slow, causing your client to hit its rate
limit quickly. We recommend that you do not make unnecessary query calls, even if the filter
returns a small number of rows. You may need to consider caching some of the information on
the client-side for better performance.
Simulating Rate Limit Conditions

The sforce API provides developers with a tool to simulate rate limit conditions as part of validity
testing. API users can send the HTTP Header “RateLimitAdd” to simulate that a particular call
took additional time to complete. The RateLimitAdd header must specify the number of
additional milliseconds to add to the simulated length of the call, beyond the amount of time the
call actually takes.
For example to simulate that a call took 80 seconds longer, you can send the HTTP header as
follows:
RateLimitAdd: 80000
Because rate limits are calculated based on how long each call takes, the RateLimitAdd header
can be an effective way to simulate rate limits.

sforce API Chapter 7: Performance Considerations
STREAMING
Most clients achieve better performance if they optimize the use of their network connection by
making sure not to pause the sending of large responses to the client. This can often be achieved
by streaming responses to disk, and then reading the response from disk once the entire
response has been received.
BATCHING
Clients can use batching to improve the performance of inserts, updates, and deletes. Instead of
sending individual changes to the server in each request, a group of them can be batched
together. Usually, this significantly improves the performance of sending changes to the server.
See The batch Call on page 22 for more information.
COMPRESSION
Most clients are partially constrained by their network connection, even on a corporate LAN. The
sforce API allows the use of compression to improve performance. Almost all clients can benefit
from response compression, and many clients may benefit from compression of requests as well.
The sforce server supports deflate and gzip compression according the HTTP 1.1 specification.
See Use of Compression on page 28 for more information.
Response Compression
The sforce server can optionally compress responses. Responses are compressed only if the
client sends an Accept-Encoding header with either gzip or deflate compression specified. The
server is not required to compress the response even if you have specified Accept-Encoding, but
it normally does. If the server compresses the response, it also specifies a Content-Encoding
header with the name of the compression algorithm used, either gzip or deflate.
Request Compression
Clients can also compress requests. The sforce server decompresses any requests before
processing. The client must send up a Content-Encoding HTTP header with the name of the
appropriate compression algorithm.
HTTP PERSISTENT CONNECTIONS

Most clients achieve better performance if they use HTTP 1.1 persistent connection to reuse the
socket connection for multiple requests. See the HTTP 1.1 specification for more details -
www.w3.org/Protocols/rfc2616/rfc2616-sec8.html#sec8.1.
HTTP CHUNKING
Clients that use HTTP 1.1 may receive chunked responses. See Variable-Length Responses on

sforce API Appendix A: Frequently Asked Questions
APPENDIX A: Frequentl y Asked Q uest ions
How do I gain access to the sforce API?

You need several things to access the sforce API:
• The complete “sforce Web Services API Reference” technical documentation (this document)
• An Enterprise Edition or Developer Edition organization, and a username and password
within that organization. To sign up for a Developer Edition organization, go to http://
www.sforce.com. To sign up for an Enterprise Edition organization, go to http://
www.salesforce.com, or call 1-800-NO-SOFTWARE in the USA.
• API access for that organization. API access is included when you purchase Enterprise Edition
or sign up for Developer Edition.
• An XML-RPC or SOAP client with which to initiate calls and process responses. Sforce does
not provide any HTTP, XML-RPC, or SOAP client and/or libraries with the sforce API. Go to
http://www.sforce.com for a list of third party providers of libraries and toolkits that work
with the sforce API.
• [Product Partners Only] A valid client ID. You can obtain a client ID from salesforce.com.
Contact salesforce.com for details. You must use the client ID in both the HTTP User-Agent
header and in the client argument to each request.
• Client code to access the sforce API. You must provide the code, based on the details in the
“sforce Web Services API Reference” documentation.
How do I get help if I have a problem?

If you encounter a problem while using the sforce API:
Developer Edition users. Salesforce.com does not provide any technical assistance. You can
solicit help from the developer community message boards available to registered users via the
sforce Web site - http://www.sforce.com.
Enterprise Edition customers. You can contact salesforce.com Customer Support for
assistance:
• Submit a case online. Log in to the salesforce.com user interface. Click Support in the upper
right of any page. Click Customer Self-Service, and then choose Log a Service Ticket.
• Call Customer Support. Log in to the salesforce.com user interface, and click Support in the
upper right of any page to access Customer Support phone numbers.
You must provide a description of what you are doing and the request that you are using. The
example request must include both the XML body and the HTTP headers. Salesforce.com will not
be able to assist you unless you provide both.
Invalid <?xml version="1.0" encoding="UTF-8" ?>

Sample <methodCall>
<methodName>sfdc.login</methodName>
Request for
<params><param><value><struct>
Assistance <member>
<name>version</name>
<value><string>2.0</string></value>
</member>
<member>
<name>username</name>
<value><string>USERNAME</string></value>

sforce API
</member>
<member>
<name>password</name>
<value><string>PASSWORD</string></value>
</member>
</struct></value></param></params>
</methodCall>
Acceptable You must provide the HTTP headers with the call.
Sample POST /servlet/servlet.Api HTTP/1.1
Request for Connection: close
Host: www.salesforce.com
Assistance Content-Type: text/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<methodCall>
<member>
</member>
<member>
</member>
<member>
</member>
</methodCall>
Can I purchase additional technical support for the sforce API?

Technical support for coding issues relating to use of the sforce API is available to Enterprise
Edition subscribers of the Advanced Integration Service only. This option is targeted at those
customers needing a higher level of service and integration support as compared to the
standard, free support offered with Enterprise Edition. Contact your Account Executive for pricing
and program details.
Additional technical support is not available for Developer Edition. Users can solicit help from the
developer community message boards available to registered users via the sforce Web site -
http://www.sforce.com.
Is there support for the sforce API in EMEA and Japan?

Yes. The sforce API is supported on all sforce instances. See Chapter 4: Multiple Instance
Support on page 31 for more information.
How do I write the HTTP headers?

To use the sforce API, you must be able to write and read the HTTP headers for a request. At a
minimum, you should be able to set and read the Cookie and Set-Cookie headers, and the
Accept-Encoding and Content-Encoding headers. The manner in which you set and read headers
is specific to each HTTP library or to a higher-level XML or XML-RPC library. You must read the
documentation for the libraries that you are using. Salesforce.com cannot provide help or
debugging with client-side libraries. Go to http://www.sforce.com for a list of third-party
providers of libraries and toolkits that work with the sforce API.

sforce API
How do I specify all fields and all records for a query?

The query call requires a “filter” argument and a “select” argument. The “filter” argument can
be an empty array, which returns all visible records of that type. The “select” argument cannot
be empty. To select all columns, you must specify a list of all columns that are returned by the
describe call for that entity type. See The query Call on page 19 for more information.

sforce API Appendix B: Entity Relationship Diagrams
APPENDIX B: Ent i t y Relat ionship Diag r ams
MAJOR ENTITIES
See page 75 for the relationship diagram of the major entities.
TASK AND EVENT ENTITIES

See page 76 for the relationship diagram describing the task and event entities.
SUPPORT ENTITIES
See page 76 for the relationship diagram describing the customer support entities.
DOCUMENT, NOTE, AND ATTACHMENT ENTITIES

See page 77 for the relationship diagram describing the document, note, and attachment
entities.
USER, RECORD TYPES, AND CUSTOM F IELD ENTITIES

See page 77 for the relationship diagram describing the user, record types, and custom field
entities.
PRODUCT AND SCHEDULE ENTITIES

See page 78 for the relationship diagram describing the pricebook, product, and schedule
entities.
SHARING AND TEAM SELLING ENTITIES

See page 78 for the relationship diagram describing the sharing and team selling entities.

1
sforce API
Major Entities
Campaign Solution Case

CaseSolution
id
id id id
caseID OwnerID
Name SolutionNumber caseID
CaseNumber
Active Title solutionID solutionID
Contact ID
OwnerID Published CreatedDate
CaseTy pe
CreatedDate Status CreatedBy ID
CaseReason
CreatedBy ID Rev iewed
Status
Last Modif iedDate Description
Priority
Last Modif iedBy ID OwnerID Case Origin
CreatedDate
contactID EmailAddress
CreatedBy ID
Name
Last Modif iedDate
CampaignID Company
Last Modif iedBy ID
Phone
ClosedDate
Subject
Description
Campaignmember Closed
Escalated
CampaignID CreatedDate
LeadID Contact Account CreatedBy ID
Contact ID Last Modif iedDate
Status id id Last Modif iedBy ID
Responded OwnerID Owner_ID
CreatedDate Salutation Account_Name
CreatedBy ID First Name Account_Site
Last Modif iedDate Last Name
parentAccountID Parent_Account_ID
Last Modif iedBy ID Account ID Account_Number
Title Opportunity
Account_Ty pe
OR Department Industry
Birthdate id
contactID Annual_Rev enue
Reports ToID OwnerID
leadID Account_Rating Priv ate
LeadSource Account_Phone
Business Phone Name
Account_Fax accountID
HomePhone Account ID
accountID Website Opportunity Ty pe
MobilePhone Ticker_Sy mbol
Lead OtherPhone LeadSource
Ownership Amount
Business Fax Employ ees
id ExpectedAmount
OwnerID EmailAddress SIC_Code
Assistant's Name CloseDate
Salutation Billing_Street
Next Step
First Name reportsToID Asst. Phone Billing_City
EmailOpt Out Stage
Last Name Billing_State Probability
Mailing Street Billing_Zip/Postal_Code
Company Description
MailingCity Billing_Country
Title Closed
MailingState Shipping_Street
LeadSource Won
MailingZip/PostalCode Shipping_City
Industry Forecast Category
MailingCountry Shipping_State
AnnualRev enue CreatedDate
OtherStreet Shipping_Zip/PostalCode
Phone CreatedBy ID
OtherCity Shipping_Country
MobilePhone Last Modif iedDate
OtherState Account_Description
Fax Last Modif iedBy ID
OtherZip Created_Date
Email
OtherCountry Created_By _ID
Website
Contact Description Last Modif ied_Date
Status
CreatedDate Last Modif ied_By _ID
Rating
Employ ees CreatedBy ID
Last Modif iedDate
EmailOpt Out
Last Modif iedBy ID
Street
opportunity ID
City
State accountToID
Zip
Country contactID Partners
Description
Conv erted accoutFromID opportunity ID
Conv ertedAccount ID
accountFromID
Conv ertedContact ID
accountToID
Conv ertedOpportunity ID Opportunity ContactRole
id
CreatedDate
role
CreatedBy ID id
primary
Last Modif iedDate Opportunity ID
createdBy ID
Last Modif iedBy ID Contact ID
Role createdDate
Primary lastModif iedBy ID
lastModif iedDate
CreatedDate
CreatedBy ID
Last Modif iedDate
Last Modif iedBy ID
opportunity ID

sforce API
Task and Event Entities
Lead Contact
id id
whoID OR whoID
Task Event
id id
Account ID Account ID
Who ID Who ID
What ID What ID
Subject Subject
M aster Event ID M aster Event ID
Location Location
All Day All Day
Due Date Due Date
Duration Duration
Description Description
Owner ID Owner ID
Created Date Created Date
Created By ID Created By ID
Last M odified Date Last M odified Date
Last M odified By ID Last M odified By ID
Note : Task and Event entities relate to Account, Opportunity, Campaig n, or Case entities via the whatID.
Task and Event entities relate to Lead or Contact entities via the whoID.
Task and Event entities can also related to an Account entity via the accountID.
OR whatID OR OR
whatID whatID
whatID
Campaig n Account Opportunity Case

accountID
id id id id
Support Entities
contactID Contact
Solution Case
CaseSolution
id
id id id
caseID Owner ID
Solution Number caseID
solutionID solutionID Case Number
Title
Created Date Contact ID
Published
Case Type
Status Created By ID
Case Reason
Reviewed Status
Description Priority
Owner ID Case Comment Case Orig in
Created Date
Email Address
Created By ID id Name
Last M odified Date Parent ID Company
Last M odified By ID Published parentID
Phone
Body Closed Date
Created By ID Subject
Created Date Description
Closed
Escalated
Created Date
CaseHistory Created By ID
id Last Modified Date
case ID Last Modified By ID
field caseID
oldValue
newValue
Created Date
Created By ID

sforce API
Document, Note, and Attachment Entities

User
Document Folder
id id
author name id
folderID name
folderID type
type
body g lobal
bodyLeng th sortOrder
description Created By ID
author Created Date
Created By ID Last M odified Date
Created Date Last M odified By ID
Last M odified Date
Last M odified By ID
Campaig n
Note Attachment
id
id parentID
id
Parent ID
Parent ID
File Name
Title Solution
Private
Private Body Leng th parentID
Body Body
Owner ID id
Owner ID
Created Date Created By ID
Created By ID Created Date
Last M odified Date Last M odified Date parentID
Last M odified By ID parentID Case
Last Modified By ID
id
parentID parentID
parentID
Account Contact Opportunity
id id id
parentID
parentID
User, Record Types, and Custom Field Entities

User Profile ProfileRecordType
id
id id
profileID profileID
Username Name profileID recordTypeID
First Name Created Date
tableName
Note : All own e r, Last Name Created By ID
isDefault
cre a te dB yID, a nd Company Name Last M odified Date
la stM o dif ied B yID field s on Division Last M odified By ID
o th e r en titie s rela te to the Department
u se r e ntit y. Title profileID
Street roleID Role
City
State id RecordType
Zip Name
Country
Parent Role ID id
E-mail Description active
Phone
name
Fax
tableName
Cell
Created Date
Alias
Created By ID
Active
Last Modified Date
Time Zone
CustomFieldDefinition Last Modified By ID
Role ID
Locale id
Info Emails
tableName
Email Encoding label profileID
Profile ID dataType
Lang uag e
leng th
Last Log in precision
Created Date RecordTypePicklist
scale
Created By ID id
Created By ID
Last M odified Date recordTypeID
Created Date
Last Modified By ID Last M odified Date isDefault
Last M odified By ID field
value

sforce API
Product and Schedule Entities
OpportunityLineItemSchedule Opportunity Line Item Product PriceBook
id id id id
Line Item ID Opportunity ID Price Book ID Name
Revenue Date lineItemID Name
Product ID Currency ISO Code
Amount Quantity Product Code priceBookID Active
Comments Total Price Default Unit Price Last M odified Date
Service Date Description
productID
Has Schedule Schedule Type
Created Date Installment Period
Created By ID Number Of Installments
Last M odified Date Active
Last Modified By ID Created Date
Created By ID
Last Modified Date
opportunityID Last Modified By ID
Opportunity
id
Sharing and Team Selling Entities
Account Opportunity
id id
OpportunityTeamM ember
accountID opportunityID id
opportunityID opportunityID
userID
AccountShare OpportunityShare opportunityAccessLevel
teamM emberRole
id Last M odified Date
id
accountID Last M odified By
opportunityID
userOrGroupID
userOrGroupID
accountAccessLevel OpportunityAccessLevel
OpportunityAccessLevel
rowCause
rowCause
Last M odified Date
Last M odified Date userID
Last M odified By
Last M odified By
OR OR
userOrGroupID userOrGroupID
userOrGroupID
User
Group GroupM ember
id
id id
name g roupID
relatedID userOrGroupID owner userID
type g roupID
OR
Created Date userOrGroupID UserTeamM ember
Created By ID
Last M odified Date id
Last M odified By userOrGroupID owner
userID
opportunityAccessLevel
relatedID
teamM emberRole
Last M odified Date
Role Last M odified By
id
userOrGroupID

sforce API Appendix C: Fault Codes
APPENDIX C: Fa ult Codes
Sforce API requests can return a successful response or a fault response. A fault response
indicates that the request could not be completed. A fault response is composed of an error code
and a text message. The fault message is a short description in English that can be displayed to
the user as a minimally descriptive error message. If you display the fault message, you should
also display the fault code. Clients should always recognize the fault codes, not the fault
messages. The actual fault messages may vary slightly from the messages listed in this
appendix.
Some faults are particular to certain calls, while others are more general faults that could happen
on any call, such as error code 1000 for a null parameter list. In the section Fault Codes Common
to Specific Calls on page 82, each subsection lists fault codes that commonly occur with a
particular call. However, the fault codes listed for a particular call could occur with any other call
as well.
Beyond the fault codes, clients should also check that the response Content-Type in the HTTP
header is “text/xml.” Any other type, such as “text/html,” indicates that the application server is
down or unreachable, such as being blocked by a firewall.
HTTP, XML, AND XML-RPC LEVEL FAULTS

Fault codes ‘0’ and ‘-1’ are used for general faults.
Table 59: HTTP, XML, and XML-RPC Fault Responses

Code Message
0 Invalid XML or XML-RPC syntax. Usually indicates a development error

on the client. The server does not attempt to inform you about how to
correct the XML or XML-RPC. You must validate the request on your
own.
-1 Unspecified internal API error while processing the request. Usually

indicates a runtime error on the server. Contact salesforce.com for
more help.
HTTP HEADERS AND XML-RPC PARAMETER FAULTS

Codes 1000 to 1099 indicate problems with XML-RPC parameters or HTTP headers.
Table 60: HTTP Headers and XML-RPC Parameter Fault Responses

Code Message
1000 Null parameter list
1001 Zero length parameter list
1002 Greater than 1 parameter
1003 The one parameter was null
1004 Parameter was not a struct or a map

Table 60: HTTP Headers and XML-RPC Parameter Fault Responses

Code Message
1005 Session ID required in cookie for non-login request
1006 Invalid Content-Encoding
1007 API currently disabled
1008 API not enabled for this user or organization
1009 User or organization is not allowed to use the API during this time
period, or has exceeded its API quota for this time period.
1010 User or organization has exceeded rate limit. Sleep and try again in 'X'
ms (where 'X' is an integer listed at the beginning of the text message
and followed by “ms delay:”)
1011 Servers temporarily unavailable
ARGUMENT FAULTS
Codes 1100 to 1199 indicate problems with arguments inside a single struct or map parameter.
They normally indicate a bug in the client code.
Table 61: Argument-Level Fault Responses

Code Message
1100 Argument was not specified
1101 Argument was of wrong type
1111 Invalid type (must be “contact,” “account,” etc.)
1112 Invalid login (username and password)
1113 Invalid operation (“sfdc.list,” “sfdc.get,” etc.)
1114 Unsupported version
1115 Invalid client or user-agent
1116 Unsupported client or user-agent
USER-LEVEL FAULTS
Codes in the 1200 range indicate user-level problems.
Table 62: User-Level Fault Responses

Code Message
1200 Invalid type for the operation
1201 Invalid ID field
1202 Invalid cross-reference key
1203 Cannot set owner to empty key


Code Message
1204 Required field is missing in insert/update
1205 User does not have sufficient rights
1206 Arguments not specified to batch operation
1207 Arguments to batch must be an array
1208 Batch argument must be a struct or a map
1209 Delete operation failed because the entity is referenced by another

object
1210 User does not have an email address
1211 Username could not be resolved
1212 Invalid value type of a field in the record
1213 Functionality is currently disabled
1215 Cross-reference type is not valid for the field
1218 Bad field name in query call
1219 Query filter value of wrong type
1220 Field is not filterable
1221 Text data is outside of the supported character set
1222 Storage limit exceeded
1223 Invalid operator in query filter criterion
1224 Invalid batch operation
1225 Invalid or null value for a restricted picklist field
1226 Invalid currency ISO code
1227 Entity type is read-only
1228 Entity is deleted (on an update or delete operation)
1229 Duplicate username in insert/update user call
1230 License limit exceeded
1231 Field integrity exception
1232 Cannot update converted lead
1233 Number outside of valid range
1236 Bad field names on insert/update call
1239 Insufficient access rights on cross-reference entity
1240 Owner or user is inactive
1241 Invalid status
1242 Entity is currently locked


Code Message
1246 Entity is archived
1247 Assignment rule is invalid or not defined for the organization
1248 Attachment or document data has exceeded maximum size limit for
uploads
1249 Relationship between case and solution already exists
1250 Sharing entry cannot be deleted because it is needed for access to

associated child record
1251 Cannot change ownership or change sharing because new owner does
not have sharing access to associated parent record
1252 Circular dependency not allowed (as in a group)
1253 Malformed ID; ID must be 15 or 18 characters
1254 Invalid search terms
FAULT CODES COMMON TO SPECIFIC CALLS

Some faults are particular to certain calls, while others are more general faults that could happen
on any call. The sections below lists fault codes that commonly occur with a particular call.
However, the fault codes listed for a particular call could occur with any other call as well.
login Fault Codes
Table 63: Common login Fault Responses

Code Message
1005 Session ID required in cookie for non-login request
1008 API is not enabled for this user or organization
1012 Trial period expired
1112 Invalid username and password, or the session not authenticated
1900 User is not allowed to log in during restricted times
1901 User is not allowed to log in from his domain
1902 User has been locked out due to repeated failed login attempts
1903 The organization has been locked, closed, suspended, or deactivated.
logout Fault Codes

The logout call can generate various fault responses, for example, if the session ID is invalid.
describe Fault Codes

Common fault responses for the describe call are only those that can happen with most any call,
such as invalid authentication or bad entity type name.

insert Fault Codes
Table 64: Common insert Fault Responses

Code Message
1202 Invalid cross-reference key
1203 Cannot set owner to empty key
1204 Required field is missing
1205 User does not have sufficient rights (This can happen if the user does
not have sufficient rights to a referenced entity.)
1212 Invalid type for the value of a field in the record struct or map
1215 Cross-reference key type is not valid for this field
1221 Text data is outside of supported character set
1222 Storage limit exceeded
1233 Number outside of valid range
1236 bad field names on insert/update call
update Fault Codes

Common fault responses are similar to the insert call (see insert Fault Codes on page 83).
Additional common faults are:
Table 65: Common update Fault Responses

Code Message
1201 The ID for the update call is invalid
1100 A required argument, such as the id field, is missing
1205 Insufficient access rights on this record, or on a cross-referenced field
1236 bad field names on insert/update call
delete Fault Codes
Table 66: Common delete Fault Responses

Code Message
1100 Required parameter, such as the id parameter, is missing
1201 Invalid id value
1205 User does not have sufficient rights for that entity
1209 Entity cannot be deleted

query Fault Codes
Table 67: Common query Fault Responses

Code Message
1100 Filter criterion in query call must contain a value argument
1218 Bad field name in query call
1219 Query filter value of wrong type
1220 Field is not filterable
1223 Invalid operator in query filter criterion
1234 Query exceeded maximum time allowed
1237 Query exceeded maximum number of rows
1245 batch/bulk ID query size limit exceeded
2000 Query with scope parameter cannot specify select, filter, or idList
batch Fault Codes

A batch call can have faults with the entire batch or just with individual elements of the batch. A
fault with the entire batch operation is reported as a normal fault. Common faults of this type
are:
Table 68: Common batch Fault Responses

Code Message
1206 Arguments not specified to batch operation
1207 Arguments to batch must be an array
1245 batch/bulk ID query size limit exceeded
Faults on individual elements of the batch call are reported as faults in the element of the
response array. The other elements of the batch are still processed. An individual batch element
that has a fault is returned as an array of two elements. The first element is the integer fault
code. The second element is the string fault message.
search Fault Codes
Table 69: Common search Fault Responses

Code Message
1011 Search is temporarily unavailable. In rare cases, search can be

unavailable even if other operations are available.
1100 Search value cannot be blank
1100 Invalid search scope
1113 Search is not available on this instance, or for this organization

sforce API
Table 69: Common search Fault Responses

Code Message
1113 Entity type does not support search

sforce API Appendix D: XML-RPC Examples
APPENDIX D: XML-RPC Examples
Example XML-RPC requests and responses are included for each call. Each call must be contained in an HTTP
request with appropriate HTTP headers. The HTTP headers are not shown in the examples, as they are either
fixed or vary by the client.
Most calls take a session HTTP header cookie for authentication. The value for that session ID is obtained from
the response to the login call. An example HTTP cookie header for the session value would be:
Cookie: sid=1tfY2dmkMSWr3_.R0tbU1dbXHYna29zdqonw8Mmxy_s=; Path=/
The XML-RPC examples are indented for readability. The sforce API is not sensitive to indenting. The examples
could be passed “as is” to the API, or they could be passed as one long line of text without any formatting.
Responses from the sforce API are not normally formatted, without newlines (unless the data contains
newlines). You can obtain indented responses for readability and debugging purposes by specifying the HTTP
header: PrettyPrint: Yes. You should not use the PrettyPrint header for actual production use, though (see
Use of Headers on page 29 for more information).
LOGIN CALL XML-RPC EXAMPLES
login Request
<?xml version="1.0"?>
<methodCall>
<member>
</member>
<member>
</member>
<member>
</member>
<member>
<name>secure</name>
<value><boolean>1</boolean></value>
</member>
</methodCall>
login Response
<methodResponse>
<member>
<name>server_url</name>

<value>https://ssl.salesforce.com/servlet/servlet.Api</value>
</member>
<member>
<name>session_id</name>
<value>Q0DEqyenM0pEfH17f2AgFmNkZWZuKgECJFxdX19dXfRC=</value>
</member>
</methodResponse>
LOGOUT CALL XML-RPC EXAMPLES
logout Request
<methodCall>
<methodName>sfdc.logout</methodName>
<member>
</member>
</methodCall>
logout Response
A successful response is empty.
<methodResponse>
<params><param>
<value></value></param>
</params>
</methodResponse>
GLOBAL DESCRIBE CALL XML-RPC EXAMPLES
global describe Request

<methodCall>
<methodName>sfdc.describe</methodName>
<member>
</member>
<member>
<name>type</name>
<value><string>global</string></value>
</member>
</methodCall>

global describe Response

The response to a global describe call can vary based on the organization and user permissions, and the
instance it is performed on. A typical global describe response is:
<methodResponse>
<params><param>
<value><struct>
<member><name>types</name>
<value>
<array>
<data>
<value>event</value>
<value>task</value>
<value>opportunity</value>
<value>account</value>
<value>contact</value>
<value>solution</value>
<value>note</value>
<value>lead</value>
<value>case</value>
<value>user</value>
<value>profile</value>
<value>role</value>
<value>product</value>
<value>pricebook</value>
</data>
</array></value>
</member>
<member><name>maxBatchSize</name>
<value><int>500</int></value>
</member>
<member><name>encoding</name>
<value>ISO-8859-1</value>
</member></struct></value></param>
</params>
</methodResponse>
DESCRIBE CALL XML-RPC EXAMPLES
describe Request for Accounts

An example of an entity-specific describe call (in this case, for accounts) is:
<methodCall>
<methodName>sfdc.describe</methodName>
<member>
</member>
<member>
<name>type</name>
<value><string>account</string></value>

</member>
</methodCall>
You can describe any other entity type by replacing the value “account” in the “type” member with any other
entity type returned as part of the global describe response.
describe Response for Accounts

Note that the description of each entity may change in the future. In addition, the response may differ for
different users, based on the user's access rights and the custom fields defined for that organization.
<methodResponse>
<params><param>
<value><struct>
<member><name>access</name>
<value>
<array>
<data>
<value>query</value>
<value>insert</value>
<value>update</value>
<value>delete</value>
<value>idList</value>
<value>search</value>
</data>
</array></value>
</member>
<member><name>fields</name>
<value>
<array>
<data>
<value><struct>
<value>
<array>
<data>
<value>select</value>
<value>filter</value>
</data>
</array></value>
</member>
<member><name>type</name>
<value>string</value>
</member>
<member><name>field</name>
<value>id</value>
</member>
<member><name>display</name>
<value><struct>
<value>id</value>
</member></struct></value>
<value><struct>
<member><name>label</name>

<value>Owner ID</value>
</member>
</member>
<value>ownerID</value>
</member>
<value><struct>
<value>reference</value>
</member>
<member><name>referenceTo</name>
<value>user</value>
</member>
<member><name>nullable</name>
<value>
<boolean>0
</boolean></value>
<value><struct>
<value>Account Name</value>
</member>
</member>
<member><name>length</name>
</member>
<value>name</value>
</member>
<member><name>nullable</name>
<value>
<boolean>0
</boolean></value>
<value><struct>
<value>Account Site</value>
</member>
</member>
</member>
<value>site</value>
<value><struct>

<value>Parent Account ID</value>

</member>
</member>
<value>parentID</value>
</member>
<value><struct>
</member>
<value>account</value>
<value><struct>
<value>Account Number</value>
</member>
</member>
</member>
<value>accountNumber</value>
<value><struct>
<value>Account Type</value>
</member>
</member>
</member>
<value>type</value>
</member>
<value><struct>
<member><name>values</name>
<value>
<array>
<data>
<value><struct>
<member><name>value</name>
<value>Analyst</value>
<value><struct>

<value>Competitor</value>
<value><struct>
<value>Customer</value>
<value><struct>
<value>Integrator</value>
<value><struct>
<value>Investor</value>
<value><struct>
<value>Partner</value>
<value><struct>
<value>Press</value>
<value><struct>
<value>Prospect</value>
<value><struct>
<value>Reseller</value>
<value><struct>
<value>Other</value>
</data>
</array></value>
</member>
<value>picklist</value>
<value><struct>
<value>Industry</value>
</member>
</member>
</member>
<value>industry</value>
</member>

<value><struct>
<value>
<array>
<data>
<value><struct>
<value>Agriculture</value>
<value><struct>
<value>Apparel</value>
<value><struct>
<value>Banking</value>
<value><struct>
<value>Biotechnology</value>
<value><struct>
<value>Chemicals</value>
<value><struct>
<value>Communications</value>
<value><struct>
<value>Construction</value>
<value><struct>
<value>Consulting</value>
<value><struct>
<value>Education</value>
<value><struct>
<value>Electronics</value>
<value><struct>
<value>Energy</value>
<value><struct>
<value>Engineering</value>
<value><struct>

<value>Entertainment</value>
<value><struct>
<value>Environmental</value>
<value><struct>
<value>Finance</value>
<value><struct>
<value>Food & Beverage</value>
<value><struct>
<value>Government</value>
<value><struct>
<value>Healthcare</value>
<value><struct>
<value>Hospitality</value>
<value><struct>
<value>Insurance</value>
<value><struct>
<value>Machinery</value>
<value><struct>
<value>Manufacturing</value>
<value><struct>
<value>Media</value>
<value><struct>
<value>Not For Profit</value>
<value><struct>
<value>Recreation</value>
<value><struct>
<value>Retail</value>
<value><struct>

<value>Shipping</value>
<value><struct>
<value>Technology</value>
<value><struct>
<value>Telecommunications</value>
<value><struct>
<value>Transportation</value>
<value><struct>
<value>Utilities</value>
<value><struct>
</data>
</array></value>
</member>
<value><struct>
<value>Annual Revenue</value>
</member>
<value>double</value>
</member>
<value>sales</value>
</member>
<value><struct>
<member><name>precision</name>
</member>
<value>currency</value>
</member>
<member><name>scale</name>
<value><struct>
<value>Account Rating</value>

</member>
</member>
</member>
<value>rating</value>
</member>
<value><struct>
<value>
<array>
<data>
<value><struct>
<value>Hot</value>
<value><struct>
<value>Warm</value>
<value><struct>
<value>Cold</value>
</data>
</array></value>
</member>
<value><struct>
<value>Account Phone</value>
</member>
</member>
</member>
<value>accountPhone</value>
</member>
<value><struct>
<value>phone</value>
<value><struct>

<value>Account Fax</value>
</member>
</member>
</member>
<value>accountFax</value>
</member>
<value><struct>
<value>phone</value>
<value><struct>
<value>Website</value>
</member>
</member>
</member>
<value>url</value>
</member>
<value><struct>
<value>url</value>
<value><struct>
<value>Ticker Symbol</value>
</member>
</member>
</member>
<value>ticker</value>
<value><struct>
<value>Ownership</value>
</member>

</member>
</member>
<value>ownership</value>
</member>
<value><struct>
<value>
<array>
<data>
<value><struct>
<value>Public</value>
<value><struct>
<value>Private</value>
<value><struct>
<value>Subsidiary</value>
<value><struct>
</data>
</array></value>
</member>
<value><struct>
<value>Employees</value>
</member>
<value>i4</value>
</member>
<value>employees</value>
</member>
<value><struct>
<member><name>digits</name>
<value><struct>

<value>SIC Code</value>
</member>
</member>
</member>
<value>sic</value>
<value><struct>
<value>Billing Street</value>
</member>
</member>
</member>
<value><struct>
<value>textarea</value>
</member>
<value>billingStreet</value>
<value><struct>
<value>Billing City</value>
</member>
</member>
</member>
<value><struct></struct></value>
</member>
<value>billingCity</value>
<value><struct>
<value>Billing State</value>
</member>
</member>

</member>
</member>
<value>billingState</value>
<value><struct>
<value>Billing Zip/Postal Code</value>
</member>
</member>
</member>
</member>
<value>billingPostalCode</value>
<value><struct>
<value>Billing Country</value>
</member>
</member>
</member>
</member>
<value>billingCountry</value>
<value><struct>
<value>Shipping Street</value>
</member>
</member>
</member>
<value><struct>
</member>

<value>shippingStreet</value>
<value><struct>
<value>Shipping City</value>
</member>
</member>
</member>
</member>
<value>shippingCity</value>
<value><struct>
<value>Shipping State</value>
</member>
</member>
</member>
</member>
<value>shippingState</value>
<value><struct>
<value>Shipping Zip/Postal Code</value>
</member>
</member>
</member>
</member>
<value>shippingPostalCode</value>
<value><struct>
<value>Shipping Country</value>
</member>

</member>
</member>
</member>
<value>shippingCountry</value>
<value><struct>
<value>total sales</value>
</member>
<value>double</value>
</member>
<member><name>custom</name>
<value>
<boolean>1
</boolean></value>
</member>
<value>00N000000000na9</value>
</member>
<value><struct>
<member><name>precision</name>
</member>
<member><name>scale</name>
<value><struct>
</member>
</member>
</member>
<member><name>custom</name>
<value>
<boolean>1
</boolean></value>
</member>
<value>00N000000000mHm</value>
</member>

<value><struct>
<value>
<array>
<data>
<value><struct>
<value>a</value>
<value><struct>
<value>b</value>
</data>
</array></value>
</member>
<value><struct>
<value>
<array>
<data>
<value>insert</value>
<value>update</value>
</data>
</array></value>
</member>
<value>Account Description</value>
</member>
</member>
</member>
<value>description</value>
</member>
<value><struct>
<value><struct>
<value>
<array>
<data>

</data>
</array></value>
</member>
<value>Created Date</value>
</member>
<value>dateTime.iso8601</value>
</member>
<value>createdDate</value>
</member>
<value><struct>
<value>datetime</value>
<value><struct>
<value>
<array>
<data>
</data>
</array></value>
</member>
<value>Created By ID</value>
</member>
</member>
<value>createdByID</value>
</member>
<value><struct>
</member>
<value>user</value>
<value><struct>
<value>
<array>
<data>
</data>

</array></value>
</member>
<value>Last Modified Date</value>
</member>
<value>dateTime.iso8601</value>
</member>
<value>lastModifiedDate</value>
</member>
<value><struct>
<value>datetime</value>
<value><struct>
<value>
<array>
<data>
</data>
</array></value>
</member>
<value>Last Modified By ID</value>
</member>
</member>
<value>lastModifiedByID</value>
</member>
<value><struct>
</member>
<value>user</value>
</data>
</array></value>
</params>
</methodResponse>

INSERT CALL XML-RPC EXAMPLES
insert Request (for a contact)

<methodCall>
<methodName>sfdc.insert</methodName>
<member>
</member>
<member>
<name>type</name>
<value><string>contact</string></value>
</member>
<member>
<name>record</name>
<value><struct>
<member><name>firstName</name><value>Jim</value></member>
<member><name>lastName</name><value>Smith</value></member>
<member><name>accountID</name>
<value>0010000000000O9</value></member>
<member><name>title</name><value>VP of Sales</value></member>
<member><name>email</name>
<value>[email protected]</value></member>
<member><name>businessPhone</name>
<value>777-7777</value></member>
<member><name>mailingAddress</name>
<value>1 Main St.</value></member>
<member><name>mailingAddressCity</name>
<value>Seattle</value></member>
<member><name>mailingAddressState</name>
<value>WA</value></member>
<member><name>description</name>
<value>Jim is good</value></member>
</struct></value>
</member>
</methodCall>
insert Response
<methodResponse>
<params><param>
<value><struct>
<member><name>changed</name>
<value><struct>
<value>[email protected]</value>
</member>
<member><name>id</name>

<value>003000000008N56</value>
</params>
</methodResponse>
UPDATE CALL XML-RPC EXAMPLES
update Request (for a contact)

<methodCall>
<methodName>sfdc.update</methodName>
<member>
</member>
<member>
<name>type</name>
</member>
<member>
<name>record</name>
<value><struct>
<value>003000000008N56</value></member>
<member><name>firstName</name>
<value>James</value></member>
<value>0010000000000O9</value></member>
<member><name>title</name>
<value>VP of Sales</value></member>
<value>[email protected]</value></member>
</struct></value>
</member>
</methodCall>
update Response
The response for an update call is the same as for an insert call (see insert Response on page 106).
DELETE CALL XML-RPC EXAMPLES
delete Request (for a contact)

<methodCall>
<methodName>sfdc.delete</methodName>
<member>

</member>
<member>
<name>type</name>
</member>
<member>
<name>id</name>
<value><string>003000000007ySI</string></value>
</member>
</methodCall>
delete Response
A successful delete response is empty. An unsuccessful call generates a fault response.
QUERY CALL XML-RPC EXAMPLES
“filter” query Request (specifying a single criterion for a contact)

<methodCall>
<methodName>sfdc.query</methodName>
<member>
</member>
<member>
<name>type</name>
</member>
<member>
<name>filter</name>
<value><array>
<value><struct>
<member><name>field</name><value>lastName</value></member>
<member><name>value</name><value>Benioff</value></member>
</struct></value>
</array></value>
</member>
<member>
<name>select</name>
<value><array>
<value>id</value>
<value>lastName</value>
<value>firstName</value>
<value>accountID</value>
<value>department</value>
<value>reportsToID</value>
</array></value>
</member>

</methodCall>
“filter” query Request (specifying a simple OR filter of two fields)

For brevity, the example shows only the “filter” member the request. The OR filter in the example is (lastName
= “Benioff” OR lastName = “Sclavos”).
<member><name>filter</name>
<value><array><value><struct>
<member><name>operator</name><value>or</value></member>
<member><name>value</name><value><array>
<value><struct>
<member><name>value</name><value>Benioff</value></member>
</struct></value>
<value><struct>
<member><name>value</name><value>Sclavos</value></member>
</struct></value>
</array></value></member>
</struct></value></array></value></member>
“filter” query Request (specifying nested Boolean combination filters)

For brevity, the example shows only the “filter” member the request. The nested AND, OR, and NOT filter
combination in the example is (lastName = “Smith” AND (firstName = “John” OR firstName = “Mike”) AND NOT
(birthdate >= Jan 1 1970)).
<member><name>filter</name>
<value><array>
<value><struct>
<member><name>value</name><value>Smith</value></member>
</struct></value>
<value><struct>
<member><name>operator</name><value>or</value></member>
<member><name>value</name><value><array>
<value><struct>
<member><name>field</name><value>firstName</value></member>
<member><name>value</name><value>John</value></member>
</struct></value>
<value><struct>
<member><name>field</name><value>firstName</value></member>
<member><name>value</name><value>Mike</value></member>
</struct></value>
</struct></value>
<value><struct>
<member><name>operator</name><value>not</value></member>
<member><name>value</name><value><struct>
<member><name>operator</name><value>greater than</value></member>
<member><name>field</name><value>birthdate</value></member>
<value><dateTime.iso8601>19700101T00:00:00</dateTime.iso8601></value>
</member>
</struct></value></member>
</struct></value>

query Response
<methodResponse>
<params><param><value>
<array><data>
<value><struct>
<member><name>id</name><value>003000000000aBc</value></member>
<member><name>lastName</name><value>Benioff</value></member>
<member><name>firstName</name><value>Marc</value></member>
<value>001000000000146</value></member>
<member><name>department</name>
<value>Executive</value></member>
<member><name>reportsToID</name>
</struct></value>
<value><struct>
<member><name>id</name><value>003000000000654</value></member>
<member><name>lastName</name><value>Benioff</value></member>
<member><name>firstName</name><value>Jim</value></member>
<member><name>department</name>
<value>Sales</value></member>
<member><name>reportsToID</name>
<value>003000000000aBc</value></member>
</struct></value>
</data></array>
</value></param></params>
</methodResponse>
BATCH CALL XML-RPC EXAMPLES
batch Request (for inserting contacts)

<methodCall>
<methodName>sfdc.batch</methodName>
<member>
</member>
<member>
<name>type</name>
</member>
<member>
<name>operation</name>
<value><string>insert</string></value>
</member>

<member>
<name>arguments</name>
<value><array>
<value><struct>
<member><name>firstName</name><value>Jane</value></member>
<member><name>lastName</name><value>Smith</value></member>
</struct></value>
<value><struct>
<member><name>lastName</name><value>Jones</value></member>
<member><name>businessPhone</name>
<value>555-9999</value></member>
</struct></value>
</array></value>
</member>
</methodCall>
batch Response
<methodResponse>
<params><param><value>
<array>
<data>
<value><struct>
<value>003000000008NG6</value>
<value><struct>
<value>003000000008NG7</value>
</data>
</array></value></param>
</params>
</methodResponse>
SEARCH CALL XML-RPC EXAMPLES
search Response
<methodCall>
<methodName>sfdc.search</methodName>
<member>
</member>
<member>
<name>type</name>
</member>
<member>

sforce API
<name>scope</name>
<value><string>name</string></value>
</member>
<member>
<name>searchValue</name>
<value><string>Smith</string></value>
</member>
</methodCall>
search Request
<methodResponse>
<params><param>
<value>
<array>
<data>
<value>003000000000wFF</value>
<value>003000000008sRt</value>
<value>003000000008u7p</value>
<value>003000000000tN2</value>
<value>003000000007rpt</value>
<value>003000000008u7L</value>
<value>003000000008pjc</value>
<value>003000000008u7a</value>
<value>003000000006iYi</value>
<value>003000000001Ujd</value>
<value>003000000008u7e</value>
<value>003000000008qBu</value>
<value>003000000008u7Z</value>
</data>
</array></value></param>
</params>
</methodResponse>
SET_PASSWORD CALL XML-RPC EXAMPLES
set_password Request
<methodCall>
<methodName>sfdc.set_password</methodName>
<member>
</member>
<member>
<value><string>Q0DEqyenM0pEfH17f2AgFmNkZWZuKgECJF=</string></value>
</member>
<member>
<name>userID</name>

sforce API
<value><string>006a0000000EUaa</string></value>
</member>
<member>
<value><string>my_password</string></value>
</member>
</methodCall>
set_password Response
<methodResponse>
<params><param>
<value>my_password</value></param>
</params>
</methodResponse>
RESET_PASSWORD CALL XML-RPC EXAMPLES
reset_password Request
<methodCall>
<methodName>sfdc.reset_password</methodName>
<member>
</member>
<member>
<value><string>Q0DEqyenM0pEfH17f2AgFmNkZWZuKgECJF=</string></value>
</member>
<member>
<name>userID</name>
<value><string>006a0000000EUaa</string></value>
</member>
</methodCall>
reset_password Response
<methodResponse>
<params><param>
<value>KG6Cm0</value></param>
</params>
</methodResponse>

sforce API
GET_SERVER_TIMESTAMP CALL XML-RPC EXAMPLES
get_server_timestamp Request
<?xml version="1.0"?>
<methodCall>
<methodName>sfdc.get_server_timestamp</methodName>
<member>
</member>
</methodCall>
get_server_timestamp Response
<params><param>
<value><dateTime.iso8601>20030609T18:38:24</dateTime.iso8601></value></param>
</params>
</methodResponse>

sforce API Appendix E: SOAP Examples
APPENDIX E: SOAP Examples
Example SOAP requests and responses are included for each call.
The SOAP examples are indented for readability. The sforce API is not sensitive to indenting. The examples
could be passed “as is” to the API, or they could be passed as one long line of text without any formatting.
Responses from the sforce API are not normally formatted, without newlines (unless the data contains
newlines). You can obtain indented responses for readability and debugging purposes by specifying the HTTP
header: PrettyPrint: Yes. You should not use the PrettyPrint header for actual production use, though (see
Use of Headers on page 29 for more information).
LOGIN CALL SOAP EXAMPLES
login Request
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tns="salesforce" xmlns:types="salesforce/encodedTypes"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<soap-env:Header>
<headerStruct>
<version type="string">2.0</version>
</headerStruct>
</soap-env:Header>
<soap-env:Body>
<tns:login xmlns:tns="sfconnector:SalesforceConnector" type="methodCall">
<username type="string">USERNAME</username>
<password type="string">PASSWORD</password>
</tns:login>
</soap-env:Body>
</soap-env:Envelope>
login Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" >
<soap:Header/>
<soap:Body>
<return>
<valueMap type="map">
<server_url type="string">http://www.salesforce.com/servlet/servlet.SoapApi</
server_url>
<session_id
type="string">V1zaeZWGJW5vVVFSU1RVVldYUBgzNBJub3FxTABweWpXeHl6e3x9fn_AgYKDhIWGh4iJio
uMjY6PkJGSk5SVlg==</session_id>
</valueMap>

</return>
</soap:Body>
</soap:Envelope>
DESCRIBE CALL SOAP EXAMPLES
describe Request
<?xml version="1.0" encoding="utf-8"?>
xmlns:tns="salesforce"
xmlns:types="salesforce/encodedTypes"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<tns:headerStruct id="id1">
<session_id xsi:type="xsd:string">DguSIHKFbhUZJygsKissLUR2MxA=</session_id>
<version xsi:type="xsd:string">2.0</version>
</tns:headerStruct>
</soap:Header>
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:describe xmlns:q1="sfconnector:SalesforceConnector">
<type xsi:type="xsd:string">account</type>
</q1:describe>
</soap:Body>
</soap:Envelope>
describe Response
<soap:Header/>
<soap:Body>
<return>
<valueArray type="array">
<value type="map"> 
<access type="array">
<value type="string">select</value>
<value type="string">filter</value>
</access>
<type type="string">string</type>
<field type="string">id</field>
<display type="map">
<type type="string">id</type>
</display>
</value>
<label type="string">Owner ID</label>

<field type="string">ownerID</field>
<type type="string">reference</type>
</display>
<referenceTo type="string">user</referenceTo>
<nullable type="boolean">false</nullable>
</value>
<label type="string">Account Name</label>
<length type="int">80</length>
<field type="string">name</field>
<nullable type="boolean">false</nullable>
</value>
<label type="string">Parent Account ID</label>
<field type="string">parentID</field>
</display>
<referenceTo type="string">account</referenceTo>
</value>
<value type="string">insert</value>
<value type="string">update</value>
</access>
<label type="string">Account Description</label>
<length type="int">32000</length>
<field type="string">description</field>
<type type="string">textarea</type>
</display>
</value>
</access>
<label type="string">Created Date</label>
<type type="string">dateTime</type>
<field type="string">createdDate</field>
<type type="string">datetime</type>
</display>
</value>
</access>
<label type="string">Created By ID</label>

<field type="string">createdByID</field>
</display>
</value>
</access>
<label type="string">Last Modified Date</label>
<type type="string">dateTime</type>
<field type="string">lastModifiedDate</field>
<type type="string">datetime</type>
</display>
</value>
</access>
<label type="string">Last Modified By ID</label>
<field type="string">lastModifiedByID</field>
</display>
</value>
</valueArray>
</return>
</soap:Body>
</soap:Envelope>
INSERT CALL SOAP EXAMPLES
insert Request
<soap:Header>
<session_id
xsi:type="xsd:string">ExCXJ5VWYxoULC0rLxAREhMUFRYRTGIeISwisy8Ns3jRKBU=</session_id>
</tns:headerStruct>

</soap:Header>
<q1:insert xmlns:q1="sfconnector:SalesforceConnector">
<record href="#id1" />
</q1:insert>
<soapenc:Array id="id1" soapenc:arrayType="tns:mapEntry[1]">
<Item href="#id2" />
</soapenc:Array>
<tns:mapEntry id="id2" xsi:type="tns:mapEntry">
<key xsi:type="xsd:string">name</key>
<value xsi:type="xsd:string">test account 234</value>
</tns:mapEntry>
</soap:Body>
</soap:Envelope>
insert Response
<soap:Header/>
<soap:Body>
<return>
<id type="string">001z00000008OVn</id>
</valueMap>
</return>
</soap:Body>
</soap:Envelope>
UPDATE CALL SOAP EXAMPLES
update Request
<soap:Header>
<session_id
xsi:type="xsd:string">ys9O.ElrqtHd4_Tg5ufo6err7O3ou6vV6OPreObaarnS98w=</session_id>
</tns:headerStruct>
</soap:Header>
<q1:update xmlns:q1="sfconnector:SalesforceConnector">

<record href="#id1" />
</q1:update>
</soapenc:Array>
<value xsi:type="xsd:string">blah2</value>
</tns:mapEntry>
<key xsi:type="xsd:string">id</key>
<value xsi:type="xsd:string">001z00000008OVy</value>
</tns:mapEntry>
</soap:Body>
</soap:Envelope>
update Response
<soap:Header/>
<soap:Body>
<return>
<id type="string">001z00000008OVy</id>
</valueMap>
</return>
</soap:Body>
</soap:Envelope>
DELETE CALL SOAP EXAMPLES
delete Request
<soap:Header>
<session_id
xsi:type="xsd:string">DguSIHKFbhUZJygsKissLS4vEBEUR28RLCcntCoWrgQEMxA=</session_id>
</tns:headerStruct>
</soap:Header>

<q1:delete xmlns:q1="sfconnector:SalesforceConnector">
<id xsi:type="xsd:string">0010000000078aj</id>
</q1:delete>
</soap:Body>
</soap:Envelope>
delete Response
<soap:Header/>
<soap:Body>
<return>
</return>
</soap:Body>
</soap:Envelope>
QUERY CALL SOAP EXAMPLES
“filter” query Request (specifying a single criterion for a contact)

<soap:Header>
<session_id
xsi:type="xsd:string">josSoPxM7pWZp6isqqusra6vkJGUx__RrKenNKqWLprds5A=</session_id>
</tns:headerStruct>
</soap:Header>
<q1:query xmlns:q1="sfconnector:SalesforceConnector">
<type xsi:type="xsd:string">contact</type>
<maxRows xsi:type="xsd:int">20</maxRows>
<select href="#id1" />
<filter href="#id2" />
</q1:query>
<soapenc:Array id="id1" soapenc:arrayType="xsd:string[4]">
<Item>lastName</Item>
<Item>firstName</Item>
<Item>id</Item>
<Item>email</Item>
</soapenc:Array>
<soapenc:Array id="id2" soapenc:arrayType="xsd:anyType[1]">


</soapenc:Array>
</soapenc:Array>
<key xsi:type="xsd:string">field</key>
<value xsi:type="xsd:string">createdDate</value>
</tns:mapEntry>
<key xsi:type="xsd:string">value</key>
<value xsi:type="xsd:dateTime">2003-04-01T00:00:00.0000000-08:00</value>
</tns:mapEntry>
<key xsi:type="xsd:string">operator</key>
<value xsi:type="xsd:string">greater than</value>
</tns:mapEntry>
</soap:Body>
</soap:Envelope>
“filter” query Response

<soap:Header />
<soap:Body>
<return>
<value type="array">
<email type="string">[email protected]</email>
<lastName type="string">Testuser</lastName>
<firstName type="string">Joe</firstName>
<id type="string">00330000000cT2t</id>
</valueMap>
<firstName type="string">Mary</firstName>
<id type="string">00330000000clu1</id>
</valueMap>
<firstName type="string">Jim</firstName>
<id type="string">00330000000d6WM</id>
</valueMap>
</value>
</return>
</soap:Body>
</soap:Envelope>

“idList” query Request

<soap:Header>
<session_id
xsi:type="xsd:string">josSoPxM7pWZp6isqqusra6vkJGUx__RrKenNKqWLprds5A=</session_id>
</tns:headerStruct>
</soap:Header>
<q1:query xmlns:q1="sfconnector:SalesforceConnector">
<select href="#id1" />
<idList href="#id2" />
</q1:query>
<Item>ownerID</Item>
<Item>name</Item>
</soapenc:Array>
<Item>0010000000072By</Item>
<Item>001z00000008OVk</Item>
</soapenc:Array>
</soap:Body>
</soap:Envelope>
“idList” query Response

<soap:Header/>
<soap:Body>
<return>
<value type="array">
<name type="string">$A Test</name>
<ownerID type="string">005000000006dK4</ownerID>
</valueMap>
<name type="string">$A Test 2</name>
<ownerID type="string">005000000006dK4</ownerID>
</valueMap>
</value>

sforce API
</return>
</soap:Body>
</soap:Envelope>
BATCH CALL SOAP EXAMPLES
batch Request
<soap:Header>
<tns:headerStruct id="h_id1">
<session_id
xsi:type="xsd:string">GR6YgadHZRARFxMUFRYXGBkaGxxpSCUwKNkzCsc3NSQZOjs8PT4.QEFCQ0RFRk
dISUpLTVZXWA==</session_id>
</tns:headerStruct>
</soap:Header>
<q1:batch xmlns:q1="sfconnector:SalesforceConnector">
<operation xsi:type="xsd:string">insert</operation>
<arguments href="#id1" />
</q1:batch>
</soapenc:Array>
</soapenc:Array>
</soapenc:Array>
</soapenc:Array>
<value xsi:type="xsd:string">newaccount 1</value>
</tns:mapEntry>
</tns:mapEntry>

sforce API

</tns:mapEntry>
</soap:Body>
</soap:Envelope>
batch Response
<soap:Header />
<soap:Body>
<sfdc:batchResponse xmlns:sfdc="sfconnector:SalesforceConnector">
<return>
<value xsi:type="tns:array">
<valueMap xsi:type="tns:map">
<id xsi:type="xsd:string">001z00000008VVr</id>
</valueMap>
<id xsi:type="xsd:string">001z00000008VVs</id>
</valueMap>
<id xsi:type="xsd:string">001z00000008VVt</id>
</valueMap>
</value>
</return>
</sfdc:batchResponse>
</soap:Body>
</soap:Envelope>
SEARCH CALL SOAP EXAMPLES
search Request
<soap:Header>
<session_id
</tns:headerStruct>
</soap:Header>

sforce API
<q1:search xmlns:q1="sfconnector:SalesforceConnector">
<scope xsi:type="xsd:string">all</scope>
<searchValue xsi:type="xsd:string">$A Test</searchValue>
</q1:search>
</soap:Body>
</soap:Envelope>
search Response
<soap:Header/>
<soap:Body>
<return>
<valueArray type="array">
<value type="string">0010000000072By</value>
<value type="string">001z00000008OVk</value>
</valueArray>
</return>
</soap:Body>
</soap:Envelope>
SET_PASSWORD CALL SOAP EXAMPLES
set_password Request
<soap:Header>
<session_id
</tns:headerStruct>
</soap:Header>
<q1:set_password xmlns:q1="sfconnector:SalesforceConnector">
<userID xsi:type="xsd:string">006a0000000EUaa</userID>
<password xsi:type="xsd:string">my_password</password>
</q1:set_password>
</soap:Body>
</soap:Envelope>

sforce API
set_password Response
<soap:Envelope xmlns:soap="http:schemas.xmlsoap.orgsoapenvelope"
xmlns:soapenc="http:schemas.xmlsoap.orgsoapencoding"
xmlns:tns="salesforce" xmlns:types="salesforceencodedTypes"
xmlns:xsi="http:www.w3.org2001XMLSchema-instance"
xmlns:xsd="http:www.w3.org2001XMLSchema" >
</soap:Header>
<soap:Body>
<return>
<value type="string">my_password</value>
</return>
</soap:Body>
</soap:Envelope>
RESET_PASSWORD CALL SOAP EXAMPLES
reset_password Request
<soap:Header>
<session_id
</tns:headerStruct>
</soap:Header>
<q1:reset_password xmlns:q1="sfconnector:SalesforceConnector">
<userID xsi:type="xsd:string">006a0000000EUaa</userID>
</q1:reset_password>
</soap:Body>
</soap:Envelope>
reset_password Response
xmlns:tns="salesforce" xmlns:types="salesforceencodedTypes"
</soap:Header>
<soap:Body>
<return>
<value type="string">ePap1B</value>
</return>
</soap:Body>
</soap:Envelope>

sforce API
GET_SERVER_TIMESTAMP CALL SOAP EXAMPLES
get_server_timestamp Request
<soap:Header>
<session_id
</tns:headerStruct>
</soap:Header>
<q1:get_server_timestamp xmlns:q1="sfconnector:SalesforceConnector"/>
</soap:Body>
</soap:Envelope>
get_server_timestamp Response
xmlns:types="salesforceencodedTypes"
<soap:Header>
<soap:Body>
<return>
<value type="dateTime">2003-06-09T18:38:14-0700</value>
</return>
</soap:Body>
</soap:Envelope>

Sforce API Reference Manual

Uploaded by

Copyright:

Available Formats

Sforce API Reference Manual

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Sforce API Reference Manual

Uploaded by

Copyright:

Available Formats

sforce Web Services

Chapter 2: sforce API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 3: Protocol Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 4: Multiple Instance Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 5: Field-Specific Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page i

Long Text Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Chapter 6: Entity-Specific Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 7: Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Appendix A: Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Appendix B: Entity Relationship Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page ii

Sharing and Team Selling Entities . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Appendix C: Fault Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Appendix D: XML-RPC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Appendix E: SOAP Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page iii

Table 1: List of sforce API Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page iv

Table 42: CaseSolution Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page v

List of sforce API Revisions

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page vi

List of sforce API Revisions

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page vii

List of sforce API Revisions

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page viii

List of sforce API Revisions

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page ix

Table 1: Supported Entities

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page 1

Entity-Specific Issues on page 39

Table 2: Supported Operations

login Start a session

logout Finish a session

insert Create a new record with the specified information

update Modify an existing record

delete Delete an existing record

batch Perform multiple insert, update, or delete operations in one call

search Search for entities based on specified keywords

set_password Set a user’s password to a specified value

reset_password Reset a user’s password to a server-generated value

get_server_timestamp Obtain the exact time from the API server

GENERAL FORM OF THE SFORCE API

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page 2

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page 3

SOAP Data Types

Table 4: SOAP Data Types

array An array of any type

ArrayOfString An array of type string

mapEntry A name-value pair containing these elements:

map An array of mapEntry elements

SOAP Response Types

Table 5: SOAP Response Types

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page 4

REQUIREMENTS FOR ALL CALLS

Table 6: Standard Arguments for All sforce API Calls

Copyright•2002-2003 SalesForce.com, Inc. All rights reserved. Page 5

Table 8: login Request Members