Quickstart

Authenticate, query your fleet, and create a workflow instance — all in under 5 minutes.

Prerequisites

• API credentials: email, password, and apiKey provided during onboarding
• Your tenant hostname (e.g., yourcompany.geotareas.com)

Step 1 — Authenticate

Obtain a JWT token by calling the login endpoint:

cURL

curl -s -X POST \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@yourcompany.com","password":"your_password"}' \
  "https://$TENANT/apidev/v1/login"

JavaScript

const TENANT = 'yourcompany.geotareas.com';
const API_KEY = 'gtk_prod_xxxxxxxxxxxx'; // from onboarding

const loginRes = await fetch(`https://${TENANT}/apidev/v1/login`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'tenant': TENANT,
  },
  body: JSON.stringify({
    email: 'dev@yourcompany.com',
    password: 'your_password',
  }),
});

const { data } = await loginRes.json();
const token = data.authorization;

Python

import requests

TENANT = "yourcompany.geotareas.com"
API_KEY = "gtk_prod_xxxxxxxxxxxx"  # from onboarding

login = requests.post(
    f"https://{TENANT}/apidev/v1/login",
    headers={"tenant": TENANT, "Content-Type": "application/json"},
    json={"email": "dev@yourcompany.com", "password": "your_password"},
)

token = login.json()["data"]["authorization"]

PHP

$tenant = 'yourcompany.geotareas.com';
$apiKey = 'gtk_prod_xxxxxxxxxxxx'; // from onboarding

$ch = curl_init("https://{$tenant}/apidev/v1/login");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["tenant: {$tenant}", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(['email' => 'dev@yourcompany.com', 'password' => 'your_password']),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$token = $response['data']['authorization'];

C#

using System.Net.Http;
using System.Text;
using System.Text.Json;

var tenant = "yourcompany.geotareas.com";
var apiKey = "gtk_prod_xxxxxxxxxxxx"; // from onboarding

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("tenant", tenant);

var payload = JsonSerializer.Serialize(new {
    email = "dev@yourcompany.com",
    password = "your_password"
});

var loginResponse = await client.PostAsync(
    $"https://{tenant}/apidev/v1/login",
    new StringContent(payload, Encoding.UTF8, "application/json"));

var loginJson = JsonDocument.Parse(await loginResponse.Content.ReadAsStringAsync());
var token = loginJson.RootElement.GetProperty("data").GetProperty("authorization").GetString();

Response:

{
  "success": true,
  "data": { "authorization": "eyJhbGciOi..." },
  "meta": {}
}

tip

The token is valid for 1 hour. There is no refresh endpoint — simply re-authenticate when it expires. The API Key (gtk_prod_...) is permanent and was provided during onboarding — you'll use it alongside the token in every request from here on.

Step 2 — Query your fleet

Use the token + API key to call any protected endpoint. Every request requires 3 headers:

Authorization: Bearer <token>
X-API-Key: <your_api_key>
tenant: <your_tenant>

cURL

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/fleet/devices?limit=5&status=A"

JavaScript

const headers = {
  'Authorization': `Bearer ${token}`,
  'X-API-Key': API_KEY,
  'tenant': TENANT,
};

const res = await fetch(
  `https://${TENANT}/apidev/v1/fleet/devices?limit=5&status=A`,
  { headers }
);
const devices = await res.json();
console.log(devices.data);

Python

headers = {
    "Authorization": f"Bearer {token}",
    "X-API-Key": API_KEY,
    "tenant": TENANT,
}

devices = requests.get(
    f"https://{TENANT}/apidev/v1/fleet/devices",
    headers=headers,
    params={"limit": 5, "status": "A"},
)
print(devices.json()["data"])

PHP

$ch = curl_init("https://{$tenant}/apidev/v1/fleet/devices?limit=5&status=A");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$token}",
        "X-API-Key: {$apiKey}",
        "tenant: {$tenant}",
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$devices = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($devices['data']);

C#

client.DefaultRequestHeaders.Clear();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
client.DefaultRequestHeaders.Add("X-API-Key", apiKey);
client.DefaultRequestHeaders.Add("tenant", tenant);

var devicesResponse = await client.GetStringAsync(
    $"https://{tenant}/apidev/v1/fleet/devices?limit=5&status=A");
var devices = JsonDocument.Parse(devicesResponse);

Response:

{
  "success": true,
  "data": [
    {
      "id": "104820579301",
      "name": "Truck-42",
      "plate": "ABC-1234",
      "status": "A",
      "lastPosition": {
        "lat": -34.6037,
        "lng": -58.3816,
        "speed": 45,
        "timestamp": "2026-04-04T14:23:00"
      }
    }
  ],
  "meta": { "total": 128, "limit": 5, "offset": 0 }
}

Step 3 — Create a workflow instance

Now try a write operation — start a workflow instance tied to an entity:

cURL

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{"definitionId":"wf_maintenance","entityId":"104820579301"}' \
  "https://$TENANT/apidev/v1/workflow/instances"

JavaScript

const instance = await fetch(
  `https://${TENANT}/apidev/v1/workflow/instances`,
  {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      definitionId: 'wf_maintenance',
      entityId: '104820579301',
    }),
  }
);
const result = await instance.json();
console.log(result.data);

Python

instance = requests.post(
    f"https://{TENANT}/apidev/v1/workflow/instances",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "definitionId": "wf_maintenance",
        "entityId": "104820579301",
    },
)
print(instance.json()["data"])

PHP

$ch = curl_init("https://{$tenant}/apidev/v1/workflow/instances");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$token}",
        "X-API-Key: {$apiKey}",
        "tenant: {$tenant}",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'definitionId' => 'wf_maintenance',
        'entityId' => '104820579301',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$instance = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($instance['data']);

C#

var body = JsonSerializer.Serialize(new {
    definitionId = "wf_maintenance",
    entityId = "104820579301"
});

var createResponse = await client.PostAsync(
    $"https://{tenant}/apidev/v1/workflow/instances",
    new StringContent(body, Encoding.UTF8, "application/json"));

var instanceJson = JsonDocument.Parse(await createResponse.Content.ReadAsStringAsync());

Response:

{
  "success": true,
  "data": {
    "instanceId": "inst_7x4k9m",
    "definitionId": "wf_maintenance",
    "entityId": "104820579301",
    "status": "RUNNING",
    "createdAt": "2026-04-04T14:25:12"
  },
  "meta": {}
}

Step 4 — Explore the full API

You've authenticated, read data, and performed a write operation. Here's what else you can do across all 10 domains:

Domain	Try this	Endpoint
Fleet	List vehicles with GPS position	GET /fleet/devices
Fleet	List drivers and assignments	GET /fleet/drivers
Telemetry	Ingest GPS points from devices	POST /telemetry
Reports	Kilometers traveled in a date range	GET /reports/avl/kilometers
Reports	Task productivity by team	GET /reports/gt/productivity
Accounts	Search customer accounts	GET /accounts
Clients	Create a new client record	POST /clients
Workflow	Query instance timeline	GET /workflow/instances/{id}/timeline
Kanban	List boards in a workspace	GET /kanban/workspaces/{id}/boards
Kanban	Create and move cards	POST /kanban/cards
Billing	List invoices with filters	GET /billing/invoices
Billing	Export invoices to XLSX	GET /billing/invoices/export
Portal	Supplier invoice declarations	POST /portal/invoices/declare
Portal	Tolerance validation results	GET /portal/tolerance

All paths are prefixed with /apidev/v1/.

Testing with Postman

A ready-to-use Postman collection is available. See the Postman Collection page for import instructions and the full list of pre-built requests.

What's next

By use case:

• Fleet tracking & IoT — Fleet & Telemetry, AVL Reports
• Task management — Workflow, Kanban
• Back-office integration — Billing, Accounts
• Supplier operations — Portal Proveedores

Fundamentals:

• Authentication — Full dual-auth model and troubleshooting
• Rate Limits — Understand limits and avoid 429 errors
• Error Handling — Standard error envelope and codes
• API Coverage — Complete endpoint inventory (102 endpoints)