UMAX Fleet API v1

Programmatic access for fleet operators: account details, transactions, and the full LOVES / TA / Petro station catalog. Every request is authenticated, scoped to one customer, and rate-limited.

Base URL: https://api.umaxfleet.com/api/v1
All responses are application/json · timestamps are ISO-8601 UTC · amounts are decimal strings.

Contents Authentication· Rate limits· Errors· POST /auth· GET /account-details· GET /transactions· GET /transactions/{id}· GET /locations· GET /locations/{id}

Authentication

Every key pair has a public key_id (prefix umaxk_) and a secret. Two ways to authenticate:

1. Bearer token (recommended)

Exchange the pair once for a short-lived bearer token, then send the token on every subsequent call.

curl -X POST https://api.umaxfleet.com/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"key_id":"umaxk_live_abc...","secret":"sk_live_def..."}'

# Response
{ "ok": true, "access_token": "...", "expires_in": 3600 }

# Then on every request
curl https://api.umaxfleet.com/api/v1/account-details \
  -H "Authorization: Bearer <access_token>"

2. HTTP Basic (one-shot calls)

Use the key_id as username and the secret as password. Convenient from cURL or Postman; slower than bearer for repeated calls.

curl https://api.umaxfleet.com/api/v1/locations \
  -u "umaxk_live_abc...:sk_live_def..."

Treat the secret like a password. If it leaks, revoke and re-issue from Admin » API keys. The full secret is shown only once at creation time.

Rate limits

Each key has a per-minute budget (default 60 req/min). When the budget is exceeded the API returns 429 Too Many Requests. Limit windows reset every 60 seconds.

Errors

Failed requests return a JSON body with ok: false and a short message. HTTP status codes are conventional.

{ "ok": false, "error": "invalid_credentials", "message": "Unknown key_id or wrong secret." }

HTTP	error	meaning
`400`	`bad_request`	Missing or malformed parameters.
`401`	`unauthenticated`	Missing or invalid bearer / basic credentials.
`403`	`scope_denied`	Key is valid but lacks the required scope.
`404`	`not_found`	Resource does not exist for this customer.
`429`	`rate_limited`	Slow down. See `Retry-After` header.
`500`	`server_error`	Something is wrong on our side. Please retry.

POST /api/v1/auth

POST https://api.umaxfleet.com/api/v1/auth

Exchanges a key pair for a bearer token. Response is cached server-side for the duration of expires_in.

Request body

field	type	required	description
`key_id`	string	yes	Public key identifier, starts with `umaxk_`.
`secret`	string	yes	The secret shown once at creation time.

Response

{
  "ok": true,
  "access_token": "eyJ...",
  "token_type":   "Bearer",
  "expires_in":   3600
}

GET /api/v1/account-details scope: read

GET https://api.umaxfleet.com/api/v1/account-details

Returns the customer's profile, contact info, and rolling 30-day spend / volume totals.

Response

{
  "ok": true,
  "customer": {
    "id":      "61dd6c85-...",
    "name":    "ABC Trucking Inc.",
    "code":    "ABC",
    "active":  true
  },
  "totals_30d": {
    "transactions": 142,
    "gallons":      "11842.500",
    "amount":       "47536.20"
  }
}

Note: the per-gallon deduction the customer is billed at is intentionally not exposed. Customers only see the price they pay; the underlying margin is an internal detail.

GET /api/v1/transactions scope: read

GET https://api.umaxfleet.com/api/v1/transactions

Paginated list of the caller's fuel transactions. Default sort: most recent first.

Query parameters

name	type	default	description
`page`	int	1	1-based page index.
`limit`	int	50	Page size, 1-200.
`from`	date	-	ISO date inclusive, e.g. `2026-01-01`.
`to`	date	-	ISO date inclusive.
`status`	string	-	One of `completed`, `pending`, `failed`.
`search`	string	-	Matches station name, driver name, or card last-4.

Response

{
  "ok": true,
  "data": {
    "page": 1,
    "limit": 50,
    "total": 142,
    "pages": 3,
    "items": [
      {
        "id":               "9b6e426b-...",
        "transaction_id":   "efs-1534955126",
        "transaction_at":   "2026-05-23T20:03:00+00:00",
        "status":           "completed",
        "product":          "Diesel",
        "gallons":          120.15,
        "price_per_gallon": 4.8302,
        "amount":           580.3525,
        "station": {
          "id":    "01bb3d7e-...",
          "name":  "LOVES #791 TRAVEL STOP",
          "loc":   "791",
          "city":  "HOLLADAY",
          "state": "TN"
        },
        "driver": { "id": "9f88da5f-...", "name": "Ali Adnan Khan", "truck_id": null },
        "card":   { "last4": "7839" },
        "def": {
          "gallons": 5.91,
          "amount":  27.72,
          "category":"DEF"
        }
      }
    ]
  }
}

GET /api/v1/transactions/{id} scope: read

GET https://api.umaxfleet.com/api/v1/transactions/{id}

Single transaction with the full breakdown: station address, driver email, card type, source, and timestamps.

GET /api/v1/locations scope: read

GET https://api.umaxfleet.com/api/v1/locations

Catalog of fuel stations available to the caller. Filter by brand, state, or name.

Query parameters

name	type	default	description
`page`	int	1	1-based page index.
`limit`	int	100	Page size, 1-500.
`brand`	string	-	e.g. `loves`, `ta`, `petro`.
`state`	string	-	USPS 2-letter code, e.g. `TX`.
`search`	string	-	Matches name, city, or loc number.

Response

{
  "ok": true,
  "data": {
    "page": 1,
    "limit": 100,
    "total": 967,
    "pages": 10,
    "items": [
      {
        "id":               "fb61f9df-...",
        "loc_num":          "0701",
        "name":             "Goasis Ashland",
        "brand":            "ta",
        "address":          "715 US 250 East",
        "city":             "ASHLAND",
        "state":            "OH",
        "lat":              40.8566,
        "lng":             -82.2623,
        "price":            3.69,
        "price_updated_at": "2026-05-02T09:40:35+00:00"
      }
    ]
  }
}

GET /api/v1/locations/{id} scope: read

GET https://api.umaxfleet.com/api/v1/locations/{id}

Full details for a single station: amenities, phone, DEF availability, and the latest customer price.

OpenAPI

A machine-readable OpenAPI 3.1 schema is available at https://api.umaxfleet.com/api/docs/openapi.

Questions? Email api@umaxfleet.com.