Quality Score Report

Completion-quality score per group based on captured form fields, photos, and signature on finished tasks.

GET/apidev/v1/reports/gt/quality-score

PermissionAPICLI_RPTGT_QUALITYSCORE

Rate Limit10 req/min

Cache300s

Max Range92 days

---

Overview

Scores how completely each finished task was documented and averages that score per group. The quality score combines three components per task:

• 40% — completed form fields versus the fields expected for the task's product.
• 30% — at least one photo attached.
• 30% — a signature captured.

A task with every expected field filled, a photo, and a signature scores 100. The report returns the average score per group along with supporting counts (tasks with photos, tasks with signature, total completed versus expected form fields), so you can see which component is pulling a score down. Choose how rows are grouped with group_by (defaults to provider).

---

Request

Request Headers

Every request to a protected endpoint requires these headers:

Header	Required	Description
Authorization	Yes	Bearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-Key	Yes	Company integration key provided during onboarding. Format: gtk_xxx...
tenant	Yes	Your assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-Type	Conditional	application/json — required for POST and PUT requests

Query Parameters

Parameter	Type	Required	Default	Description
startdate	string	Yes	—	ISO 8601 start date-time (e.g. 2026-03-01T00:00:00).
enddate	string	Yes	—	ISO 8601 end date-time. Max range 92 days from startdate.
group_by	string	No	provider	How rows are grouped. One of: provider, device, driver, cause, subcause, service_type, product, origin, shift, end_code, comm_media, route, country, department, city, zone, client, telephonist, operator, resource_type, date, month, weekday, hour.
devices	string	No	—	Comma-separated device IDs. Max 500.
drivers	string	No	—	Comma-separated driver IDs. Max 500.
providers	string	No	—	Comma-separated provider IDs. Max 100.
service_types	string	No	—	Comma-separated service type IDs. Max 100.
causes	string	No	—	Comma-separated cause IDs. Max 100.
subcauses	string	No	—	Comma-separated subcause IDs. Max 100.
statuses	string	No	—	Comma-separated task status codes. Max 100.
device_groups	string	No	All	Comma-separated device type IDs (the device_group catalog from Fleet / Devices). Filters tasks to devices of those types; combines with devices as an intersection. Max 100
origins	string	No	—	Comma-separated origin IDs. Max 100.
route_ids	string	No	—	Comma-separated route IDs. Max 100.
operators	string	No	—	Comma-separated operator IDs. Max 100.
client_id	string	No	—	Single client ID.
account_id	string	No	—	Single account ID.
shift_id	string	No	—	Single shift ID.
limit	integer	No	25	Number of records per page (1–100).
offset	integer	No	0	Number of records to skip for pagination.

How device_groups combines with devices

device_groups is expanded to every device of those types, and if you also send devices, only the devices present in both lists are kept. If that intersection is empty the report returns no rows.

---

Code Examples

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/reports/gt/quality-score?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=driver&limit=25"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/gt/quality-score?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=driver&limit=25`,
  {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      'tenant': TENANT,
    },
  }
);
const data = await res.json();

Python

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/gt/quality-score",
    headers={"Authorization": f"Bearer {TOKEN}", "X-API-Key": APIKEY, "tenant": TENANT},
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-15T23:59:59",
        "group_by": "driver",
        "limit": 25,
    },
)
data = response.json()

---

Response

Response Fields

Field	Type	Description
group_label	string	Display name of the group (e.g. driver, device, provider).
group_id	string | null	Internal ID of the group, or null when not resolvable.
total	number	Total finished tasks in the group.
score_promedio	number	Average quality score (0–100) across the group's tasks.
con_fotos	number	Tasks that have at least one photo attached.
con_firma	number	Tasks that have a signature captured.
oav_completos_total	number	Total completed form fields across the group.
oav_esperados_total	number	Total form fields expected for the group's tasks.

Example Response

{
  "success": true,
  "data": [
    {
      "group_label": "Carlos Martinez",
      "group_id": "10293",
      "total": 120,
      "score_promedio": 87.34,
      "con_fotos": 112,
      "con_firma": 98,
      "oav_completos_total": 540,
      "oav_esperados_total": 600
    }
  ],
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

---

Errors

Code	HTTP	Description
VALIDATION_ERROR	400	Invalid params: missing dates, range > 92 days, invalid enum values.
UNAUTHORIZED	401	Missing, invalid, or expired tenant / Authorization / X-API-Key
FORBIDDEN	403	User lacks required permission.
RATE_LIMITED	429	Exceeded 10 req/min.
INTERNAL_ERROR	500	Unexpected server error.

---

Related

• Time-window Compliance Report
• Revisits Report
• Advanced Forms Report
• Pagination