Leaving a Review

Allow clients to leave a review for a completed job directly from your service via an API key.

Purpose: Enables integrating the Logis review system into your own platform (website, app, etc.). Clients can submit ratings and comments for completed deliveries without needing to visit the Logis public tracking page directly.

Endpoint

Submits ratings and an optional comment for a specific job. This action can only be performed if the job status is COMPLETED and it is within the allowed review window (typically 7 days after completion).

POST Endpoint

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

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

Request Body

The endpoint expects a JSON payload in the request body with the following structure:

Request Body

{
  "job_id": "job-uuid-that-was-completed",       // Required: UUID of the job
  "review_key": "review-uuid-key-for-this-job", // Required: Client verification key
  "rating_delivery": 5,                         // Required: Integer rating (0-5) for delivery experience
  "rating_job": 4,                              // Optional: Integer rating (0-5) for the product/service itself
  "rating_comment": "Excellent service, driver was very courteous!" // Optional: Text comment
}

fields

Field	Type	Required	Description
`job_id`	string	Yes	The UUID of the job being reviewed.
`review_key`	string	Yes	The unique UUID review key associated with the job, used to verify the client's identity.
`rating_delivery`	integer	Yes	The rating for the delivery experience, typically on a scale of 0 to 5 (inclusive).
`rating_job`	integer	Optional	The rating for the actual product or service provided (if applicable), scale 0–5.
`rating_comment`	string	Optional	A text comment providing further feedback.

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 submission of the review, the endpoint returns a 200 OK status code and a JSON body containing a confirmation message and the updated job data (reflecting the newly added ratings).

Response Body

{
  "message": "Job reviewed successfully",
  "job": {
    "id": "job-uuid-that-was-completed",
    "name": "Reviewed Delivery",
    // ... other job fields ...
    "status": "COMPLETED",
    "completed_at": "2025-04-10T10:00:00Z", // Example completion time
    "rating_delivery": 5, // Updated field
    "rating_job": 4, // Updated field (if provided)
    "rating_comment": "Excellent service, driver was very courteous!", // Updated field
    // ... other job fields ...
    "address": "address-uuid",
    "address_detail": { /* ... */ }
  }
}

Error Responses

Status Code	Error Code / Reason	Description
`400 Bad Request`	Missing Required Fields	`job_id`, `review_key`, or `rating_delivery` was missing from the request body.
`400 Bad Request`	Invalid Rating Value	The provided `rating_delivery` or `rating_job` was not a valid integer or was outside the allowed range (0–5).
`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_review)	The API key used does not have permission to submit reviews.
`404 Not Found`	Invalid job_id or review_key	No job was found matching the provided `job_id` and `review_key` combination.
`412 Precondition Failed`	Job Not Completed	The specified job has not yet been marked as `COMPLETED`.
`412 Precondition Failed`	Review Window Expired	The review submission is outside the allowed timeframe (e.g., more than 7 days after job completion).
`429 Too Many Requests`	Rate Limit Exceeded (Key or Global)	The API key's hourly limit or the user's global daily limit was exceeded.

Code Examples

Future<Map<String, dynamic>?> submitReview({ // Return updated job data
  required String jobId,
  required String reviewKey,
  required int ratingDelivery,
  int? ratingJob,
  String? ratingComment,
  required String apiKey,
}) async {
  final String url = 'https://app.logisapp.ca/api/apikeys/submit_review';
  final Map<String, String> headers = {
    'Content-Type': 'application/json',
    'LOGIS-API-KEY': apiKey,
  };
  final Map<String, dynamic> body = {
    'job_id': jobId,
    'review_key': reviewKey,
    'rating_delivery': ratingDelivery,
    if (ratingJob != null) 'rating_job': ratingJob,
    if (ratingComment != null && ratingComment.isNotEmpty) 'rating_comment': ratingComment,
  };
 
  try {
    final response = await http.post(
      Uri.parse(url),
      headers: headers,
      body: json.encode(body),
    );
 
    final decodedBody = json.decode(response.body);
 
    if (response.statusCode == 200 && decodedBody != null && decodedBody['job'] is Map) {
      debugPrint('Review submitted successfully for job $jobId.');
      return decodedBody['job']; // Return updated job map
    } else {
      final errorMessage = decodedBody['error'] ?? 'Request failed with status: ${response.statusCode}';
      debugPrint('LogisService API error (submitReview): $errorMessage');
      throw Exception(errorMessage);
    }
  } catch (error) {
    debugPrint('LogisService Network/Request error (submitReview): $error');
    throw Exception('Failed to submit review: $error');
  }
}

Leaving a Review

Endpoint

Authentification

Request Body

fields

Success Response

Error Responses

Code Examples

On this page