API/Tracking

Toggle SMS Notifications

Allow clients to enable or disable SMS notifications for a specific job or for all their future jobs via an API key.

Purpose: Provides end clients with control over their SMS notification preferences directly from your integrated platform, using their secure review_key for authentication.

Endpoint

Updates the SMS notification setting (do_notify_sms) either for a specific job or for the client's overall profile.

PUT Endpoint
https://app.logisapp.ca/api/apikeys/toggle_sms_notifications

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 Public Track" permission enabled in the Logis settings.

Request Body

The endpoint expects a JSON payload in the request body specifying the job, verification key, the desired notification state, and whether to update the job or the client profile:

Request Body
{
  "job_id": "job-uuid",             // Required: UUID of the relevant job
  "review_key": "review-uuid-key",    // Required: Client verification key for the job
  "do_notify_sms": "false",           // Required: Desired state ('true' or 'false' as strings)
  "update_target": "job"              // Required: Either 'job' or 'client'
}

Fields

FieldTypeRequiredDescription
job_idstringYesThe UUID of a job associated with the client whose preference is being changed. Used with review_key to authenticate the client.
review_keystringYesThe unique UUID review key associated with the specified job_id, used for client verification.
do_notify_smsstringYesThe desired SMS notification state. Must be sent as the string "true" or "false".
update_targetstringYesSpecifies what to update. Must be either "job" (to change setting for this job only) or "client" (to change default preference).

The review_key acts as a secure token to verify that the request likely originates from the intended recipient (or a system acting on their behalf). This key is usually sent to the client via SMS or email through Logis' notification system (e.g., in the public tracking link). You can retrieve the review_key for a specific job using the Fetch Job Track endpoint.

Success Response

On successful update, the endpoint returns a 200 OK status code. The response body contains either the updated job object or the updated end_client object, depending on the update_target.

Response for update_target : "job"

Response Body
{
  "job": {
    "id": "job-uuid",
    // ... other job fields ...
    "do_notify_sms": false, // Reflects the updated value for this job
    // ... other job fields ...
    "address_detail": { /* ... */ }
  }
}

Response for update_target : "client"

Response Body
{
  "end_client": {
    "id": "client-uuid",
    // ... other client fields ...
    "do_notify_sms": true, // Reflects the updated default value for the client
    // ... other client fields ...
    "address_detail": { /* ... */ }
  }
}

Error Responses

Status CodeError Code / ReasonDescription
400 Bad RequestMissing Required Fieldsjob_id, review_key, do_notify_sms, or update_target was missing.
400 Bad RequestInvalid review_key formatThe provided review_key was not a valid UUID format.
400 Bad RequestInvalid update_targetThe update_target value was something other than "job" or "client".
401 UnauthorizedMissing LOGIS-API-KEY headerThe required API key header was not included.
401 UnauthorizedIncorrect review_keyThe review_key provided does not match the one associated with the job_id.
403 ForbiddenInvalid/Inactive LOGIS-API-KEYThe provided API key is not valid or is inactive.
403 ForbiddenPermission Denied (allow_public_track)The API key used does not have the required permission (public track permission enables this toggle).
404 Not FoundJob Not FoundNo job exists with the provided job_id.
429 Too Many RequestsRate Limit Exceeded (Key or Global)The API key's hourly limit or the user's global daily limit was exceeded.

Code Examples

// Define Job/Client classes if needed for parsing response
 
Future<Map<String, dynamic>?> toggleSmsNotifications({
  required String jobId,
  required String reviewKey,
  required bool doNotify, // Use boolean for clarity
  required String updateTarget, // 'job' or 'client'
  required String apiKey,
}) async {
  if (updateTarget != 'job' && updateTarget != 'client') {
    throw ArgumentError("updateTarget must be 'job' or 'client'");
  }
 
  final String url = 'https://app.logisapp.ca/api/apikeys/toggle_sms_notifications'; 
  final Map<String, String> headers = {
    'Content-Type': 'application/json',
    'LOGIS-API-KEY': apiKey,
  };
  final Map<String, dynamic> body = {
    'job_id': jobId,
    'review_key': reviewKey,
    'do_notify_sms': doNotify.toString(), // Convert boolean to string 'true'/'false'
    'update_target': updateTarget,
  };
 
  try {
    final response = await http.put( // Use http.put
      Uri.parse(url),
      headers: headers,
      body: json.encode(body),
    );
 
    final decodedBody = json.decode(response.body);
 
    if (response.statusCode == 200 && decodedBody != null) {
       if (updateTarget == 'job' && decodedBody['job'] is Map) {
          debugPrint('SMS notification toggled successfully for job $jobId.');
          return decodedBody['job'];
       } else if (updateTarget == 'client' && decodedBody['end_client'] is Map) {
          debugPrint('SMS notification toggled successfully for client associated with job $jobId.');
          return decodedBody['end_client'];
       } else {
           throw Exception('API Success Status (200) but response format is unexpected.');
       }
    } else {
      final errorMessage = decodedBody['error'] ?? 'Request failed with status: ${response.statusCode}';
      debugPrint('LogisService API error (toggleSms): $errorMessage');
      throw Exception(errorMessage);
    }
  } catch (error) {
    debugPrint('LogisService Network/Request error (toggleSms): $error');
    throw Exception('Failed to toggle SMS notifications: $error');
  }
}

On this page