Lookup Customer

Check if a customer exists in the GrandShift system by their phone number or shifter code. Use this endpoint before submitting a transaction to verify the customer is registered.

Development Environment

For testing and development, prepend the base URL: https://dev.api.grandshifts.com

GET/pos/v1/invoices/customers/lookup

How to Use

Provide either phoneNumber OR shifterCode as a query parameter.
At least one parameter is required.
Returns masked customer information if found.
All queries are logged for security and audit purposes.

Privacy & Security

Phone numbers are masked (only last 4 digits shown).
Display name shows first name + last initial only.
Requires x-api-key header for authentication.

Query Parameters

Property	Type	Description
phoneNumber	string	Customer phone number registered in GrandShift. Example: +966512345678
shifterCode	string	Customer shifter code. Example: SH123456

Parameter Requirement

At least one of phoneNumber or shifterCode must be provided.

Response Schema

Property	Type	Description
existsRequired	boolean	Whether the customer exists in GrandShift system. Example: true
phoneNumber	string	Customer phone number (masked for privacy - only last 4 digits shown). Example: ****5678
shifterCode	string	Customer shifter code. Example: SH123456
displayName	string	Customer display name (first name + last initial). Example: Mohammed A.

Example Request

cURL

curl -X 'GET' \
  'https://dev.api.grandshifts.com/pos/v1/invoices/customers/lookup?phoneNumber=%2B966512345678' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

Success Response (200 OK)

When the customer is found:

Customer Found

{
  "exists": true,
  "phoneNumber": "****5678",
  "shifterCode": "SH123456",
  "displayName": "Mohammed A."
}

When the customer is not found:

Customer Not Found

{
  "exists": false
}

Error Responses

400Bad Request

Neither phoneNumber nor shifterCode was provided in the query parameters.

401Unauthorized

Invalid or missing API key. Ensure you include a valid x-api-key header.