Integration
Web Services API Cheat Sheet
Overview
Use the Force.com Web Services API to create, retrieve, update, or delete records in Force.com from any external system that supports SOAP-based Web services, such as Java, .NET, or PHP client applications. With more than 20 different calls, the API also allows you to maintain passwords, perform searches, retrieve metadata information about objects and more.
Getting Started
To generate the WSDL representing your environment, go to Setup | Developer | API. The Enterprise WSDL is a strongly typed representation of your data, while the Partner WSDL is a loosely typed representation, ideal for writing generic clients that work across different organizations.
Core Calls
These are the fundamental calls needed for logging in, querying, creating and deleting data:
| login() | Logs in and starts a client session. |
| logout() | Ends the session of the logged-in user. |
| invalidateSessions() | Ends one or more sessions. |
| create() | Adds one or more new individual records. |
| delete() | Deletes one or more individual records. |
| update() | Updates one or more existing records. |
| upsert() | Creates new records and updates existing records; matches on a custom field to determine the presence of existing records. |
| undelete() | Undeletes records from the Recycle Bin. |
| emptyRecycleBin() | Deletes records from the Recycle Bin immediately. |
| getDeleted() | Retrieves the IDs of individual deleted records for a specified timespan. |
| getUpdated() | Retrieves the IDs of individual updated records for a specified timespan. |
| convertLead() | Converts a Lead into an Account, Contact, or (optionally) an Opportunity. |
| merge() | Merges records of the same object type. |
| process() | Submits an array of approval process instances for approval, or processes an array of approval process instances to be approved, rejected, or removed. |
| query() | Executes a query against the specified object and returns data that matches the specified criteria. |
| queryAll() | Same as query(), but includes deleted and archived items. |
| queryMore() | Retrieves the next batch of records from a query. |
| retrieve() | Retrieves one or more records based on the specified record IDs. |
| search() | Executes a text search in your organization’s data. |
Describe Calls
These calls let you dynamically retrieve information about objects and other aspects of an organization:
| describeGlobal() | Retrieves a list of available objects for your organization’s data. |
| describeLayout() | Retrieves metadata about page layouts for the specified object type. |
| describeSObject() | Superseded. Use describeSObjects() instead. |
| describeSObjects() | Retrieves metadata (field list and object properties) for the specified object types. |
| describeSoftphoneLayout() | Describes the SoftPhone layout(s) created for an organization. |
| describeTabs() | Describes the apps and tabs that have been configured for the user. |
Utility Calls
These calls let you retrieve user information, send emails and reset passwords:
| getServerTimestamp() | Retrieves the current system timestamp from the API. |
| getUserInfo() | Retrieves personal information for the user associated with the current session. |
| resetPassword() | Changes a user’s password to a system-generated value. |
| sendEmail() | Immediately sends an email message. |
| setPassword() | Sets the specified user’s password to the specified value. |
Primitive Data Types
The API uses the following primitive data types:
| base64 | Base 64-encoded binary data. |
| boolean | Boolean fields have one of these values: true (or 1), or false (or 0). |
| byte | A set of bits. |
| date | Date data. Unlike dateTime fields, date fields contain no time value. |
| dateTime | Date/time values (timestamps) |
| double | Double values. |
| int | Fields of this type contain numbers with no fractional portion. |
| string | Character strings. |
| time | Time values. |
Field Types
In addition to the primitive data types, the API defines the following data types for object fields:
| anyType | Polymorphic data type that represents a particular type depending on the kind of field involved. |
| calculated | Fields that are defined by a formula. |
| combobox | A combobox, which includes a set of enumerated values and allows the user to specify a value not in the list. |
| currency | Currency values. |
| Email addresses. | |
| encryptedstring | Encrypted text fields contain any combination of letters, numbers, or symbols that are stored in encrypted form. |
| ID | Primary key field for the object. |
| masterrecord | When records are merged, the ID of the record that is saved (the other records are deleted). |
| multipicklist | Multi-select picklists, which include a set of enumerated values from which multiple values can be selected. |
| percent | Percentage values. |
| phone | Phone numbers. Values can include alphabetic characters. |
| picklist | Picklists, which include a set of enumerated values from which one value can be selected. |
| reference | Cross-references to a different object. Analogous to a foreign key field in SQL. |
| textarea | String that is displayed as a multiline text field. |
| url | URL values. |
API Fault Element
The following table lists the API fault elements that the API returns if an error occurs when processing a service request.
| ApiQueryFault | The row and column numbers where the problem occurred. |
| LoginFault | An error occurred during the login() call. |
| InvalidSObjectFault | An invalid sObject in a describeSObject(), describeSObjects(), create(), update(), retrieve(), or query() call. |
| InvalidFieldFault | An invalid field in a retrieve() or query() call. |
| MalformedQueryFault | A problem in the queryString passed in a query() call. |
| InvalidQueryLocatorFault | A problem in the queryLocator passed in a queryMore() call. |
| MalformedSearchFault | A problem in the search passed in a search() call. |
| InvalidIdFault | A specified ID was invalid in a setPassword() or resetPassword() call. |
| UnexpectedErrorFault | An unexpected error occurred. The error is not associated with any other API fault. |
