Locations
Search locations
Search locations using OpenSearch-powered full-text and field-specific search.
This endpoint provides fast, indexed search across location data with support for:
- Full-text search across multiple fields
- Field-specific filtering with various operators
- Geographic search capabilities
- Sorting and pagination
- Saved search preferences
Note: Only active (non-deleted) locations are searchable. Soft-deleted records are automatically excluded from all search results.
Response Formats:
- flat (default): Returns indexed fields only for faster performance
- full: Returns complete location objects with all relationships
post/locations/search
Request body
Example request
{
"criteria": {
"id": {
"operator": "EQUALS",
"values": [
"550e8400-e29b-41d4-a716-446655440000"
]
},
"customerId": {
"operator": "EQUALS",
"values": [
"550e8400-e29b-41d4-a716-446655440000"
]
},
"customerName": {
"operator": "INCLUDES",
"values": [
"search term"
]
},
"customerFriendlyId": {
"operator": "ONE_OF",
"values": [
"ACTIVE",
"PENDING"
]
},
"type": {
"operator": "ONE_OF",
"values": [
"ACTIVE",
"PENDING"
]
},
"name": {
"operator": "INCLUDES",
"values": [
"search term"
]
},
"externalId": {
"operator": "ONE_OF",
"values": [
"ACTIVE",
"PENDING"
]
},
"line1": {
"operator": "INCLUDES",
"values": [
"search term"
]
},
"line2": {
"operator": "INCLUDES",
"values": [
"search term"
]
},
"city": {
"operator": "INCLUDES",
"values": [
"search term"
]
},
"state": {
"operator": "ONE_OF",
"values": [
"ACTIVE",
"PENDING"
]
},
"postalCode": {
"operator": "ONE_OF",
"values": [
"ACTIVE",
"PENDING"
]
},
"country": {
"operator": "ONE_OF",
"values": [
"ACTIVE",
"PENDING"
]
},
"market": {
"operator": "ONE_OF",
"values": [
"ACTIVE",
"PENDING"
]
},
"zone": {
"operator": "ONE_OF",
"values": [
"ACTIVE",
"PENDING"
]
},
"phoneNumber": {
"operator": "INCLUDES",
"values": [
"search term"
]
},
"appointmentRequired": {
"operator": "TRUE"
},
"stopsCount": {
"operator": "BETWEEN",
"min": 10,
"max": 100
},
"createdAt": {
"operator": "AFTER",
"value": "2025-01-01T00:00:00Z"
}
},
"pagination": {
"pageNumber": 1,
"pageSize": 50
},
"sort": [
{
"field": "createdAt",
"order": "desc"
}
],
"savedSearch": {
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}Response
Successful search results
Example response
{
"data": [
{
"object": "LOCATION",
"id": "770e8400-e29b-41d4-a716-446655440000",
"customerId": "550e8400-e29b-41d4-a716-446655440000",
"customer": {
"object": "CUSTOMER",
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Acme Manufacturing Corp",
"friendlyId": "A123456",
"website": "https://acme-manufacturing.com",
"phoneNumber": "+1-555-123-4567",
"naics": "336411",
"ein": "12-3456789",
"duns": "123456789",
"leadSource": "Referral",
"dbaName": "Acme Corp DBA",
"externalId": "EXT-12345",
"creditLimit": 50000,
"creditUsageWarning": 40000,
"freeCreditReq": 5000,
"defaultMargin": 0.15,
"minMargin": 0.1,
"maxMargin": 0.25,
"defaultInternalNotes": "Contact via email only",
"defaultCarrierNotes": "Call pickup contact before arrival",
"defaultExternalNotes": "Please call 1 hour before delivery",
"group": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "ERP-USER-12345"
},
"paymentTerm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "ERP-PAYTERM-NET30",
"name": "Net 30",
"description": "Payment due 30 days from invoice date",
"days": 30,
"quickPayFee": 0.05,
"createdAt": "2025-01-15T10:00:00Z",
"updatedAt": "2025-01-15T14:30:00Z"
},
"notes": "Prefers email communication",
"closedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "ERP-USER-12345",
"email": "john.doe@example.com",
"name": "John Doe",
"phone": "+1-555-123-4567",
"phoneExt": "123",
"status": "ACTIVE",
"avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"createdAt": "2025-01-15T10:00:00Z",
"updatedAt": "2025-01-15T14:30:00Z"
},
"corporateAddress": {
"line1": "123 Main St",
"line2": "Suite 400",
"city": "Chicago",
"country": "USA",
"market": "CHI",
"latitude": "41.8781",
"longitude": "-87.6298",
"isSmartyValidated": true,
"obeysDst": true
},
"billingAddress": {
"line1": "123 Main St",
"line2": "Suite 400",
"city": "Chicago",
"country": "USA",
"market": "CHI",
"latitude": "41.8781",
"longitude": "-87.6298",
"isSmartyValidated": true,
"obeysDst": true
},
"key": "ERP-CUSTOMER-12345",
"contacts": [
{
"object": "CUSTOMER_CONTACT",
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "ERP-CONTACT-JOHN-001",
"name": "John Smith",
"contactInfo": {
"name": "John Smith",
"email": "john.smith@example.com",
"phoneNumber": "+1-555-0100",
"title": "Operations Manager"
},
"phoneExtension": "1234",
"isPrimary": true,
"contactTypes": [
"BILLING",
"ACCOUNT_MANAGER"
],
"notifications": [
"SHIPMENT_PICKED_UP",
"SHIPMENT_DELIVERED"
],
"invitedUser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "ERP-USER-12345",
"email": "john.doe@example.com",
"name": "John Doe",
"phone": "+1-555-123-4567",
"phoneExt": "123",
"status": "ACTIVE",
"avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"createdAt": "2025-01-15T10:00:00Z",
"updatedAt": "2025-01-15T14:30:00Z"
},
"deletedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "ERP-USER-12345",
"email": "john.doe@example.com",
"name": "John Doe",
"phone": "+1-555-123-4567",
"phoneExt": "123",
"status": "ACTIVE",
"avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"createdAt": "2025-01-15T10:00:00Z",
"updatedAt": "2025-01-15T14:30:00Z"
},
"createdAt": "2025-01-15T10:00:00Z"
}
],
"createdAt": "2025-01-15T10:00:00Z",
"updatedAt": "2025-01-15T14:30:00Z",
"deletedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "ERP-USER-12345",
"email": "john.doe@example.com",
"name": "John Doe",
"phone": "+1-555-123-4567",
"phoneExt": "123",
"status": "ACTIVE",
"avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"createdAt": "2025-01-15T10:00:00Z",
"updatedAt": "2025-01-15T14:30:00Z"
}
},
"name": "ABC Warehouse - Dallas",
"key": "ERP-LOC-DALLAS-01",
"isAppointmentRequired": true,
"notes": "Call 24 hours ahead for appointment",
"internalNotes": "Use dock door 5 for expedited shipments",
"contacts": [
{
"object": "LOCATION_CONTACT",
"id": "880e8400-e29b-41d4-a716-446655440000",
"customerContactId": "660e8400-e29b-41d4-a716-446655440000",
"customerContact": {
"object": "CUSTOMER_CONTACT",
"id": "550e8400-e29b-41d4-a716-446655440000",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "ERP-CUSTOMER-ACME",
"name": "Acme Manufacturing Corp",
"friendlyId": "A123456",
"status": "ACTIVE",
"phoneNumber": "+1-555-123-4567",
"website": "https://acme-manufacturing.com",
"createdAt": "2025-01-15T10:00:00Z",
"updatedAt": "2025-01-15T14:30:00Z"
},
"name": "John Smith",
"contactInfo": {
"name": "John Smith",
"email": "john.smith@example.com",
"phoneNumber": "+1-555-0100",
"title": "Operations Manager"
},
"phoneExtension": "1234",
"isPrimary": true,
"contactTypes": [
"BILLING",
"ACCOUNT_MANAGER"
],
"notifications": [
"SHIPMENT_PICKED_UP",
"SHIPMENT_DELIVERED"
],
"invitedUser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "ERP-USER-12345",
"email": "john.doe@example.com",
"name": "John Doe",
"phone": "+1-555-123-4567",
"phoneExt": "123",
"status": "ACTIVE",
"avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"createdAt": "2025-01-15T10:00:00Z",
"updatedAt": "2025-01-15T14:30:00Z"
},
"deletedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "ERP-USER-12345",
"email": "john.doe@example.com",
"name": "John Doe",
"phone": "+1-555-123-4567",
"phoneExt": "123",
"status": "ACTIVE",
"avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"createdAt": "2025-01-15T10:00:00Z",
"updatedAt": "2025-01-15T14:30:00Z"
},
"key": "ERP-CONTACT-JOHN-001",
"createdAt": "2025-01-15T10:00:00Z"
},
"isPrimary": true,
"contactTypes": [
"LOCATION_MANAGER",
"SHIPPING"
],
"key": "ERP-LOC-CONTACT-001",
"createdAt": "2025-01-15T10:00:00Z",
"updatedAt": "2025-01-15T14:30:00Z"
}
],
"createdAt": "2025-01-15T10:00:00Z",
"updatedAt": "2025-01-15T14:30:00Z"
}
],
"pagination": {
"pageNumber": 1,
"pageSize": 50,
"totalPages": 25
}
}