# Search globally

Search across multiple entity types simultaneously (shipments, customers, carriers, users, vendors).

Use Cases:
- Unified search bar for finding any type of record
- Quick lookup by name, ID, or reference number
- Cross-entity discovery

Search Behavior:
- Searches across default searchable fields for each entity type
- Results are sorted by object type priority: SHIPMENT → CUSTOMER → CARRIER → USER → VENDOR
- Within each object type, results are sorted by most recently updated

Prefix Filtering:
Use "type:query" syntax to search specific object types:
- carrier:acme - searches only carriers
- shipment:12345 - searches only shipments
- customer:west - searches only customers

IMPORTANT: Eventually Consistent
This endpoint queries OpenSearch indices which are updated asynchronously.
Changes typically appear within 2 seconds, but this is not guaranteed.

Endpoint: POST /global-search
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `query` (string, required)
    Search query string. Searches across default searchable fields for each entity type.

Supports prefix filtering using "type:query" syntax:
- carrier:acme - searches only carriers for "acme"
- shipment:12345 - searches only shipments for "12345"
- user:john - searches only users for "john"
    Example: "acme corp"

  - `objects` (array)
    Optional filter to limit search to specific object types.
If not provided, searches across all object types.
    Enum: "SHIPMENT", "CUSTOMER", "CARRIER", "USER", "VENDOR"

  - `pagination` (object)
    Pagination options for search requests

  - `pagination.pageNumber` (integer)
    Page number (1-based)
    Example: 1

  - `pagination.pageSize` (integer)
    Number of results per page (max 250)
    Example: 50

## Response 200 fields (application/json):

  - `data` (array, required)
    Search results sorted by object type priority:
SHIPMENT → CUSTOMER → CARRIER → USER → VENDOR

  - `data.object` (string, required)
    The type of object this result represents
    Enum: "SHIPMENT", "CUSTOMER", "CARRIER", "USER", "VENDOR"

  - `data.id` (string, required)
    Unique identifier of the matched record

  - `data.key` (string,null)
    Client-defined reference identifier if set
    Example: "ERP-CUST-12345"

  - `data.entityName` (string, required)
    Internal entity type name (for backwards compatibility).
Prefer using the object field instead.
    Example: "SHIPPER_PROFILE"

  - `data.title` (string, required)
    Primary display text for the result (e.g., name, friendlyId)
    Example: "Acme Corporation"

  - `data.subtitle` (string,null)
    Secondary display text (varies by entity type)
    Example: "CUST-12345"

  - `data.field` (string, required)
    Name of the field that matched the search query
    Example: "Name"

  - `data.highlight` (string,null)
    Matched text with highlight markers.
Contains HTML <em> tags around matched portions.
    Example: "<em>Acme</em> Corporation"

  - `pagination` (object, required)
    Pagination information for search results

  - `pagination.pageNumber` (integer, required)
    Current page number
    Example: 1

  - `pagination.pageSize` (integer, required)
    Number of results returned on this page
    Example: 50

  - `pagination.totalPages` (integer, required)
    Total number of pages available
    Example: 25

  - `totalResults` (integer, required)
    Total number of matching results across all object types
    Example: 42

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message

## Response 429 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message