# Frigolive Developer

> Frigolive Public API v1 — the stable, versioned contract customers use to
> integrate cold chain telemetry and device data into their own products.
> Authentication is OAuth 2.0 client credentials; access tokens last about one
> hour and there is no refresh token. Every request is checked against the token
> scope, the credential account allow-list, and tenant ownership.

- Base URL: https://api.frigolive.nl/api/public/v1
- OpenAPI: https://api.frigolive.nl/api/public/schema.json (also .yaml)
- Content is published in Turkish (/tr) and English (/en); the English tree is listed below.

## Guides

- [Overview](https://developer.frigolive.nl/en/docs): trust boundaries and how the integration works.
- [Integration Journey](https://developer.frigolive.nl/en/docs/getting-started): credential creation to production.
- [Service Identity & Tokens](https://developer.frigolive.nl/en/docs/authentication): client credentials and token lifecycle.
- [Scopes & Isolation](https://developer.frigolive.nl/en/docs/authorization): scopes, account allow-list, tenant ownership.
- [Web, Mobile & BFF](https://developer.frigolive.nl/en/docs/mobile): where the secret may and may not live.
- [Events & Webhooks](https://developer.frigolive.nl/en/docs/webhooks): not part of v1 yet; poll instead.
- [Errors & Resilience](https://developer.frigolive.nl/en/docs/errors): status codes, retries, idempotency, pagination.
- [SDKs & OpenAPI](https://developer.frigolive.nl/en/docs/sdk): official Python, Node.js, and .NET clients.
- [Changelog](https://developer.frigolive.nl/en/changelog): contract and documentation changes.

## API reference

### Authentication — https://developer.frigolive.nl/en/api-reference/authentication

Obtain short-lived, scope-restricted access tokens with client credentials.

- `POST /api/public/v1/oauth/token/` — Get a service access token. Exchanges the client ID and the once-shown client secret for a JWT valid for at most one hour. (scope: public)

### Accounts — https://developer.frigolive.nl/en/api-reference/accounts

Work with the companies assigned to the integration and customer-managed profile fields.

- `GET /api/public/v1/accounts/` — List assigned accounts. Returns the active real customer accounts on the credential allow-list. (scope: accounts:read)
- `GET /api/public/v1/accounts/{account_id}/` — Get an account profile. Returns the safe profile fields of a customer company on the allow-list. (scope: accounts:read)
- `PATCH /api/public/v1/accounts/{account_id}/` — Update an account profile. Updates customer-managed contact and legal profile fields; it cannot change status or subscription. (scope: accounts:write)

### Locations & Geofences — https://developer.frigolive.nl/en/api-reference/locations

Manage circle and polygon locations plus entry/exit automation.

- `GET /api/public/v1/locations/` — List locations. Returns a page of locations records in the selected account. (scope: locations:read)
- `POST /api/public/v1/locations/` — Create a location. Creates a new location record in the selected customer account. (scope: locations:write)
- `GET /api/public/v1/locations/{location_id}/` — Get location detail. Looks the resource up only inside the selected tenant. (scope: locations:read)
- `PUT /api/public/v1/locations/{location_id}/` — Update a location. Updates writable fields against an explicit allow-list contract and rejects unknown fields. (scope: locations:write)
- `PATCH /api/public/v1/locations/{location_id}/` — Partially update a location. Updates only the writable fields you send; the rest stay unchanged. (scope: locations:write)
- `DELETE /api/public/v1/locations/{location_id}/` — Delete a location. Deletes the resource only inside the selected tenant. (scope: locations:write)

### Carriers — https://developer.frigolive.nl/en/api-reference/carriers

Manage the customer's carrier catalogue.

- `GET /api/public/v1/carriers/` — List carriers. Returns a page of carriers records in the selected account. (scope: carriers:read)
- `POST /api/public/v1/carriers/` — Create a carrier. Creates a new carrier record in the selected customer account. (scope: carriers:write)
- `GET /api/public/v1/carriers/{carrier_id}/` — Get carrier detail. Looks the resource up only inside the selected tenant. (scope: carriers:read)
- `PUT /api/public/v1/carriers/{carrier_id}/` — Update a carrier. Updates writable fields against an explicit allow-list contract and rejects unknown fields. (scope: carriers:write)
- `PATCH /api/public/v1/carriers/{carrier_id}/` — Partially update a carrier. Updates only the writable fields you send; the rest stay unchanged. (scope: carriers:write)
- `DELETE /api/public/v1/carriers/{carrier_id}/` — Delete a carrier. Deletes the resource only inside the selected tenant. (scope: carriers:write)

### Receivers — https://developer.frigolive.nl/en/api-reference/receivers

Manage Frigolive receiver and delivery-party records.

- `GET /api/public/v1/receivers/` — List receivers. Returns a page of receivers records in the selected account. (scope: receivers:read)
- `POST /api/public/v1/receivers/` — Create a receiver. Creates a new receiver record in the selected customer account. (scope: receivers:write)
- `GET /api/public/v1/receivers/{receiver_id}/` — Get receiver detail. Looks the resource up only inside the selected tenant. (scope: receivers:read)
- `PUT /api/public/v1/receivers/{receiver_id}/` — Update a receiver. Updates writable fields against an explicit allow-list contract and rejects unknown fields. (scope: receivers:write)
- `PATCH /api/public/v1/receivers/{receiver_id}/` — Partially update a receiver. Updates only the writable fields you send; the rest stay unchanged. (scope: receivers:write)
- `DELETE /api/public/v1/receivers/{receiver_id}/` — Delete a receiver. Deletes the resource only inside the selected tenant. (scope: receivers:write)

### Alert Presets — https://developer.frigolive.nl/en/api-reference/alert-presets

Manage reusable temperature, humidity, light, shock, and battery thresholds.

- `GET /api/public/v1/alert-presets/` — List alert presets. Returns a page of alert presets records in the selected account. (scope: alert-presets:read)
- `POST /api/public/v1/alert-presets/` — Create a alert preset. Creates a new alert preset record in the selected customer account. (scope: alert-presets:write)
- `GET /api/public/v1/alert-presets/{preset_id}/` — Get alert preset detail. Looks the resource up only inside the selected tenant. (scope: alert-presets:read)
- `PUT /api/public/v1/alert-presets/{preset_id}/` — Update a alert preset. Updates writable fields against an explicit allow-list contract and rejects unknown fields. (scope: alert-presets:write)
- `PATCH /api/public/v1/alert-presets/{preset_id}/` — Partially update a alert preset. Updates only the writable fields you send; the rest stay unchanged. (scope: alert-presets:write)
- `DELETE /api/public/v1/alert-presets/{preset_id}/` — Delete a alert preset. Deletes the resource only inside the selected tenant. (scope: alert-presets:write)

### Shipment Templates — https://developer.frigolive.nl/en/api-reference/shipment-templates

Manage frequently used shipment routes as templates.

- `GET /api/public/v1/shipment-templates/` — List shipment templates. Returns a page of shipment templates records in the selected account. (scope: shipment-templates:read)
- `POST /api/public/v1/shipment-templates/` — Create a shipment template. Creates a new shipment template record in the selected customer account. (scope: shipment-templates:write)
- `GET /api/public/v1/shipment-templates/{template_id}/` — Get shipment template detail. Looks the resource up only inside the selected tenant. (scope: shipment-templates:read)
- `PUT /api/public/v1/shipment-templates/{template_id}/` — Update a shipment template. Updates writable fields against an explicit allow-list contract and rejects unknown fields. (scope: shipment-templates:write)
- `PATCH /api/public/v1/shipment-templates/{template_id}/` — Partially update a shipment template. Updates only the writable fields you send; the rest stay unchanged. (scope: shipment-templates:write)
- `DELETE /api/public/v1/shipment-templates/{template_id}/` — Delete a shipment template. Deletes the resource only inside the selected tenant. (scope: shipment-templates:write)

### Devices — https://developer.frigolive.nl/en/api-reference/devices

Use the safe device view, status, customer settings, and maintenance history.

- `GET /api/public/v1/devices/` — List devices. Returns the safe operational view of approved, non-deleted devices. (scope: devices:read)
- `GET /api/public/v1/devices/{device_id}/` — Get device detail. Fetches the device only inside the selected tenant. (scope: devices:read)
- `PATCH /api/public/v1/devices/{device_id}/label/` — Change the device label. Changes only the customer-visible label, using the narrowest write scope. (scope: devices:read + devices:label:write)
- `PATCH /api/public/v1/devices/{device_id}/settings/` — Update customer device settings. Updates the measurement/transmission interval, sensor usage, thresholds, and alert preset against an allow-list. (scope: devices:read + devices:settings:write)
- `GET /api/public/v1/devices/{device_id}/status/` — Get device status. Returns a lightweight status view with connectivity, battery, and last location. (scope: devices:read)
- `GET /api/public/v1/devices/{device_id}/alarms/` — Get device alarms. Returns only alarms from the device's current physical lifecycle. (scope: alarms:read)
- `GET /api/public/v1/devices/{device_id}/maintenance/` — Get maintenance and calibration history. Returns maintenance, fault, repair, and calibration records without exposing cost fields. (scope: maintenance:read)

### Telemetry — https://developer.frigolive.nl/en/api-reference/telemetry

Read temperature, humidity, light, shock, battery, and location measurements.

- `GET /api/public/v1/devices/{device_id}/telemetry/` — Get device telemetry. Returns tenant-scoped sensor measurements within the configured maximum day range. (scope: telemetry:read)

### Shipments — https://developer.frigolive.nl/en/api-reference/shipments

Create, track, share, and complete multi-device shipments.

- `GET /api/public/v1/shipments/` — List shipments. Lists multi-device shipments, filtered by active/completed status and search. (scope: shipments:read)
- `POST /api/public/v1/shipments/create/` — Create a shipment. Creates a new, immediately active shipment with up to five eligible devices from the same tenant. (scope: shipments:write)
- `GET /api/public/v1/shipments/{shipment_id}/` — Get shipment detail. Returns the route, devices, active transport leg, and AIS position where available, under a safe contract. (scope: shipments:read)
- `PUT /api/public/v1/shipments/{shipment_id}/` — Update an active shipment. Updates customer-managed fields: route, planning, receiver, carrier, and up to five devices. (scope: shipments:write)
- `DELETE /api/public/v1/shipments/{shipment_id}/` — Delete an active shipment. Deletes only an incomplete shipment; completed history is left untouched. (scope: shipments:write)
- `POST /api/public/v1/shipments/{shipment_id}/complete/` — Complete a shipment. Completes the shipment atomically and freezes the telemetry window at the completion moment. (scope: shipments:complete)
- `GET /api/public/v1/shipments/{shipment_id}/share/` — Get the sharing status. Returns whether sharing is enabled plus the safe URL, expiry, and view counts — never the raw share token. (scope: shipments:read + shipments:share)
- `PUT /api/public/v1/shipments/{shipment_id}/share/` — Create or refresh a share link. Creates or refreshes the single Frigolive share record with an expiry and a view limit. (scope: shipments:share)
- `DELETE /api/public/v1/shipments/{shipment_id}/share/` — Revoke the share link. Invalidates the existing external tracking link immediately. (scope: shipments:share)
- `GET /api/public/v1/shipments/{shipment_id}/tracking/` — Get shipment tracking data. Returns tenant-scoped telemetry of the attached devices, limited to the shipment time window. (scope: shipments:tracking:read)

### Alarms — https://developer.frigolive.nl/en/api-reference/alarms

Read tenant-scoped alarm records and manage their resolution status.

- `GET /api/public/v1/alarms/` — List alarms. Returns tenant-scoped alarm records filtered by resolution, severity, device, and shipment. (scope: alarms:read)
- `GET /api/public/v1/alarms/{alarm_id}/` — Get alarm detail. Fetches the alarm only inside the selected tenant. (scope: alarms:read)
- `PATCH /api/public/v1/alarms/{alarm_id}/` — Update the alarm resolution status. Accepts only the resolved field and never writes the service account into the human resolved_by field. (scope: alarms:write)

### Reports — https://developer.frigolive.nl/en/api-reference/reports

List and securely download the report archive generated in Frigolive.

- `GET /api/public/v1/reports/` — List the report archive. Lists device and shipment reports already generated in Frigolive. (scope: reports:read)
- `GET /api/public/v1/reports/{report_id}/` — Get a report record. Returns the file metadata within the tenant. (scope: reports:read)
- `GET /api/public/v1/reports/{report_id}/download/` — Download the report file. Streams the file as an attachment after authorization and tenant checks. (scope: reports:read)

### Users & Invitations — https://developer.frigolive.nl/en/api-reference/users

Manage customer users and invitations without touching platform administrators.

- `GET /api/public/v1/users/` — List customer users. Lists users of the selected tenant, excluding platform staff and superuser records. (scope: users:read)
- `GET /api/public/v1/users/{user_id}/` — Get user detail. Fetches a customer user inside the tenant, never a platform user. (scope: users:read)
- `PATCH /api/public/v1/users/{user_id}/` — Update a customer user. Updates the profile and an assignable role; it can neither grant nor change COMPANY_ADMIN. (scope: users:write)
- `DELETE /api/public/v1/users/{user_id}/` — Deactivate a customer user. Deactivates a regular customer user and leaves company administrators untouched. (scope: users:write)
- `GET /api/public/v1/roles/` — List company roles. Returns the tenant roles that can be shown in your user interface. (scope: users:read)
- `GET /api/public/v1/user-invitations/` — List user invitations. Returns pending, accepted, and expired invitations without exposing the token. (scope: users:read)
- `POST /api/public/v1/user-invitations/` — Send a secure user invitation. Starts the Frigolive-hosted password creation flow by email, without returning the invitation token. (scope: users:invite)
- `DELETE /api/public/v1/user-invitations/{invitation_id}/` — Revoke a pending invitation. Revokes an invitation that has not been accepted yet, within the tenant. (scope: users:invite)

## Notes for code generation

- Never place `client_secret` in a browser or a mobile app; it belongs in a backend secret vault.
- Send `X-Frigolive-Account-ID` when the credential is assigned to more than one company.
- Send a unique `Idempotency-Key` (8-128 chars) on every record-creating POST.
- Retry only 429 and 5xx, with exponential backoff and jitter, honouring `Retry-After`.
- Read the next page from `links.next`; do not increment the page number yourself.