API reference

GET /partner-api/v1/me

Your partner account

Entitlement (active, restricted …), capabilities, limits (credit limit, rate limits, page size), the plans with your current price (keys with rate_card.read; other keys get price null), and the key making the request. Answers while the account is restricted so your integration can explain refused charge-creating calls.

Key: management key

GET /partner-api/v1/openapi.json

This OpenAPI document

Public, no authentication.

Key: none (public)

GET /partner-api/v1/ping

Check a management key

Who am I: the partner, mode, scopes and fleet scope of the key. Works even when the account is not active.

Key: management key

GET /partner-api/v1/customers

List customers

Newest first. A key limited to fleets sees a customer only when one of its fleets is in scope.

Key: management key · Scope: customers.read

POST /partner-api/v1/customers

Create a customer

external_reference is unique per partner and mode (case-sensitive): a second customer with the same reference answers 409 CONFLICT with details.field = "external_reference", details.reason = "duplicate_external_reference" and, when your key can see it, details.customer (the existing cus_ id). Resolve existing customers with GET /customers?external_reference=… before creating.

Key: management key · Scope: customers.write · Idempotency-Key required

Request body CustomerCreateRequest

{
    "name": "Acme Deliveries Ltd",
    "external_reference": "C1042",
    "contact_name": "Sam Patel",
    "contact_email": "[email protected]"
}

{
    "object": "customer",
    "id": "cus_89ABCDEFGHJKLMNPQRSTUVWX",
    "name": "Acme Deliveries Ltd",
    "external_reference": "C1042",
    "contact": {
        "name": "Sam Patel",
        "email": "[email protected]",
        "phone": null
    },
    "notes": null,
    "is_self": false,
    "status": "active",
    "livemode": true,
    "created_at": "2026-10-01T09:00:00Z",
    "updated_at": "2026-10-01T09:00:00Z",
    "closed_at": null
}

GET /partner-api/v1/customers/{id}

Retrieve a customer

Key: management key · Scope: customers.read

{
    "object": "customer",
    "id": "cus_89ABCDEFGHJKLMNPQRSTUVWX",
    "name": "Acme Deliveries Ltd",
    "external_reference": "C1042",
    "contact": {
        "name": "Sam Patel",
        "email": "[email protected]",
        "phone": null
    },
    "notes": null,
    "is_self": false,
    "status": "active",
    "livemode": true,
    "created_at": "2026-10-01T09:00:00Z",
    "updated_at": "2026-10-01T09:00:00Z",
    "closed_at": null
}

PATCH /partner-api/v1/customers/{id}

Update a customer

Name, reference, contact details and notes. Customers are never deleted through the API.

Key: management key · Scope: customers.write · Idempotency-Key required

Request body CustomerUpdateRequest

{
    "contact_phone": "+44 1473 000000"
}

GET /partner-api/v1/fleets

List fleets

Key: management key · Scope: fleets.read

POST /partner-api/v1/fleets

Create a fleet

Creates the fleet and starts provisioning it on the tracking platform at once (provisioning.operation). The fleet becomes ready within seconds (event fleet.ready; customer.ready for a customer's first fleet). Activations requested earlier wait for it. A fleet created by a key limited to fleets is added to that key. external_reference is unique per partner and mode: a duplicate answers 409 CONFLICT with details.reason = "duplicate_external_reference" and, when your key can see it, details.fleet.

Key: management key · Scope: fleets.write · Idempotency-Key required

Request body FleetCreateRequest

{
    "customer_id": "cus_89ABCDEFGHJKLMNPQRSTUVWX",
    "name": "Acme vans",
    "plan_code": "pro",
    "external_reference": "C1042-main"
}

{
    "object": "fleet",
    "id": "flt_FGHJKLMNPQRSTUVWXYZabcde",
    "customer": "cus_89ABCDEFGHJKLMNPQRSTUVWX",
    "name": "Acme vans",
    "external_reference": "C1042-main",
    "plan_code": "pro",
    "status": "provisioning",
    "timezone": "Europe/London",
    "hosted_access_enabled": false,
    "livemode": true,
    "created_at": "2026-10-01T09:01:00Z",
    "updated_at": "2026-10-01T09:01:00Z",
    "closed_at": null,
    "provisioning": {
        "operation": "op_NPQRSTUVWXYZabcdefghijkm",
        "status": "queued"
    }
}

GET /partner-api/v1/fleets/{id}

Retrieve a fleet

Key: management key · Scope: fleets.read

PATCH /partner-api/v1/fleets/{id}

Update a fleet

Name, external_reference and timezone only. Change the plan with POST /fleets/{id}/plan-changes; no upstream account fields can be set.

Key: management key · Scope: fleets.write · Idempotency-Key required

Request body FleetUpdateRequest

{
    "name": "Acme vans (north)"
}

POST /partner-api/v1/fleets/{id}/invitations

Invite a hosted tracking user

Only when hosted access is enabled for your account (otherwise 403 PARTNER_ACCESS_REQUIRED with details.feature = "hosted_access"). The invitee receives a Fleetalyse-branded email with a one-time link to their sign-in details (72 hours). Test mode never creates real logins or sends invitations to anyone but you.

Key: management key · Scope: fleets.write · Idempotency-Key required

Request body FleetInvitationRequest

{
    "email": "[email protected]",
    "name": "Acme dispatch"
}

GET /partner-api/v1/device-claims

List device claims

Key: management key · Scope: devices.read

POST /partner-api/v1/device-claims

Claim a device

For supplied or imported hardware Fleetalyse must verify. Evidence is required — knowing an IMEI is not enough: give evidence_text or evidence_order_ref, otherwise 422 INVALID_REQUEST with details.field = "evidence_text". A unit allocated to you by a Fleetalyse hardware order is approved at once (status auto_approved). The decision reason never names another owner.

Key: management key · Scope: devices.write · Idempotency-Key required

Request body DeviceClaimCreateRequest

{
    "identifier": "356307042441013",
    "manufacturer": "Teltonika",
    "model": "FMC130",
    "evidence_order_ref": "FA-100231"
}

GET /partner-api/v1/device-claims/{id}

Retrieve a device claim

Key: management key · Scope: devices.read

GET /partner-api/v1/devices

List devices

Newest first. Keys limited to fleets never see devices without a fleet.

Key: management key · Scope: devices.read

POST /partner-api/v1/devices

Register a device

Registers a tracker you supply (manufacturer and model from Supported devices). verification.decision tells you whether it is usable at once (verified), being checked (verification_pending) or reviewed by Fleetalyse (review). Refusals are 409 CONFLICT with details.reason: "already_registered" (you already registered it; details.device is your dev_ id), "not_eligible" (held elsewhere — the owner is never named; claim it with evidence if it is yours) or "sim_in_use" (details.field = "sim_iccid": the SIM is fitted to another registered device). Also creates the vehicle (veh_) used by the Tracking API.

Key: management key · Scope: devices.write · Idempotency-Key required

Request body DeviceRegisterRequest

{
    "identifier_type": "imei",
    "identifier": "356307042441013",
    "manufacturer": "Teltonika",
    "model": "FMC130",
    "fleet_id": "flt_FGHJKLMNPQRSTUVWXYZabcde",
    "label": "Van 12",
    "registration_plate": "AB12 CDE"
}

GET /partner-api/v1/devices/{id}

Retrieve a device

Hardware identity, ownership, fleet, vehicle, SIM, connectivity and the current service — separate fields, never merged.

Key: management key · Scope: devices.read

PATCH /partner-api/v1/devices/{id}

Update a device's vehicle identity

Key: management key · Scope: devices.write · Idempotency-Key required

Request body DeviceUpdateRequest

{
    "label": "Van 12",
    "registration_plate": "AB12 CDE"
}

POST /partner-api/v1/activations

Activate a tracking service

Activates the fleet's plan on a verified device you own. Asynchronous: 202 means accepted for processing — not that the tracker is active or that anything was charged. Charging starts at the confirmed activation (effective_at). The price comes from your rate card; requests never carry prices or payer ids. Checks your credit exposure (402 BILLING_RESTRICTED / CREDIT_LIMIT_REACHED / PAYMENT_ACTION_REQUIRED). Answers 202 with the operation; 200 when an identical earlier request already finished (created = false). Poll GET /operations/{id} or wait for the webhook.

Key: management key · Scope: services.activate · Idempotency-Key required · Creates charges

Request body ActivationRequest

{
    "external_order_reference": "ORDER-1042",
    "external_request_id": "ORDER-1042-line-1-activate",
    "customer_id": "cus_89ABCDEFGHJKLMNPQRSTUVWX",
    "fleet_id": "flt_FGHJKLMNPQRSTUVWXYZabcde",
    "device_id": "dev_jkmnopqrstuvwxyz12345678",
    "plan_code": "pro",
    "activate_when": "as_soon_as_ready"
}

{
    "object": "operation",
    "operation_id": "op_VWXYZabcdefghijkmnopqrst",
    "type": "activation",
    "status": "queued",
    "service_id": "svc_cdefghijkmnopqrstuvwxyz1",
    "device_id": "dev_jkmnopqrstuvwxyz12345678",
    "fleet_id": "flt_FGHJKLMNPQRSTUVWXYZabcde",
    "customer_id": "cus_89ABCDEFGHJKLMNPQRSTUVWX",
    "service_status": "activation_pending",
    "billing_status": "not_started",
    "effective_at": null,
    "scheduled_for": null,
    "external_order_reference": "ORDER-1042",
    "external_request_id": "ORDER-1042-line-1-activate",
    "attempts": 0,
    "error": null,
    "result": null,
    "created_at": "2026-10-01T09:29:58Z",
    "updated_at": "2026-10-01T09:29:58Z",
    "completed_at": null,
    "request_id": "req_TUVWXYZabcdefghijkmnopqr",
    "billing": {
        "state": "not_started",
        "policy": "confirmed_active_time",
        "rate_card_version": "rc_4kQ7mZp2XvT9bN3wR8sH6yJd",
        "plan_code": "pro",
        "full_month_price": {
            "amount_minor": 400,
            "currency": "GBP",
            "tax_mode": "exclusive"
        }
    },
    "created": true
}

POST /partner-api/v1/fleets/{id}/plan-changes

Change the plan of a fleet

Changes the plan of every service in the fleet. expected_affected_services must equal the current count (the portal preview shows it); otherwise 409 CONFLICT. Answers 202 with the operation; 200 when an identical earlier request already finished (created = false). Poll GET /operations/{id} or wait for the webhook.

Key: management key · Scope: services.activate · Idempotency-Key required · Creates charges

Request body FleetPlanChangeRequest

{
    "plan_code": "pro",
    "expected_affected_services": 12
}

GET /partner-api/v1/services

List services

Service state, billing state and any pending change, newest first.

Key: management key · Scope: devices.read

GET /partner-api/v1/services/{id}

Retrieve a service

Key: management key · Scope: devices.read

POST /partner-api/v1/services/{id}/deactivations

Deactivate a service

Immediate, or scheduled with at. Charging stops at the confirmed deactivation (effective_at of service.deactivation_completed); if confirmation takes longer than the credit threshold after acceptance, the delay is credited. Works while the account is restricted and has its own rate limit (600 a minute per key), separate from the write limit. Deactivating never deletes the device, fleet or history. Answers 202 with the operation; 200 when an identical earlier request already finished (created = false). Poll GET /operations/{id} or wait for the webhook.

Key: management key · Scope: services.deactivate · Idempotency-Key required · Available while restricted

Request body DeactivationRequest

{
    "effective": "immediate",
    "external_request_id": "ORDER-1042-cancel"
}

POST /partner-api/v1/services/{id}/plan-changes

Change the plan of a service

Plans are a fleet setting: accepted only when this is the only non-inactive service in its fleet (otherwise 422 PLAN_NOT_AVAILABLE with details.fleet_active_services). The new price applies from the confirmed change. Answers 202 with the operation; 200 when an identical earlier request already finished (created = false). Poll GET /operations/{id} or wait for the webhook.

Key: management key · Scope: services.activate · Idempotency-Key required · Creates charges

Request body PlanChangeRequest

{
    "plan_code": "basic"
}

POST /partner-api/v1/services/{id}/reactivations

Reactivate a service

Starts a new charging period for an inactive service (no new access fee). Subject to the daily toggle limit (409 CONFLICT, details.reason = "toggle_limit") and your credit exposure. Answers 202 with the operation; 200 when an identical earlier request already finished (created = false). Poll GET /operations/{id} or wait for the webhook.

Key: management key · Scope: services.activate · Idempotency-Key required · Creates charges

Request body ReactivationRequest

GET /partner-api/v1/operations

List operations

Key: management key · Scope: operations.read

GET /partner-api/v1/operations/{id}

Poll an operation

Status, effective_at and neutral step statuses. Poll with backoff (2, 5, 15, 30 s, then every minute) or use webhooks. requires_attention will not retry by itself.

Key: management key · Scope: operations.read

{
    "object": "operation",
    "operation_id": "op_VWXYZabcdefghijkmnopqrst",
    "type": "activation",
    "status": "completed",
    "service_id": "svc_cdefghijkmnopqrstuvwxyz1",
    "device_id": "dev_jkmnopqrstuvwxyz12345678",
    "fleet_id": "flt_FGHJKLMNPQRSTUVWXYZabcde",
    "customer_id": "cus_89ABCDEFGHJKLMNPQRSTUVWX",
    "service_status": "active",
    "billing_status": "accruing",
    "effective_at": "2026-10-01T09:30:00Z",
    "scheduled_for": null,
    "external_order_reference": "ORDER-1042",
    "external_request_id": "ORDER-1042-line-1-activate",
    "attempts": 1,
    "error": null,
    "result": null,
    "created_at": "2026-10-01T09:29:58Z",
    "updated_at": "2026-10-01T09:30:01Z",
    "completed_at": "2026-10-01T09:30:01Z",
    "request_id": "req_abcdefghijkmnopqrstuvwxy",
    "steps": [
        {
            "step": "service_start",
            "label": "Tracking service started",
            "status": "completed",
            "started_at": "2026-10-01T09:30:00Z",
            "finished_at": "2026-10-01T09:30:00Z"
        },
        {
            "step": "confirmation",
            "label": "Confirmed with the tracking platform",
            "status": "completed",
            "started_at": "2026-10-01T09:30:01Z",
            "finished_at": "2026-10-01T09:30:01Z"
        }
    ]
}

POST /partner-api/v1/operations/{id}/cancellations

Withdraw a scheduled change

Cancels a scheduled or not-yet-started change (for example a scheduled deactivation). A change already running answers 409 CONFLICT. Emits operation.cancelled.

Key: management key · Scope: operations.read · Idempotency-Key required · Available while restricted

Request body OperationCancelRequest

GET /partner-api/v1/billing/invoices

List invoices

Usage, hardware and access-fee invoices. Readable while the account is restricted; limited separately from other reads (600 a minute per key; document links 120 a minute per partner). Needs a key that sees every fleet (fleet-limited keys get 403 or 404).

Key: management key · Scope: billing.read

GET /partner-api/v1/billing/invoices/{id}

Retrieve an invoice

Key: management key · Scope: billing.read

GET /partner-api/v1/billing/invoices/{id}/document

Invoice document link

A fresh, short-lived link to the invoice PDF or payment page, fetched at request time (links are never stored in other responses). 409 CONFLICT for simulated (test-mode) or not yet finalised invoices.

Key: management key · Scope: billing.read

GET /partner-api/v1/billing/statements

List statements

Final monthly statements (frozen and later), newest period first. Needs a key that sees every fleet (fleet-limited keys get 403 or 404).

Key: management key · Scope: billing.read

GET /partner-api/v1/billing/statements/{id}

Retrieve a statement

With summary lines per plan and tax basis, and adjustments.

Key: management key · Scope: billing.read

GET /partner-api/v1/billing/statements/{id}/lines

Per-device statement lines

One line per device and plan: billable seconds, the exact numerator/denominator, price segments, delay credits and your external_order_reference — reproducible to the penny.

Key: management key · Scope: billing.read

GET /partner-api/v1/billing/summary

Billing summary

Month-to-date estimate, credit limit, exposure and headroom, unpaid invoices and restriction state. Needs a key that sees every fleet (fleet-limited keys get 403 or 404).

Key: management key · Scope: billing.read

GET /partner-api/v1/billing/usage

Usage by customer

The current month is an estimate until it closes; a closed period returns its statement's usage. include=devices lists estimated device lines of the current month.

Key: management key · Scope: billing.read

GET /partner-api/v1/rate-card

Your rate card

Prices in force (net, per device per full calendar month), announced future versions and any assignment waiting for your acceptance. Never internal costs.

Key: management key · Scope: rate_card.read

GET /partner-api/v1/hardware/catalogue

Hardware catalogue

Products with your trade prices, stock, dispatch estimates and delivery options, plus your approved delivery addresses.

Key: management key · Scope: hardware.read