Search API

Get search results data in JSON.

Prerequisites

Before making your first API call, ensure that you have completed the following prerequisites.

1. Set a user scope

SearchUnify users can have one of five user scopes, each affecting the API calls they can make. Follow the instructions in Change User Scope (API and SDK) to modify a user’s scope.

2. Create an app

Client ID and Client Secret are created at the time of app creation. These credentials authenticate your identity. Learn how to create an app and obtain these credentials in Get Client ID and Client Secret with an API App.

3. Obtain access and refresh tokens using the app

To use this API, you need access and refresh tokens. Follow the steps in Get Access and Refresh Token Using curl to generate them.

Using Access and Refresh Tokens

The token generation process provides two types of tokens:

  • Refresh Token – Valid for 14 days. Store it securely, as it is only used to generate new access tokens.

  • Access Token – Expires every four hours. This token is required for user authentication and must be included in the header of all API calls.

Format for Including the Access Token in API Calls:

Copy

bash

-H "authorization: Bearer {{access_token}}"

Base URL

The Base URL for all API calls is:

https://{{hostname}}/api/v2_search/

Where hostname is the URL of your SearchUnify instance.

Example Base URL

https://mycompany.searchunify.com/api/v2_search/

Endpoints

 

View search results on a platform of your choice.

Parameters

Parameter Optional / Required Description Data Type
uid Required It is your search client ID. You can find it in Search Clients > UID (column). string
searchString Required It is the search query. string
email Optional This parameter is used establish the searcher's identity and tailor search results based on that identity. An admin email might fetch results different from a moderator email. string
orderBy Optional It has two values, asc and desc. If orderby=desc, then the order in which the results are presented is reversed. The last result will be ranked first, the penultimate result second, and so on. The default value of orderBy is asc. string
sortby Optional It can have two values, _score or post_time. When sortby=_score, then the documents with the highest score are presented first. When sortby=post_time, then the lastest documents are on top. string
exactPhrase Optional It treats all the words in the search query as one contiguous string. exactPhrase=salesforce console becomes "salesforce console". string
withOneOrMore Optional When used, it inserts the Boolean operator OR between each pair of keywords. withOneOrMore=salesforce console becomes "salesforce OR console". string
withoutTheWords Optional This parameter inserts the Boolean operator NOT before each keyword. withoutTheWords=salesforce console becomes "NOT salesforce NOT console" string
from Optional It's an offset. If from="10", then the call will ignore the top 10 results and fetch results starting from the document ranked 11. string
resultsPerPage Optional If resultsPerPage=30, then each search will produce 30 results on each page. string
indexEnabled Optional The content sources tabs are hidden if indexEnabled is set to false. In the default state, indexEnabled=true. boolean
aggregations Optional aggregations is used to refine your search with facets. For example: type: ${facet name}, filter: [ ${facet filter name1}, ${facet filter name2} ]. A common pattern for nested facets is [{type: ${facet name},children: [ childname: ${facet child name1}, level: ${facet level} ]}] object
pagingAggregation Optional It is used if your goal is to display all your facets. {key: ${facet name},keyword: ${facet search keyword},offset: ${number of filters to shown}} object
pageNo Optional Returns search results from the specified page number. If pageNo==5, then the results from the fifth page will be returned.
sid Optional Attaches session ID(s) to the returned data.
language Optional Returns results in the specified language. language=zh returns Chinese results.
versionResults Optional Merge multiple versions of a doc into a result.
getAutoTunedResult Optional Returns auto tuned results. Works only if Auto Spell Corrector and Facet Interpretor are enabled in the instance.
getSimilarSearches Optional Returns results from the similar searches tab. Works only if Similar Searches is turned on in the instance.
mergeSources Optional Groups results by content sources. Works only if Customize Search Client View is turned on in the instance.

Salesforce-Specific Parameters

Parameter Optional / Required Description Data Type
UserId Optional Your user ID. string
UserType Optional Your user type. For example, Standard, Admin, and Developer. string
AccountId Optional Your Salesforce ID. string
ProfileID Optional Your profile ID in your org. string
ContactId Optional Your contact ID. string

Lithium-Specific Parameters

Parameter Optional / Required Description Data Type
boardsArr Required It limits search to the boards specified in boardsArr. string

Example Request

curl -X POST 'https://grazitti.searchunify.com/dev/api/v2_search/searchResults' 
-H 'Content-Type: application/json' -H "authorization: Bearer ACCESS_TOKEN" 
--data-binary $'
  {
  	\n"uid":"SEARCH_CLIENT_ID", 
    \n"searchString":"salesforce", 
    \n"sortby":"_post_time", 
    \n"resultsPerPage":"20" \n
  }'