Skip to main content
The SearchCustomers endpoint provides fast, flexible customer lookup by name, email, or user code. It supports two modes: a standard LIKE-based search for most use cases, and an advanced fuzzy matching mode that uses phonetic and distance algorithms to surface relevant results even when spellings are uncertain or inconsistent.

​
Endpoint

GET /api/SearchCustomers.php
Authentication: JWT Bearer token required. 
Authorization: Bearer <your_token>

​
Query Parameters

​
q
string
required
The search term to match against. Must be at least 2 characters long. Shorter values are rejected to prevent overly broad queries.
​
limit
integer
default:"15"
Maximum number of results to return. Cannot exceed 50.
​
courier_id
integer
Restrict results to customers belonging to a specific courier. When omitted, results are scoped to the authenticated user’s accessible couriers.
​
advanced
boolean
default:"false"
Set to true to enable fuzzy matching mode. See Advanced Search below for details.

​
Basic Search (Default)

When advanced is omitted or set to false, the endpoint performs a standard SQL LIKE search across the following fields:
  • first_name
  • last_name
  • Full name (first + last combined)
  • email
  • user_code
Results are sorted alphabetically by last_name, then first_name.

​
Example Request

GET /api/SearchCustomers.php?q=jane+smith&limit=10

curl "https://app.shiipp.com/api/SearchCustomers.php?q=jane+smith&limit=10" \
  -H "Authorization: Bearer <your_token>"

​
Example Response

{
  "status": "success",
  "count": 3,
  "data": [
    {
      "courier_customer_id": "cust-uuid",
      "user_code": "CUST001",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": null,
      "courier_id": "courier-uuid",
      "courier_name": "Express Couriers",
      "match_score": null
    }
  ]
}
Enabling advanced=true activates a multi-signal relevance engine that ranks results by how closely they match the query. This is the recommended mode when user input may contain typos, phonetic variations, or transposed name parts. The advanced mode applies three scoring signals in combination:
SignalDescription
Levenshtein DistanceMeasures the character-level edit distance between the query and each candidate field. Closer matches score higher.
Soundex Phonetic MatchingGroups names that sound alike (e.g., “Smith” and “Smyth”) so phonetic variants are surfaced even without exact spelling.
Token-Based ScoringSplits the query into individual tokens and scores partial word matches across all searchable fields.
Results are ranked by a combined match_score and returned in descending score order.

​
Example Request

GET /api/SearchCustomers.php?q=jayne+smyth&advanced=true&limit=10

curl "https://app.shiipp.com/api/SearchCustomers.php?q=jayne+smyth&advanced=true&limit=10" \
  -H "Authorization: Bearer <your_token>"

​
Example Response

{
  "status": "success",
  "count": 3,
  "data": [
    {
      "courier_customer_id": "cust-uuid",
      "user_code": "CUST001",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": null,
      "courier_id": "courier-uuid",
      "courier_name": "Express Couriers",
      "match_score": 2150.0
    }
  ]
}

​
Response Fields

​
status
string
"success" when the search completed without error.
​
count
integer
Number of results returned in this response (not the total across all pages — this endpoint does not paginate).
​
data
array
Array of matching customer objects, ordered by relevance.

​
Choosing the Right Mode

  • You have a known, correctly spelled name or user code
  • You’re building a fast autocomplete or type-ahead UI component
  • You want the lightest possible response time
For customer lookup fields in your application UI, start with basic search as the default and provide an optional “fuzzy search” toggle that appends &advanced=true when the user finds no results. This balances performance with coverage.
The match_score value is a composite internal score and is not normalized to a fixed range. Use it for relative ranking within a single response — do not compare scores across separate requests.