Use the search API to search for records that match your search criteria across all the business entities or within a specific business entity in English and Japanese. You can filter the search results based on severity levels and validation statuses. You can also filter search results based on fields that are blank or contain values. The API uses the search resource.
To search for records, submit a POST request with the following URI:
<baseApiUrl>/search/public/api/v1/search
The response is in the JSON format.
Request body
You can use the following parameters in the search request body:
Note: Use either the search or fields parameters, but not both.
Parameter
Type
Description
search
String
Search string.
To retrieve all the records, use an asterisk (*).
To perform a fuzzy search, enter a search word or phrase. When you search for records, you can use additional wildcard characters, such as *, ~, &&, and ||.
You can use search strings similar to the ones in the following examples:
- John Smith. Searches for records that contain John Smith as a field value.
- Jo*n. Searches for records that start with Jo and end with n, such as Johansson or Jordan.
- Hans && Williams. Searches for records that contain Hans and Williams in the same record. For example, the first name is Hans, and the last name is Williams.
To perform an exact search, enter the search string within double quotes.
For example, if you want to search for records that contain the field value US:10901, ensure that you specify the following search string:
"US:10901"
Note: When you use only white spaces as a search string without any other characters, the search doesn't return any results.
To search for records by specifying a date, ensure that you use the YYYY-MM-DD format.
For more information about these wildcard characters, see Using the search box to find records in the Customer 360 help.
fields
String
Searches records for specific fields. For example , searching "J*" for the first name field returns all names starting with "J".
entityType
String
Internal ID of the business entity you want to search.
filters
Array
Specifies a list of fields that you want to use to filter the search results.
filter > operator
String
The Boolean operator that joins multiple filters that you specify. Use AND or OR as the Boolean operator.
filters > filter > comparison operator
String
Condition that specifies how to filter search results.
Use one of the following comparison operators:
- EQUALS. Returns records that match the specified field value.
For example, you can filter the employees whose department is equal to product management.
- NOT_EQUALS. Returns records that don't match the specified value.
Note: When you use the NOT_EQUALS filter comparator in the request, the response doesn't return records based on fields that contain blank or null values.
To search for records with fields that contain blank or null values, use the IS_MISSING filter comparator in the request.
For example, you can filter employees whose country is not equal to India.
- IN. Returns records with field values that match any of the specified values.
For example, you can filter employees who belong to cities such as Chennai, Bangalore, and Hyderabad.
- BETWEEN. Returns records that contain field values within the specified range.
For example, you can filter people aged between 20 and 30.
- GREATER_THAN. Returns records with field values greater than the specified value.
For example, you can filter employees with more than 5 years experience.
- LESS_THAN. Returns records with field values less than the specified value.
For example, you can filter employees with less than 3 years experience.
- GREATER_THAN_EQUAL_TO. Returns records with field values greater than or equal to the specified value.
For example, you can filter students with a score greater than or equal to 80.
- LESS_THAN_EQUAL_TO. Returns records with field values less than or equal to the specified value.
For example, you can filter students with a score less than or equal to 35.
- STARTS_WITH. Returns records with field values that start with a specified value.
For example, you can filter records where the first name starts with John.
- CONTAINS. Returns records with field values that contain the exact words in the same sequence as specified in the filter condition.
For example, if you filter results by first names that contain the word James, the filter can return names such as James Earl, James Henry, and William James. However, the filter doesn't return Jameson. Similarly, if you filter results by first names that contain Anne Marie, the filter can return names, such as Anne Marie and Anne-Marie. However, the filter doesn't return Marie Anne because the order of words doesn't match.
- IS_MISSING. Returns records that don't contain values in specific fields.
For example, you can filter records that don't contain values in the middle name field.
- IS_NOT_MISSING. Returns records that contain values in specific fields.
For example, you can filter records that contain values for the country field.
Note: If you want to you use the IS_MISSING and IS_NOT_MISSING filter comparators, ensure that you run the Generate Search or Report Indexes or Match Keys job at least once to reindex records.
filters > filter > fieldName
String
Name of the field that you want to use as a filter.
To filter search results based on error types, use one of the following system fields:
- validationType
- validationState
filters > filter > fieldValue
String
Value that you want to use to filter the results.
Note: You can use a partial word or value with the STARTS_WITH or CONTAINS comparison operators.
filters > filter > fieldValueGroups
String
Filters search results based on certain criteria that define a group.
For example, you can filter search results based on their error type groups, such as error, warning, and info.
pageSize
Number
Number of search results to display on each page.
pageOffset
Number
Optional. Number of pages to skip. For example, pageOffset=2 means that the search must skip the first two pages of the search results. Default is 0.
recordsToReturn
Number
Number of search results to return.
recordOffset
Number
Number of records to skip. For example, recordOffset=200 indicates that the search must skip the first 200 search results. Default is 0.
maxRecords
Number
Maximum number of records to return.
Note: The search cannot return more than 10,000 records per page.
sort
Array
Specifies a list of fields based on which you want to sort the search results.
sort > fieldName
String
Name of the field by which you want to sort the search results.
sort > order
String
Order in which you want to sort the search results.
Use one of the following sort orders:
- ASCENDING
- DESCENDING
searchLocale
String
Optional. Code of the language that you want to use to search for records.
Use one of the following codes:
- en
- ja
Default is en.
Before you specify any value other than en, ensure that the language is configured as a searchable language in Business 360 Console.
Request response
The request response returns the search results.
The following table lists the response parameters:
Parameter
Type
Description
searchResult
Object
Contains the search results.
hits
Number
Number of search results.
records
Array
Contains all the search results that are filtered and sorted based on the criteria you specify.
Contains the vader parameter that lists the internal IDs of the failed rule associations for search results with validation errors.
pageSize
Number
Number of search results on a page.
pageOffset
Number
Number of pages to skip. For example, pageOffset=2 means that the search must skip the first two pages of the search results. Default is 0.
recordsToReturn
Number
Number of search results to return.
recordOffset
Number
Number of records to skip. For example, recordOffset=200 indicates that the search must skip the first 200 search results. Default is 0.
maxRecords
Number
Maximum number of records to return.
Note: The search cannot return more than 10,000 records per page.
The POST response includes the following meta parameters:
Parameter
Type
Description
score
Number
The current trust score of the record.
businessId
String
Unique identifier of the business entity record.
id
String
Internal ID of the record. Do not use.
businessEntity
String
Name of the business entity to which the record belongs.
createdBy
String
Name of the person who created the record.
creationDate
String
Date when the record was created.
updatedBy
String
Name of the user who last updated the record.
lastUpdateDate
String
Date when the master record was last updated.
type
String
Internal ID of the business entity to which the record belongs.
status
String
Indicates whether the record is active, inactive, or in pending status.
Note: This parameter is the same as the state parameter in the business entity record APIs. For more information about the state parameter, see Read Master Record by Business ID .
Sample requests
Request with the search parameter
You might use the following request to find all the records of the Person business entity associated with the name Arny and the state of California:
POST https://use4-mdm.dm-us.informaticacloud.com/search/public/api/v1/search Content-Type: application/json Accept: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX MODEL_VERSION: 1583398245259
To use the latest search configuration, ensure that you include the model version in the search request. If you don't include the model version, the search request might use the search configuration from the metadata cache of the previous REST API requests.
For more information about model version, see Request header.
Request with the fields parameter
You might use the following request to find all the records that start with "Jona" for the full name field:
Note: If you use filter comparators other than IS_MISSING or IS_NOT_MISSING, ensure that specify a field in the fields section.
Request to filter search results based on validation errors
The following table lists the parameters to use to filter search results based on error type, rule ID, and validation status:
Parameter
System Field
Search Parameter Value
Description
fieldName > fieldValueGroups
validationType
ERROR, WARNING, or INFO
Filters search results based on error types, such as ERROR, WARNING, or INFO.
fieldName > fieldValue
validationType
<Internal ID of rule associations>
Filters search results based on the internal IDs of failed rule associations. To view the internal rule ID, open the rule association.
fieldName > fieldValue
validationState
PASSED or FAILED
Filters search results based on the specified validation status.
You might use the following request to filter records based on the error type INFO, rule ID should_not_contain_number_1687874505794, and validation status FAILED:
You can use the IS_MISSING and IS_NOT_MISSING filter comparators to search for records with fields that are blank or contain values.
Consider the following guidelines when you use the IS_MISSING and IS_NOT_MISSING filter comparators:
•Don't specify a field value for the IS_MISSING and IS_NOT_MISSING filter comparators.
•If you use the IS_MISSING and IS_NOT_MISSING filter comparators for a field, don't use another comparator for the same field.
For example, you can't use both EQUALS and IS_MISSING filter comparators for the first name field.
You might use the following request to find all the records for the Person business entity that don't contain any value for the Designation field and matches the specified value for the First Name field:
You might use the following request to find all the records of the Person business entity that contain values for the Designation field and the First Name field equals to John:
Note: You can use additional _meta parameters, such as businessId, creationDate, and updatedBy, to filter records. For more information about _meta parameters, see _meta parameters table.
Sample responses
When you make a search request, the response retrieves records that match your search criteria.
Response with the search parameter
The following search response contains the Person business entity record associated with the name Arny:
The following search response contains the Person business entity record that doesn't contain a value for the Middle Name field, and the First Name field matches the specified search term: