API/Clients

Finding Client

API endpoint for finding existing clients based on various criteria via an API key.

Endpoint

Finds exisitng clients associated with the user linked to the API key.

GET Endpoint

https://app.logisapp.ca/api/apikeys/find_client

Usage

This endpoint can be used to fetch fully client information, including their ID. If you have existing clients in your service and in Logis, and you need to link them together, this endpoint is perfect for you.

Note: This endpoint provides more control/options than the Auto-Match Clients process during a Job creation — this endpoint provides you with all matches and allows you to choose a specific match, instead of imposing one.

Authentification

This endpoint requires authentification via a custom API key header.

Required Header

LOGIS-API-KEY: YOUR_SECRET_API_KEY

The API key used must have the "Allow Client Interaction" permission enabled in the Logis settings.

Request Parameters

This endpoint accepts query parameters in the URL. You must provide at least one of the following parameters: client_id, phone_number or email.

Parameter	Type	Required	Description
`client_id`	string	Optional (UUID)	The UUID of a specific EndClient to find. If provided, other parameters are ignored for initial lookup.
`phone_number`	string	Optional	Used for searching clients if `client_id` is not provided or not found. Format: `+1 XXX-XXX-XXXX`.
`email`	string	Optional	Used for searching clients if `client_id` is not provided or not found.
`first_name`	string	Optional	Used for searching clients alongside `phone_number` or `email` if `client_id` is not provided/found.
`last_name`	string	Optional	Used for searching clients alongside `phone_number` or `email` if `client_id` is not provided/found.

Example URLs

Find by specific ID: GET /api/apikeys/find_client?client_id=YOUR_CLIENT_UUID
Find by phone number: GET /api/apikeys/find_client?phone_number=+1 555-123-4567
Find by email: GET /api/apikeys/find_client?email=john.doe@example.com
Find by email and last name: GET /api/apikeys/find_client?email=john.doe@example.com&last_name=Doe

Success Response

The endpoint returns a 200 OK status code. The response body depends on whether a specific client_id was used for lookup or if other parameters were used for matching.

Response for `client_id` lookup

Response body

{
  "client": {
    "id": "client-uuid",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+1 555-123-4567",
    "email": "john.doe@example.com",
    "created_at": "2025-04-09T12:29:00Z",
    "is_active": true,
    "notes": "Client notes.",
    "do_notify_sms": true,
    "added_by": "store-owner-user-uuid",
    "code_secure_deliveries": false,
    "address": "client-default-address-uuid",
    "address_detail": {
      "id": "client-default-address-uuid",
      // ... client's default address fields ...
    }
  }
}

Response for match

Response body

{
  "clients": [
    {
      "id": "client-uuid-1",
      "first_name": "John",
      "last_name": "Doe",
      // ... other client fields ...
      "address": "address-uuid-1",
      "address_detail": { /* ... address fields ... */ }
    },
    {
      "id": "client-uuid-2",
      "first_name": "John",
      "last_name": "Smith",
      // ... other client fields ...
      "address": "address-uuid-2",
      "address_detail": { /* ... address fields ... */ }
    }
    // ... more clients if multiple match ...
  ],
  "only_one_found": false // Set to true if exactly one client matched the search criteria
}

Error Responses

Status Code	Error Code / Reason	Description
`400 Bad Request`	Missing Parameters (phone_number or email)	Neither `phone_number` nor `email` was provided when `client_id` was also missing or not found.
`401 Unauthorized`	Missing LOGIS-API-KEY header	The required API key header was not included.
`403 Forbidden`	Invalid/Inactive LOGIS-API-KEY	The provided API key is not valid or is inactive.
`403 Forbidden`	Permission Denied (allow_client)	The API key used does not have permission for client interaction.
`404 Not Found`	Client ID Not Found (client_id lookup)	A specific `client_id` was provided, but no client exists with that ID for the associated user.

Code Examples

// Define your Client class if needed
// class Client { ... }
 
// Function to find a client by ID
Future<Map<String, dynamic>?> findClientById(String clientId, String apiKey) async {
  final String url = 'https://app.logisapp.ca/api/apikeys/find_client/?client_id=$clientId';
  final Map<String, String> headers = {
    'LOGIS-API-KEY': apiKey,
  };
 
  try {
    final response = await http.get(
      Uri.parse(url),
      headers: headers,
    );
 
    final decodedBody = json.decode(response.body);
 
    if (response.statusCode == 200 && decodedBody != null && decodedBody['client'] is Map) {
      debugPrint('Client found successfully by ID.');
      return decodedBody['client']; // Return the client data map
    } else if (response.statusCode == 404) {
      debugPrint('Client not found with ID: $clientId');
      return null; // Indicate client not found
    } else {
      final errorMessage = decodedBody['error'] ?? 'Request failed with status: ${response.statusCode}';
      debugPrint('LogisService API error (findClientById): $errorMessage');
      throw Exception(errorMessage);
    }
  } catch (error) {
    debugPrint('LogisService Network/Request error (findClientById): $error');
    throw Exception('Failed to find client: $error');
  }
}
 
// Function to find clients based on search criteria
Future<List<Map<String, dynamic>>?> findClientsBySearch({
  String? phoneNumber,
  String? email,
  String? firstName,
  String? lastName,
  required String apiKey,
}) async {
  // Ensure at least one required search parameter is provided
  if (phoneNumber == null && email == null) {
     throw Exception('At least one of phone_number or email must be provided for search.');
  }
 
  final Map<String, String> queryParams = {};
  if (phoneNumber != null) queryParams['phone_number'] = phoneNumber;
  if (email != null) queryParams['email'] = email;
  if (firstName != null) queryParams['first_name'] = firstName;
  if (lastName != null) queryParams['last_name'] = lastName;
 
  final String url = 'https://app.logisapp.ca/api/apikeys/find_client/'; // Base URL
  final uri = Uri.parse(url).replace(queryParameters: queryParams);
 
  final Map<String, String> headers = {
    'LOGIS-API-KEY': apiKey,
  };
 
  try {
    final response = await http.get(
      uri,
      headers: headers,
    );
 
    final decodedBody = json.decode(response.body);
 
    if (response.statusCode == 200 && decodedBody != null && decodedBody['clients'] is List) {
      debugPrint('Clients found successfully via search.');
      return List<Map<String, dynamic>>.from(decodedBody['clients']); // Return list of client maps
    } else {
      final errorMessage = decodedBody['error'] ?? 'Request failed with status: ${response.statusCode}';
      debugPrint('LogisService API error (findClientsBySearch): $errorMessage');
      throw Exception(errorMessage);
    }
  } catch (error) {
    debugPrint('LogisService Network/Request error (findClientsBySearch): $error');
    throw Exception('Failed to find clients: $error');
  }
}

Deletion

API endpoint for deleting a client via an API key.

Creation

API endpoint for creating a new delivery job via an API key.