Creation

Note: This endpoint specifically creates a new client. To find existing clients, use the Find Client endpoint. To create a job and potentially match/create a client simultaneously, use the Create Job endpoint.

Endpoint

Creates a new End Client associated with the user linked to the API key.

POST Endpoint

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

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 Body

Request Body Example

{
  // --- Client Details (Required) ---
  "first_name": "Jane",
  "last_name": "Smith",
  "phone_number": "+1 555-987-6543", // Optional (Format: '+1 XXX-XXX-XXXX')
  "email": "jane.smith@sample.net",   // Optional
  "notes": "Prefers morning deliveries.", // Optional
  "do_notify_sms": true,                // Optional (Defaults based on company/system settings)
  "code_secure_deliveries": false,      // Optional (Defaults based on company/system settings)
 
  // --- Address Details (Required) ---
  "address": {
    "building_number": 456,
    "street_name": "Oak Avenue",
    "apt_number": "Unit 12", // Optional
    "city": "Mapleton",
    "postal_code": "X9Y 8Z7",
    "notes": "Leave packages at the back door." // Optional
  }
}

Field Descriptions

Top-Level Client Fields

Field	Type	Required	Description
`first_name`	string	Yes	New client's first name. Max 100 chars.
`last_name`	string	Yes	New client's last name. Max 100 chars.
`phone_number`	string	Optional	Client's phone number. Must be in format `+1 XXX-XXX-XXXX`.
`email`	string	Optional	Client's email address (valid email format).
`notes`	string	Optional	General notes about the client. Max 1000 chars.
`do_notify_sms`	boolean	Optional	Client's general preference for receiving SMS notifications. Defaults to the creating user's company settings, then `true`.
`code_secure_deliveries`	boolean	Optional	Client's preference for requiring secure delivery codes. Defaults to the company setting, then `false`.

`Address` Object (Required)

A client must have an address upon creation. This object contains the details.

Field	Type	Required	Description
`building_number`	integer	Yes	The street number of the address.
`street_name`	string	Yes	The name of the street. Max 250 chars.
`apt_number`	string	Optional	Apartment, suite, unit number, etc. Max 50 chars.
`city`	string	Yes	The city name. Max 100 chars.
`postal_code`	string	Yes	The postal or zip code. Max 20 chars.
`notes`	string	Optional	Specific notes for this address (e.g., gate code, delivery instructions). Max 1000 chars.

Success Response

On successful creation, the endpoint returns a 201 Created status code and a JSON body containing the details of the newly created client object:

{
  "client": {
    "id": "new-client-uuid-generated-by-server",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone_number": "+1 555-987-6543",
    "email": "jane.smith@sample.net",
    "created_at": "2025-04-09T13:00:00Z", // Server timestamp
    "is_active": true,
    "notes": "Prefers morning deliveries.",
    "do_notify_sms": true,
    "added_by": "store-owner-user-uuid", // User associated with API Key
    "code_secure_deliveries": false,
    "address": "new-address-uuid-created", // ID of the created address
    "address_detail": { // Nested address object
      "id": "new-address-uuid-created",
      "building_number": 456,
      "street_name": "Oak Avenue",
      "apt_number": "Unit 12",
      "city": "Mapleton",
      "postal_code": "X9Y 8Z7",
      "notes": "Leave packages at the back door.",
      "latitude": 45.67890, // Populated by geocoding
      "longitude": -73.12345, // Populated by geocoding
      "added_by": "store-owner-user-uuid" // User associated with API Key
    }
  }
}

Error Responses

Status Code	Error Code / Reason	Description
`400 Bad Request`	Missing Required Fields	Required fields like `first_name`, `last_name`, or the entire address object were missing.
`400 Bad Request`	Invalid Data Format	Data provided failed validation (e.g., invalid email, incorrect phone number format).
`400 Bad Request`	Invalid Address (Geocoding/Validation Failed)	The provided address object could not be geocoded or failed validation.
`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.
`429 Too Many Requests`	Exceeded maximum requests

Code Examples

Future<Map<String, dynamic>> addClient(Map<String, dynamic> clientAndAddressData, String apiKey) async {
  final String url = 'https://app.logisapp.ca/api/apikeys/add_client';
  final Map<String, String> headers = {
    'Content-Type': 'application/json',
    'LOGIS-API-KEY': apiKey,
  };
 
  try {
    final response = await http.post(
      Uri.parse(url),
      headers: headers,
      body: json.encode(clientAndAddressData), // Send combined client & address data
    );
 
    final decodedBody = json.decode(response.body);
 
    if (response.statusCode == 201) {
      print('Client created successfully.');
      return decodedBody['client']; // Return the created client data map
    } else {
      final errorMessage = decodedBody['error'] ?? 'Request failed with status: ${response.statusCode}';
      print('LogisService API error (addClient): $errorMessage');
      throw Exception(errorMessage);
    }
  } catch (error) {
    print('LogisService Network/Request error (addClient): $error');
    // Consider more specific error handling if needed
    if (error is FormatException) { // JSON decoding error
         throw Exception('Failed to decode server response.');
    }
    throw Exception('Failed to add client: $error');
  }
}

Creation

On this page