Skip to main content
GET
https://api.pretectum.io
/
dataobjects
/
search
Search Data Objects
curl --request GET \
  --url https://api.pretectum.io/dataobjects/search \
  --header 'Authorization: <authorization>'
{
  "hits": [
    {
      "_dataObjectId": "<string>",
      "_businessAreaName": "<string>",
      "_schemaName": "<string>",
      "_dataSetName": "<string>",
      "_businessAreaId": "<string>",
      "_schemaId": "<string>",
      "_dataSetId": "<string>",
      "[field_name]": {}
    }
  ],
  "total": 123
}
The Search Data Objects endpoint allows you to search through your master data across business areas, schemas, and datasets. You can perform full-text searches and filter results based on your organizational structure.

Prerequisites

  • Valid access token (see Get Access Token)
  • Permission to search data objects in your tenant

Authentication

Include your access token in the Authorization header.
Pass the token directly without the “Bearer” prefix.
Authorization: your_access_token

Request

Query Parameters

query
string
required
The search query string. This supports full-text search across all indexed fields in your data objects. You can use standard search operators like AND, OR, and wildcards (*).Examples:
  • John - Search for “John” in any field
  • John AND Smith - Search for records containing both “John” and “Smith”
  • email:*@example.com - Search for email addresses ending with @example.com
businessArea
string
Filter results to a specific business area by name. If not provided or set to “all”, the search will include all business areas you have access to.Use the List Business Areas endpoint to get the available business area names for your application.Example: Customer, Product, Supplier
schema
string
Filter results to a specific schema by name. A schema defines the structure and fields of your data objects within a business area.Use the List Schemas endpoint to get the available schema names for a business area.Example: Individual Customer, Business Customer
dataSet
string
Filter results to a specific dataset by name. Datasets are collections of data objects that share the same schema.Use the List Datasets endpoint to get the available dataset names for a schema.Example: US Customers, European Customers
from
number
default:"0"
The starting position for pagination. Use this to skip a number of results for implementing pagination.Example: 0 (start from the first result), 10 (start from the 11th result)
size
number
default:"10"
The maximum number of results to return. Use this in combination with from for pagination.Example: 10, 25, 50

Headers

Authorization
string
required
Your access token obtained from the /v1/oauth2/token endpoint. Pass the token directly without the “Bearer” prefix.

Example Requests

# Basic search
curl -X GET "https://api.pretectum.io/dataobjects/search?query=John" \
  -H "Authorization: your_access_token"

# Search with filters
curl -X GET "https://api.pretectum.io/dataobjects/search?query=John&businessArea=Customer&schema=Individual" \
  -H "Authorization: your_access_token"

# Search with pagination
curl -X GET "https://api.pretectum.io/dataobjects/search?query=John&from=0&size=20" \
  -H "Authorization: your_access_token"

Response

A successful search returns a list of matching data objects and the total count.
hits
array
required
An array of data objects matching your search query. Each object contains the data fields defined in its schema plus metadata fields.
total
number
required
The total number of data objects matching your search query. Use this with from and size parameters for pagination.

Example Response

{
  "hits": [
    {
      "_dataObjectId": "20240601120000123f1a2b3c4d5e6789012345678901234",
      "_businessAreaName": "Customer",
      "_schemaName": "Individual Customer",
      "_dataSetName": "US Customers",
      "_businessAreaId": "20240115103000123a1b2c3d4e5f6789012345678901234",
      "_schemaId": "20240115103000456d1e2f3a4b5c6789012345678901234",
      "_dataSetId": "20240201140000789h3c4d5e6f7a8901234567890123456",
      "First Name": "John",
      "Last Name": "Smith",
      "Email": "[email protected]",
      "Phone": "+1-555-0123",
      "Street": "123 Main Street",
      "City": "New York",
      "State": "NY",
      "Zip Code": "10001"
    },
    {
      "_dataObjectId": "20240601120100456g2b3c4d5e6f7890123456789012345",
      "_businessAreaName": "Customer",
      "_schemaName": "Individual Customer",
      "_dataSetName": "US Customers",
      "_businessAreaId": "20240115103000123a1b2c3d4e5f6789012345678901234",
      "_schemaId": "20240115103000456d1e2f3a4b5c6789012345678901234",
      "_dataSetId": "20240201140000789h3c4d5e6f7a8901234567890123456",
      "First Name": "John",
      "Last Name": "Doe",
      "Email": "[email protected]",
      "Phone": "+1-555-0456",
      "Street": "456 Oak Avenue",
      "City": "Los Angeles",
      "State": "CA",
      "Zip Code": "90001"
    }
  ],
  "total": 2
}

Empty Results

When no data objects match your query, the response will contain an empty hits array:
{
  "hits": [],
  "total": 0
}

Error Responses

Status CodeDescription
401 UnauthorizedInvalid or expired access token. Obtain a new token and try again.
403 ForbiddenYou do not have permission to search data objects. Contact your tenant administrator.
400 Bad RequestMissing required query parameter or invalid parameter values.

Search Query Syntax

The query parameter supports two types of searches: full-text search for finding terms across all fields, and field-specific search for filtering by specific attribute values. Full-text search looks for matching terms across all indexed fields in your data objects.
PatternDescriptionExample
Simple termMatch records containing the term in any fieldJohn
Multiple termsMatch records containing all terms (implicit AND)John Smith
AND operatorExplicit AND between termsJohn AND Smith
OR operatorMatch records containing either termJohn OR Jane
NOT operatorExclude records containing a termJohn NOT Doe
WildcardsMatch partial termsJo* (matches John, Jones, etc.)
Phrase searchMatch exact phrase in sequence"John Smith"
GroupingGroup terms with parentheses(John OR Jane) AND Smith
# Find records containing "John" in any field
query=John

# Find records containing both "John" and "Smith" anywhere
query=John Smith
query=John AND Smith

# Find records containing either "John" or "Jane"
query=John OR Jane

# Find records with "John" but not "Doe"
query=John NOT Doe

# Find exact phrase "John Smith"
query="John Smith"

# Find names starting with "Jo"
query=Jo*

# Complex query with grouping
query=(John OR Jane) AND (Smith OR Doe)

Comparison Operators

You can also use comparison operators with bracket notation for field names. This syntax is useful when field names contain spaces or special characters.
OperatorDescriptionExample
eqEquals - exact match[First Name] eq "Tim"
neNot equals - exclude exact match[Status] ne "Inactive"
gtGreater than[Age] gt 21
ltLess than[Age] lt 65
geGreater than or equal[Order Amount] ge 100
leLess than or equal[Price] le 500
containsContains substring[Email] contains "example.com"
startswithStarts with value[Last Name] startswith "Sm"
endswithEnds with value[Email] endswith ".com"
# Find customers where First Name equals "Tim"
query=[First Name] eq "Tim"

# Find customers where Last Name equals "Smith"
query=[Last Name] eq "Smith"

# Find customers where Status is not "Inactive"
query=[Status] ne "Inactive"

# Find customers older than 21
query=[Age] gt 21

# Find customers 65 or younger
query=[Age] le 65

# Find orders with amount greater than or equal to $100
query=[Order Amount] ge 100

# Find products with price less than $500
query=[Price] lt 500

# Find customers with email containing "example.com"
query=[Email] contains "example.com"

# Find customers whose last name starts with "Sm"
query=[Last Name] startswith "Sm"

# Find customers whose email ends with ".org"
query=[Email] endswith ".org"

Combining Comparison Operators

You can combine multiple comparison operators using and and or keywords.
# Find customers named Tim Smith
query=[First Name] eq "Tim" and [Last Name] eq "Smith"

# Find customers in CA or NY
query=[State] eq "CA" or [State] eq "NY"

# Find active customers aged 18 to 65
query=[Status] eq "Active" and [Age] ge 18 and [Age] le 65

# Find premium customers with high order value
query=[Customer Type] eq "Premium" and [Order Amount] gt 1000

# Find customers in specific cities
query=[City] eq "New York" or [City] eq "Los Angeles" or [City] eq "Chicago"

# Complex condition with grouping
query=([State] eq "CA" or [State] eq "NY") and [Status] eq "Active"

# Find inactive customers or those with no recent orders
query=[Status] eq "Inactive" or [Last Order Date] lt "2024-01-01"

# Find products in Electronics category under $500
query=[Category] eq "Electronics" and [Price] le 500 and [In Stock] eq "true"

Mixing Query Styles

You can combine bracket notation with standard field syntax in the same query.
# Combine bracket notation with standard syntax
query=[First Name] eq "Tim" AND address.state:CA

# Full-text search with comparison operator
query=premium AND [Customer Type] eq "Enterprise"

# Field-specific with comparison operator
query=email:*@example.com and [Status] eq "Active"

Field-Specific Search (Attribute Filtering)

Filter records by specific attribute values using the field:value syntax. This allows you to target searches to particular fields in your data objects.
PatternDescriptionExample
Exact field matchMatch exact value in a specific fieldfirstName:John
Field with wildcardMatch partial values in a fieldemail:*@example.com
Field phraseMatch exact phrase in a fieldaddress.city:"New York"
Field rangeMatch numeric or date rangesage:[18 TO 65]
Field existsFind records where field has any value_exists_:email
Field missingFind records where field is emptyNOT _exists_:phone
Multiple fieldsCombine field filtersfirstName:John AND city:Boston
# Find customers with first name "John"
query=firstName:John

# Find customers with last name "Smith" or "Johnson"
query=lastName:(Smith OR Johnson)

# Find customers with email addresses from example.com
query=email:*@example.com

# Find customers in New York city
query=address.city:"New York"

# Find customers in California state
query=address.state:CA

# Find customers with a phone number on file
query=_exists_:phone

# Find customers missing email address
query=NOT _exists_:email

# Combine full-text and field-specific search
query=John AND address.state:NY

# Find customers in NY or CA with name containing "Smith"
query=lastName:*Smith* AND address.state:(NY OR CA)

Numeric and Date Range Queries

Use range syntax to filter by numeric values or dates.
PatternDescriptionExample
Inclusive rangeMatch values within range (inclusive)age:[18 TO 65]
Exclusive rangeMatch values within range (exclusive)age:{18 TO 65}
Greater thanMatch values greater thanage:>18
Less thanMatch values less thanage:<65
Greater or equalMatch values greater than or equalage:>=18
Less or equalMatch values less than or equalage:<=65
# Find customers aged 18 to 65 (inclusive)
query=age:[18 TO 65]

# Find customers aged between 18 and 65 (exclusive)
query=age:{18 TO 65}

# Find customers older than 21
query=age:>21

# Find customers 65 or younger
query=age:<=65

# Find orders with amount between $100 and $1000
query=orderAmount:[100 TO 1000]

# Find records created after a specific date
query=createdDate:>2024-01-01

# Find records updated in 2024
query=updatedDate:[2024-01-01 TO 2024-12-31]

Nested Object Queries

For data objects with nested attributes, use dot notation to access nested fields.
# Search by nested address fields
query=address.city:Boston
query=address.state:MA
query=address.zipCode:02101

# Search by nested contact information
query=contact.email:*@company.com
query=contact.phone.mobile:+1-555*

# Combine nested field searches
query=address.city:Boston AND address.state:MA

# Search nested objects with phrase
query=address.street:"123 Main Street"

Escaping Special Characters

If your search term contains special characters, escape them with a backslash (\). Special characters: + - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /
# Search for email with special characters
query=email:john\+[email protected]

# Search for values containing parentheses
query=company:"Acme \(Corp\)"

Query Examples by Use Case

# Find customer by full name
query=firstName:John AND lastName:Smith

# Find customers by email domain
query=email:*@bigcorp.com

# Find customers in a specific region
query=address.state:(CA OR OR OR WA) AND customerType:Enterprise

# Find customers with recent orders
query=lastOrderDate:>2024-01-01 AND status:Active

# Find VIP customers in New York
query=customerTier:VIP AND address.city:"New York"
# Find products by SKU prefix
query=sku:PROD-2024*

# Find products in a price range
query=price:[50 TO 200] AND category:Electronics

# Find products by brand
query=brand:(Apple OR Samsung OR Google)

# Find in-stock products
query=inventory:>0 AND status:Active

# Find products with specific attributes
query=color:Blue AND size:(M OR L) AND inStock:true
# Multi-condition customer search
query=(firstName:John OR firstName:Jane) AND address.state:CA AND NOT status:Inactive

# Product availability search
query=category:Electronics AND price:[100 TO 500] AND inventory:>10 AND rating:>=4

# Full-text with field filters
query="premium service" AND customerType:Enterprise AND region:(North OR East)

# Date range with status filter
query=createdDate:[2024-01-01 TO 2024-06-30] AND status:(Pending OR Processing)

Pagination

For large result sets, use pagination to retrieve results in smaller batches:
# First page (results 1-20)
GET /dataobjects/search?query=John&from=0&size=20

# Second page (results 21-40)
GET /dataobjects/search?query=John&from=20&size=20

# Third page (results 41-60)
GET /dataobjects/search?query=John&from=40&size=20
Use the total field in the response to determine the total number of pages available.

Best Practices

  1. Use specific queries: More specific queries return more relevant results and perform better.
  2. Filter by business area: When possible, filter by businessArea to narrow your search scope.
  3. Implement pagination: Always paginate large result sets to improve performance.
  4. Handle empty results: Your application should gracefully handle cases where no results are found.
  5. Cache tokens: Reuse access tokens until they expire rather than requesting a new token for each request.