canonical: https://jentic.com/apis/bouncie.dev/bouncie

# Bouncie API

Jentic publishes the only available OpenAPI specification for Bouncie API, keeping it validated and agent-ready. Bouncie is a connected-vehicle platform built around an OBD-II device that streams trip, location, and diagnostic data from a user's vehicle. The API provides authenticated access to user profiles, vehicle inventories, trip histories, geo-zones, locations, and schedules, plus webhook registration for push events. Integrators register applications on the Bouncie Developer Portal and use OAuth 2.0 user authorization to access end-user vehicle data.

## For AI agents

Pull connected-vehicle trips, vehicle data, and geo-zone events for Bouncie-equipped cars and register webhooks across 23 endpoints.

## Scope

Does not handle vehicle remote control, OEM diagnostics, or insurance scoring - use for OBD-II trip, geo-zone, and webhook data on Bouncie-equipped vehicles only.

## Capabilities

- Retrieve the authenticated user's profile and vehicle inventory
- List trips for a user's vehicles with start, end, and distance data
- Register, update, and remove webhooks to receive vehicle event pushes
- Create and manage application-level geo-zones for fleet-wide alerts
- Read user-defined geo-zones tied to an end-user account
- Manage named locations and arrival or departure schedules
- Authorize end users via OAuth 2.0 and refresh access tokens

## Use cases

### Driving-behaviour insights for a connected app

Auto, insurance, and family-safety apps use Bouncie to give end users insight into where, when, and how they drove. The API exposes /v1/trips for the trip history and /v1/vehicles for the vehicle inventory, so an app can render a daily timeline and per-vehicle stats. Most apps ship the integration in a few days using the OAuth 2.0 authorization code flow.

Example prompt: List the last 10 trips for vehicle id veh_123 and summarise total distance and longest trip

### Geo-zone alerts for fleet operations

Light fleet operators use Bouncie's application geo-zones to know when one of their vehicles enters or leaves a customer site. POST /v1/application-geozones/ creates the zone, and webhooks deliver entry and exit events in real time without polling. Setup typically takes a sprint, including webhook signature handling.

Example prompt: Create an application geo-zone named 'Warehouse 5' centred on lat 33.7, lng -84.4 with a 200 metre radius, then register a webhook that receives geo-zone events

### Webhook-driven trip ingestion

Telematics apps avoid polling /v1/trips by registering for trip-end webhooks and ingesting each completed trip as it arrives. POST /v1/webhooks subscribes the application's callback URL and PUT /v1/webhooks/{webhookId} adjusts the subscription. Combined with /v1/trips for historical backfill, the app stays in sync without burning the rate budget on polling.

Example prompt: Register a webhook with URL https://example.com/bouncie that subscribes to trip events and confirm the webhook id

### Agent-driven vehicle queries via Jentic

An AI agent answers a user's natural-language question ('did my car go to the airport this week?') by calling Bouncie's trip and location endpoints. Through Jentic the agent searches for 'list Bouncie trips', loads the schema, and executes the call while the OAuth access and refresh tokens stay in your Jentic One instance.

Example prompt: Search Jentic for 'list Bouncie trips', load the schema, and execute it for the past 7 days, returning trips that ended within 5 km of the user's home location

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /v1/user | Authenticated user profile |
| GET | /v1/vehicles | List vehicles for the user |
| GET | /v1/trips | List trips for the user's vehicles |
| POST | /v1/webhooks | Register a webhook subscription |
| POST | /v1/application-geozones/ | Create an application geo-zone |
| POST | /v1/locations/ | Create a named location |
| POST | /v1/schedules/ | Create a schedule tied to a location |

## Key resources

- **User** — Read the authenticated user's profile
- **Vehicles** — List vehicles linked to the user's Bouncie devices
- **Trips** — List trips for the user's vehicles
- **Webhooks** — Register and manage webhook subscriptions for push events
- **Application Geo-Zones** — Create and manage application-level geo-zones used for entry and exit alerts
- **User Geo-Zones** — Read geo-zones the user has configured in their Bouncie app
- **Locations** — Create and manage named locations
- **Schedules** — Create and manage schedules that trigger on locations

## Why Jentic

- **Setup:** Wiring Bouncie by hand means running its OAuth flow, refreshing access tokens, and wiring the trip, vehicle, and webhook calls yourself. Through Jentic you install once, import the Bouncie API from the API Directory, store the OAuth credentials once, and your agent calls it.
- **Permission scoping:** Bouncie's trip and vehicle reads and its webhook, geo-zone, and schedule creates take their targets in the query or request body rather than the URL path, so scope the agent to the operations it needs, such as listing trips, and leave out ones like registering a webhook unless the agent requires them. Every operation you allow is one you have explicitly chosen.
- **Credential handling:** Your Bouncie OAuth access and refresh tokens are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list Bouncie trips' or 'register a Bouncie webhook', and Jentic returns the matching Bouncie operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Smartcar API** — OEM-integrated connected-car API that pulls data directly from manufacturer telematics rather than an OBD-II dongle.
- **Samsara API** — Enterprise fleet platform with hardware, video, and compliance features beyond consumer connected vehicles.
- **RTA Fleet API** — Fleet maintenance and asset platform that pairs with Bouncie's trip data for service scheduling.

## FAQ

### Why is there no official OpenAPI spec for Bouncie API?

Bouncie does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Bouncie API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Bouncie API use?

Bouncie uses OAuth 2.0 user authorization. Register your application on the Bouncie Developer Portal, redirect the user to https://auth.bouncie.com/dialog/authorize for consent, and exchange the returned code for an access token. In Jentic the tokens live in the vault and are injected at execution so they never enter the agent's context.

### Can I list a user's trips with the Bouncie API?

Yes. GET /v1/trips returns trips for the authenticated user's vehicles. Combine it with GET /v1/vehicles to map each trip back to a specific vehicle, and prefer trip-end webhooks for live ingestion rather than tight polling.

### How do I register a webhook through Jentic?

Run pip install jentic, then search Jentic for 'register a Bouncie webhook', load the POST /v1/webhooks schema, and execute it with your callback URL. Jentic handles the OAuth bearer header automatically; you only need to handle the webhook payloads on your side.

### What are the rate limits for the Bouncie API?

Bouncie does not document explicit per-second rate limits in the spec. Best practice is to rely on webhooks for trip and geo-zone events and to backfill via /v1/trips with reasonable page sizes; tight polling against /v1/trips is discouraged.

### Can I create geo-zones for entry and exit alerts?

Yes. POST /v1/application-geozones/ creates an application geo-zone visible to your application's connected users; pair it with a webhook subscription to receive entry and exit events. /v1/user-geozones is read-only and reflects zones the end user defined inside their Bouncie app.

### Can I limit what my agent is allowed to do with the Bouncie API?

Yes. Because you run Jentic One yourself, you decide which Bouncie operations the agent may call and which OAuth credentials it may use. You can allow read operations like listing trips (GET /v1/trips) and vehicles (GET /v1/vehicles) while withholding writes such as registering webhooks (POST /v1/webhooks) or creating geo-zones (POST /v1/application-geozones/) and schedules. Since these operations take their targets in the query or request body, every operation the agent can reach is one you have explicitly permitted.