Search | Force.com REST API Developer's Guide

For SOSL searches using the GET method and a SOSL search string:

/vXX.X/search/?q=SOSL search string

For searches using the GET method and that only use parameter values without any SOSL search strings

/vXX.X/search/?qs=search string

For searches using the POST method and query parameters appended in the JSON file:

/vXX.X/search

This is a beta feature available in API version 35.0 and later, when enabled. This release contains a beta version of the qs parameter that is production quality. You can provide feedback and suggestions for this parameter on the IdeaExchange. For information on enabling this feature for your organization, contact Salesforce.

JSON, XML

GET, POST

Authorization: Bearer token

Include one (but not both) of these required parameters.

Required Parameter (use either)	Description
q	A SOSL statement that is properly URL-encoded.
qs	A search string that is properly URL-encoded. SOSL clauses aren’t supported. Note Available in version 35.0 and later when enabled. Contact Salesforce to enable.

These additional optional parameters are supported when using the qs parameter.

Global Parameter	Description
sObject (with GET method)	Optional. Object to return in the response. Must be a valid object type. You can use multiple sObject parameter values, such as,`sObject=Account&sObject=Contact`. If unspecified, then the search results contain the IDs of all objects.
fields	Optional. Comma-separated list of one or more fields to return in the response for each sObject specified, such as fields=id,name. At least one sObject must be specified. When additional sObject fields are specified using `sOject.fields=field names`, such as `Account.fields=id,name`, this parameter is ignored for that object. If unspecified, then the search results contain the IDs of records matching all fields for the specified object.
in	Optional. Scope of fields to search. If you specify one or more fields, the fields are returned for all found objects. One of the following values: `ALL` `NAME` `EMAIL` `PHONE` `SIDEBAR` This clause doesn't apply to articles, documents, feed comments, feed items, files, products, and solutions. If any of these objects are specified, the search is not limited to specific fields; all fields are searched. Note
division	Optional. Single value. Filter search results based on the division field. For example, `division=global`. Specify a division by its name rather than ID. All searches within a specific division also include the `global` division.
netWorkIds	Optional. Filter search results by a comma-separated list of one or more netWorkIds. A network ID represents the community ID.
overallLimit	Optional. Single value. The maximum number of results to return across all sObject parameters specified. The maximum overallLimit is 2000.
defaultLimit	Optional. Single value. The maximum number of results to return for each sObject specified. When an sObject limit is specified using `sOject.limit=value`, such as `Account.limit=10`, this parameter is ignored for that object. At least one sObject must be specified. The maximum defaultLimit is 2000.
offset	Optional. Single value. The starting row offset into the result set returned. Only one sObject must be specified when using this parameter. The maximum offset is 2000.
dataCategory	Optional. Single value. If an organization uses Salesforce Knowledge articles or answers, filters all search results based on one or more data categories, such as`dataCategory=GlobalCategory__c below NorthAmerica__c` If you require multiple dataCategory filters, use the POST method, which supports multiple data category specifiers. For the POST method, use the following: dataCategories: Optional. If an organization uses Salesforce Knowledge articles or answers, filters all search results based on one or more data categories. Use the following parameters: `groupName`: Single value. The name of the data category group to filter by. `operator`: Single value. Use `AT`, `ABOVE`, `BELOW`, `ABOVE_OR_BELOW` `categories`: A list array. The name of the categories to filter by.
snippet	Optional. The target maximum number of characters to return in Salesforce Knowledge article search results. If an organization uses Salesforce Knowledge articles, displays contextual snippets and highlights the search term for each article in the search results. By default, each snippet displays up to about 300 characters, which is usually about three lines of text in a standard browser window. Specify an alternate target length, which can be from 100 and 500 characters. Snippet results are used to differentiate matches to the search term in article search results. Snippet highlights are generated from email, text, and text area (long and rich) fields. Snippets aren’t displayed for partially matching searches or if the user doesn’t have access to the field that contains the snippet. Snippets are displayed for the first 20 articles returned. If more than 20 articles are returned, snippets aren’t generated. Snippets are displayed for Salesforce Knowledge articles only. At least one of the following sObject values must be specified. To search a specific article type, use the article type name with the suffix __kav. To search all article types, use KnowledgeArticleVersion.
updateTracking	Optional. Specify a value of `true` to track keywords that are used in Salesforce Knowledge article searches. If unspecified, the default value of `false` is applied.
updateViewStat	Optional. Specify a value of `true` to determine the number of views for each Salesforce Knowledge article included in the response. If unspecified, the default value of `false` is applied.

The following optional parameters can be used with the sObject parameter to further refine search results. The format is sObject.parameter, such as Account.fields. An sObject must be specified to use these parameters. For example, sObject=Account.

sObject Parameter	Description
fields	Required for Knowledge object. Optional for other objects. Comma-separated list of one or more fields to return in the response. For example, `Account.fields=id,name`.
where	Required for Knowledge object. Optional for other objects. Filter search results for this object by specific field values. Syntax: `sobject.where = conditionExpression`. Here the `conditionExpression` of the WHERE clause uses the following syntax: `fieldExpression [logicalOperator fieldExpression2 ... ]` You can add multiple field expressions to a condition expression by using logical and comparison operators. For example, `Account.where=(NumberOfEmployees < 100) and (BillingState IN (”California’, ‘New York’))`.
limit	Optional. Displays a subset of results for the object. For example, `Account.limit=10`. If specified, the global defaultLimit parameter is ignored for this object.
orderBy	Optional. Specify the order of search results to be returned using the fieldname and one or more of the following values: `ASC` or `DESC`: Orders the results in ascending or descending order. Results are listed in ascending order by default. `first \| last`: Places null records at the beginning or end of the results. By default, null values are sorted last in ascending order and first in descending order. You can include more than one orderBy value. For example, `Account.orderBy=fieldname [ASC \| DESC][first\|last]`

For the GET method, use the following syntax with the qs parameter.

1.../vXX.X/search/?qs=Acme&sObject=object name&fields=field types&in=SearchGroup&division=division field&netWorkIds=network Ids&overallLimit=integer < 2,000&defaultLimit=integer < 2,000&offset=integer < 2,000&dataCategory=DataCategorySpec&snippet=integer&updateViewStat=boolean true or false&updateTracking=boolean true or false

1...&sObjectName.fields=comma-separated list of field types&sObjectName.where=conditionExpression&sObjectName.limit=value&sObjectName.orderBy=field name[ASC | DESC][first | last]

For the POST method, use the following syntax with the qs parameter.

1{
2"qs”:”Acme”,
3"fields” : ["id”, "firstName”, "lastName”],
4"sobjects”:[{”fields”:[”id”, "name”],
5             "name”: "Account”,
6             "where”: "DISTANCE(My_Location_Field__c,GEOLOCATION(37,122),'mi') < 100”,
7             "orderBy”: {"fields”: "name”
8                         "order”: "ASC”,
9                         "whereAreNulls”: "last”
10                        },
11             "limit”:20
12            },
13  
14            {"name”: "Contact”}            
15            ],
16"in":"ALL",
17"overallLimit":100,
18"defaultLimit”:10
19"updateViewStat": true,
20"updateTracking": true,
21}

In the example, more parameters were used in the POST method not listed in the parameter tables.

sObjects: Optional. A list array for the objects to return in the response. When listing parameters within sObjects, the syntax is different than the GET method.
name: Required if using sObjects. Name of the object to return in the response. This parameter is contained within the sObjects list array.
fields: Required if using the orderBy parameter. Name of the field to apply the ordering in the response. This parameter is contained within the orderBy parameter.
order: Optional. Orders the results in ascending or descending order. This parameter is contained within the orderBy parameter.
whereAreNulls: Optional. Places the null records at the beginning or end of the results. This parameter is contained within the orderBy parameter.

Note

See Search for a String.