CustomerSearch Resource (Data API 17.2)

Summary

Http Method Resource Description
POST /Customer_search

Searches for customers.

The search can be configured using a simple query language, which provides most common filter and operator functionality.

The identifier for an attribute to use in a query condition is always the ID of the attribute as defined in the type definition. For custom defined attributes the prefix "c_" is required in the search term (e.g. c_color = {1}), while for system attributes no prefix is used (e.g. name = {4}).

Supported attribute value types with sample expression values:

  • String 'String', 'Str*', 'Strin?'
  • Integer 1, 3E4
  • Number 1.0, 3.99E5
  • Date yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)
  • DateTime yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00
  • Boolean true, false
  • Email '[email protected]', '*@salesforce.com'
  • Set of String 'String', 'Str*', 'Strin?'
  • Set of Integer 1, 3E4
  • Set of Number 1.0, 3.99E5
  • Enum of String 'String', 'Str*', 'Strin?'
  • Enum of Integer 1, 3E4

The following types of attributes are not queryable:

  • Image
  • HTML
  • Text
  • Quantity
  • Password

Note that some system attributes are not queryable by default regardless of the actual value type code.

The following operators are supported in a condition:

  • = Equals - All types; supports NULL value (thumbnail = NULL)
  • != Not equals - All types; supports NULL value (thumbnail != NULL)
  • < Less than - Integer, Number and Date types only
  • > Greater than - Integer, Number and Date types only
  • <= Less or equals than - Integer, Number and Date types only
  • >= Greater or equals than - Integer, Number and Date types only
  • LIKE Like - String types and Email only; use if leading or trailing wildcards will be used to support substring search(custom.country LIKE 'US*')
  • ILIKE Caseindependent Like - String types and Email only, use to support case insensitive query ( c_country ILIKE 'usa'), does also support wildcards for substring matching

Conditions can be combined using logical expressions 'AND', 'OR' and 'NOT' and nested using parenthesis e.g. gender = {1} AND (age >= {2} OR (NOT profession LIKE {3})).

The query language provides a placeholder syntax to pass objects as additional search parameters. Each passed object is related to a placeholder in the query string. The placeholder must be an Integer that is surrounded by braces. The first Integer value must be '0', the second '1' and so on, e.g. "query":"age = {0} or creationDate >= {1}","query_args":[18, "2007-05-31T00:00+Z"]

The sort_string parameter is optional and might contain a comma separated list of attribute names to sort by. Each sort attribute name might be followed by an optional sort direction specifier ('asc' | 'desc'). Default sorting directions is ascending, if no direction was specified. Example: age desc, name Please note that specifying a localized custom attribute as the sorting attribute is currently not supported.

Sometimes it is desired to get all instances of specified type with a special sorting condition. This can be easily done by providing the 'type' of the custom object and the 'sort_string' in combination with an empty "query", e.g. "sort_string":"c_myAttr asc")

If the customer search API is configured to use the new Search Service (Beta), the following differences apply:

  • wildcards will be filtered from the query (*, %, +) and replaces by spaces
  • LIKE and ILIKE queries will be executed as fulltext queries (working on whole words), not as substring searches
  • LIKE queries will always be case insensitive
  • using logical operators might change the execution of LIKE/ILIKE clauses to exact string comparison, depending on how they are combined
  • using logical operators might result in degraded performance, depending on how they are combined
  • the search will return only the first 1000 hits from the search result

Search Customers

Searches for customers.

The search can be configured using a simple query language, which provides most common filter and operator functionality.

The identifier for an attribute to use in a query condition is always the ID of the attribute as defined in the type definition. For custom defined attributes the prefix "c_" is required in the search term (e.g. c_color = {1}), while for system attributes no prefix is used (e.g. name = {4}).

Supported attribute value types with sample expression values:

  • String 'String', 'Str*', 'Strin?'
  • Integer 1, 3E4
  • Number 1.0, 3.99E5
  • Date yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)
  • DateTime yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00
  • Boolean true, false
  • Email '[email protected]', '*@salesforce.com'
  • Set of String 'String', 'Str*', 'Strin?'
  • Set of Integer 1, 3E4
  • Set of Number 1.0, 3.99E5
  • Enum of String 'String', 'Str*', 'Strin?'
  • Enum of Integer 1, 3E4

The following types of attributes are not queryable:

  • Image
  • HTML
  • Text
  • Quantity
  • Password

Note that some system attributes are not queryable by default regardless of the actual value type code.

The following operators are supported in a condition:

  • = Equals - All types; supports NULL value (thumbnail = NULL)
  • != Not equals - All types; supports NULL value (thumbnail != NULL)
  • < Less than - Integer, Number and Date types only
  • > Greater than - Integer, Number and Date types only
  • <= Less or equals than - Integer, Number and Date types only
  • >= Greater or equals than - Integer, Number and Date types only
  • LIKE Like - String types and Email only; use if leading or trailing wildcards will be used to support substring search(custom.country LIKE 'US*')
  • ILIKE Caseindependent Like - String types and Email only, use to support case insensitive query ( c_country ILIKE 'usa'), does also support wildcards for substring matching

Conditions can be combined using logical expressions 'AND', 'OR' and 'NOT' and nested using parenthesis e.g. gender = {1} AND (age >= {2} OR (NOT profession LIKE {3})).

The query language provides a placeholder syntax to pass objects as additional search parameters. Each passed object is related to a placeholder in the query string. The placeholder must be an Integer that is surrounded by braces. The first Integer value must be '0', the second '1' and so on, e.g. "query":"age = {0} or creationDate >= {1}","query_args":[18, "2007-05-31T00:00+Z"]

The sort_string parameter is optional and might contain a comma separated list of attribute names to sort by. Each sort attribute name might be followed by an optional sort direction specifier ('asc' | 'desc'). Default sorting directions is ascending, if no direction was specified. Example: age desc, name Please note that specifying a localized custom attribute as the sorting attribute is currently not supported.

Sometimes it is desired to get all instances of specified type with a special sorting condition. This can be easily done by providing the 'type' of the custom object and the 'sort_string' in combination with an empty "query", e.g. "sort_string":"c_myAttr asc")

If the customer search API is configured to use the new Search Service (Beta), the following differences apply:

  • wildcards will be filtered from the query (*, %, +) and replaces by spaces
  • LIKE and ILIKE queries will be executed as fulltext queries (working on whole words), not as substring searches
  • LIKE queries will always be case insensitive
  • using logical operators might change the execution of LIKE/ILIKE clauses to exact string comparison, depending on how they are combined
  • using logical operators might result in degraded performance, depending on how they are combined
  • the search will return only the first 1000 hits from the search result

Url

POST https://hostname:port/dw/data/v17_2/customer_search

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CustomerSearchRequest

Response Document

CustomerSearchResult

Sample

REQUEST:
POST /dw/data/v17_2/customer_search HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Accept: application/json

{
    "query" : "first_name like 'Hans*'",
    "sort_string" : "customer_no asc"
}

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8

{
  "_v" : "17.2",
  "_type": "customer_search_result",
  "count" : 2,
  "hits" : [ {
    "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
    "customer_no" : "0000645",
    "link" : "https://example.com/dw/data/v17.2/customers/0000645",
  },
  {
    "_resource_state" : "t9ccde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73b8h6",
    "customer_no" : "0000123",
    "link" : "https://example.com/dw/data/v17_2/customers/0000123",
  }  ],
  "query" : "first_name like 'Hans*'",
  "sort_string" : "customer_no asc",
  "start" : 0,
  "total" : 2
}

# search using query arguments and selector

REQUEST:
POST /dw/data/v17_2/customer_search HTTP/1.1
Host: example.com
Accept: application/json
{
    "query" : "first_name = {0} and last_name = {1}",
    "query_args" : [ "Hans", "Meier"],
    "select" : "(**)"
}

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8

{
  "_v" : "17.2",
  "count" : 1,
  "hits" : [ {
    "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
    "customer_no" : "0000123",
    "birthday" : "1978-05-06",
    "customer_no" : "0815",
    "email" : "[email protected]",
    "first_name" : "Hans",
    "gender" : 1,
    "last_name" : "Meier",
    "phone_business" : "222-444-555",
    "phone_home" : "553-654-345",
    "phone_mobile" : "4932-432-454",
    "preferred_locale" : "en-US",
    "salutation" : "Mr.",
    "link" : "https://example.com/dw/data/v17_2/customers/0000645",
  }],
    "query" : "first_name = {0} and last_name = {1}",
    "query_args" : [ "Hans", "Meier"],
    "select" : "(**)"
  "start" : 0,
  "total" : 1
}

Infocenter Retirement: On June 30, 2023, the Infocenter was retired, and documentation currently hosted on the Infocenter will be published to Salesforce Help, Commerce Cloud Developer Center, and Salesforce B2C Commerce Developer Documentation Resources. For more information, see the release note.

X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.