### GET /v1/webhooks Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/webhooks ```markdown ### Parameters - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns an array of webhooks for the current application ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/webhooks" ``` ``` -------------------------------- ### GET /v1/schedules/ Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/schedules/ ```markdown ### Parameters - **id** (string, query, optional): Unique ID of the schedule (example: "65f8a2b4c9d7e1234567890f") - **name** (string, query, optional): Name of the schedule (example: "Weekday Work Hours") - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns schedules #### 400 - Returns a list of validation errors ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/schedules/?id=65f8a2b4c9d7e1234567890f&name=Weekday Work Hours" ``` ``` -------------------------------- ### GET /v1/application-geozones/ Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/application-geozones/ ```markdown ### Parameters - **imei** (string, query, optional): IMEI of the device that will trigger the webhook (example: "123456789101112") - **locationId** (string, query, optional): Unique identifier of the location associated with the application geozone - **scheduleId** (string, query, optional): Unique identifier of the schedule associated with the application geozone - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns application geozones #### 400 - Returns a list of validation errors ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/application-geozones/?imei=123456789101112&locationId=value&scheduleId=value" ``` ``` -------------------------------- ### GET /v1/user Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/user ```markdown ### Parameters - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns user information for the user associated with the current access token ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/user" ``` ``` -------------------------------- ### API Overview: Bouncie API Source: https://docs.bouncie.dev/openapi.json # Data Integration Specification Bouncie offers data integrations in two varieties: - [Webhooks](#webhooks) (push) - [Rest API Endpoints](#rest-api-endpoints) (pull) The registration and setup for your application with Bouncie is done through the [Bouncie Developer Portal](https://www.bouncie.dev/). --- # Navigation 1. [Authorization](#authorization) 2. [Webhooks](#webhooks) 3. [Geo-Zones](#geo-zones-1) 4. [Zapier Integration](#zapier-integration) 5. [FAQ](#faq) ## Authorization Bouncie API uses [User Authentication with OAuth 2.0](https://oauth.net/articles/authentication/) to authorize users for your application. To obtain Authorization, you must first register your application on the [Bouncie Developer Portal](https://www.bouncie.dev/) and follow the authorization code flow below. 1. You prompt your user to a webpage where they can give you permission to access their data. 1. Once your user has approved, they will be redirected back to a redirect uri that you will have initially set up for your application on the [Bouncie Developer Portal](https://www.bouncie.dev) with an authorization code as a query parameter (This step is enough to start receiving events for any webhooks you have registered). 1. You then use that authorization code to get an access token which can be used to make requests to Bouncie API REST endpoints. ### 1. Have your application request authorization; the user will log in using their Bouncie account and grant access. To request authorization, redirect your user to with the following parameters: | Request Query Parameter | Value | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | client_id | This value is required. When you set up your application on the [Bouncie Developer Portal](https://www.bouncie.dev/), you can set your Client ID | | response_type | This value is required. It should be set to "code" | | redirect_uri | This value is required. This is the URI the user will be redirected back to once they have granted permission. The URI needs to have been added to your application's Redirect URI list on the [Bouncie Developer Portal](https://www.bouncie.dev/). The value of this parameter must exactly match one of the Redirect URIs you have set up, including upper or lowercase, terminal slashes etc | | state | This value is optional. When the user is redirected back to your app, whatever value you include as the state will also be included in the redirect. You can check to see if the value you sent for state is the same as the value you got back for added security | | code_challenge | This value is optional. Base64Url encoded `code_verifier` for using [PKCE](https://datatracker.ietf.org/doc/html/rfc7636). | | code_challenge_method | This value is optional. `S256` (recommended) or `plain`. Defaults to `S256` if `code_challenge` is provided. | | resource | This value is optional. URI of the protected resource (e.g. `https://api.bouncie.dev/v1/`). Echoed as `aud` claim in the access token per RFC 8707. | > For more information on using PKCE see the [RFC](https://datatracker.ietf.org/doc/html/rfc7636) #### Example An example of an authorization URL: `https://auth.bouncie.com/dialog/authorize?client_id=my-app&redirect_uri=http://www.example.com/&response_type=code&state=abcdefg` An example of the response URL if the user grants permission: `http://www.example.com/?code=I1uHE12LIK123PQRmnoGD1RnR12Ybrr99Tio1SQRpow12dabc&state=abcdefg` | Response Query Parameter | Value | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | code | An authorization code that can be exchanged for an access token. There is no expiration for the authorization code, however if the user goes through the authorization flow for your application again and a new authorization code is generated, the old authorization code will no longer be valid | | state | The value of the state parameter supplied in the request. | #### At this point, if you have any [Webhooks](#webhooks) set up, you will start receiving events for the user that has just granted your application permission ### 2. Have your application request access tokens. Once you have received an authorization code, you will need to exchange it with an access token by making a POST request to . The body of this POST (JSON) will be as follows: | Request Header Field | Value | | -------------------- | ---------------- | | Content-Type | application/json | | Request Body Field | Value | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | client_id | This value is required. When you set up your application on the [Bouncie Developer Portal](https://www.bouncie.dev/), you can set your Client ID | | client_secret | This value is required. It is provided to you when you set up your application on the [Bouncie Developer Portal](https://www.bouncie.dev/) | | grant_type | This value is required. It must be set to "authorization_code" | | code | This value is required. It is the authorization code returned by the initial endpoint | | redirect_uri | This value is required. It must match one of the Redirect URI's you have set up for your application on the [Bouncie Developer Portal](https://www.bouncie.dev/). This value is ONLY used for validation, there is no actual redirection that happens here | | code_verifier | This value is required if you are using [PKCE](https://datatracker.ietf.org/doc/html/rfc7636). | An alternative way to send the Client ID and the Client Secret is as an authorization header with the value set to a base64 encoded string as follows: | Request Header Field | Value | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Content-Type | application/json | | Authorization | If you do not send the Client ID and the Client Secret as part of the request body, you can send it using the Authorization header. The value **must** be a base64 encoded string and **must** have the following format Authorization: Basic _< base64 encoded client_id:client_secret >_ | A successful request for the access token will yield a JSON response with the following fields: | Response field | Value Type | Value Description | | -------------- | ---------- | -------------------------------------------------------------------------------------- | | access_token | string | An access token that can be provided in subsequent calls to Bouncie API REST endpoints | | refresh_token | string | A refresh token that can be exchanged for a new access token | | expires_in | int | The time period (in seconds) for which the access token is valid. | | token_type | string | Describes how the access token may be used. It is always set to "Bearer". | You can now make calls to Bouncie API REST endpoints by sending the access token as the request authorization header. ### 3. Refresh an expired access token. Once your access token has expired, you will need to exchange your refresh token for a new access token by making another POST request to . The body of this POST (JSON) will be as follows: | Request Header Field | Value | | -------------------- | ---------------- | | Content-Type | application/json | | Request Body Field | Value | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | client_id | This value is required. When you set up your application on the [Bouncie Developer Portal](https://www.bouncie.dev/), you can set your Client ID | | client_secret | This value is required. It is provided to you when you set up your application on the [Bouncie Developer Portal](https://www.bouncie.dev/) | | grant_type | This value is required. It must be set to "refresh_token" | | refresh_token | This value is required. It is the refresh token returned by the previous request to the endpoint | A successful request will yield a JSON response with the same fields as the previous request with a new access token and new refresh token. The previous refresh token will no longer be valid. Each refresh token will expire after some time if it is not used. If the refresh token expires, you can generate a new one by making a POST request to the endpoint again with the same POST body as described in [step 2](#2-have-your-application-request-access-tokens). --- ## Webhooks Webhooks can be used to be notified about events occurring on your vehicle. This can greatly your simplify the overhead for loading data, since polling the restful APIs may no longer be necessary. **Configuration is simple:** Provide Bouncie secure server side URL endpoint and specify the types of events you wish to receive. (ex: [https://myapp.mycompany.com/bouncie-webhook](https://myapp.mycompany.com/bouncie-webhook)). Webhooks can be set up for your application on the [Bouncie Developer Portal](https://www.bouncie.dev/). **_That’s it!_** Now when an event occurs for your any of your connected vehicles. Bouncie will POST JSON event payloads to your endpoint in real time. ### Webhook Security Webhooks use a unique key that you provide to secure calls. An `Authorization` header will be sent with every outgoing webhook that you can use to validate that the incoming request is actually from Bouncie. Additionally, Bouncie provides an `X-Bouncie-Authorization` header that is also included with every outgoing webhook. This header will have the same value as the `Authorization` header and can be used for validation in the same manner. Bouncie provides this header in the event that the platform your app is running on has removed the `Authorization` header. ```json // HTTP Headers { "Authorization": "yourKey", "X-Bouncie-Authorization": "yourKey", } ``` As part of the process of setting up your application you will provide the initial value for this key. ### Webhook Key rotation Webhook consumers can change their unique key by returning a new key in an `Authorization` response header in the response to the webhook. ### Retries URL endpoint(s) for webkook calls should respond with `2xx` level status code to indicate successful receipt. Bouncie will attempt to retry a webhook Request if it times out, responds with invalid JSON, or responds with a `4xx` or `5xx` level status code. A backoff policy will be used to prevent overloading the webhook endpoint. Bouncie will continue retrying until the maximum amount of retries are reached. ### Event Types #### Device - [Device Connected](webhooks/deviceConnect/post) - [Device Disconnected](webhooks/deviceDisconnect/post) - [VIN Change](webhooks/vinChange/post) #### Vehicle Health - [MIL](webhooks/mil/post) - [Low Battery](webhooks/battery/post) #### Trips - [Trip Start](webhooks/tripStart/post) - [Trip Data](webhooks/tripData/post) - [Trip Metrics](webhooks/tripMetrics/post) - [Trip End](webhooks/tripEnd/post) #### Geo-Zones - [Application Geo-Zone](webhooks/applicationGeozone/post) - [User Geo-Zone](webhooks/userGeozone/post) --- ## Rest API Endpoints ### Base URL - The base URL is [https://api.bouncie.dev/v1/](https://api.bouncie.dev/v1/). - All API requests must use HTTPS. Calls made over HTTP will fail. - Successful requests return JSON data (application/json). ### Authentication The Bouncie API uses the access token that is granted to you per user who grants access to their information. This access token is generated when you [obtain authorization](#authorization). ```json // HTTP Headers { "Authorization": "AccessTokenYouHaveGenerated", "Content-Type": "application/json" } ``` ### Responses and Errors Bouncie API uses standard HTTP response codes to indicate success or failure of an API request. | Responses | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | 200 - OK | A GET request succeeded. JSON response. | | 201 - Created | A POST response succeeded. JSON response. | | 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. JSON response`{ "errors": "This was a bad request because..." }` | | 401 - Unauthorized | No valid API key provided. | | 404 - Not Found | The requested resource doesn't exist. | | 50x - Application Error | An error occurred on Bouncie API | --- ## Geo-Zones Bouncie supports two types of Geo-Zones: User Geo-Zones, which are managed by users, and Application Geo-Zones, which are created and managed through the API. ### User Geo-Zones These are created and managed directly by users through the Bouncie app or web dashboard. Users can set up zones around locations of interest—like home, school, or work—and receive notifications when their vehicle enters or exits these areas. User Geo-Zones are personal and cannot be modified by external integrations. ### Application Geo-Zones Application Geo-Zones are designed for integrations that require programmatically defined zones. These zones are created and managed through the Bouncie API, allowing for dynamic setup and control independent of User Geo-Zones. Application Geo-Zones **do not appear** in the Bouncie client experience and do not trigger notifications to users. To create an Application Geo-Zone: 1. **Create a Location**: Define the geographic area by specifying coordinates and a radius or a polygon. Refer to the [Create Location](paths/v1-locations/post) endpoint for details. 2. **(Optional) Create a Schedule**: Define active time periods for the geozone. This step is optional. Refer to the [Create Schedule](paths/v1-schedules/post) endpoint for details. 3. **Create the Application Geo-Zone**: Use the IDs from the Location and Schedule (if applicable) to create the geozone. Refer to the [Create Application Geo-Zone](paths/v1-application-geozones/post) endpoint for details. --- ## Zapier Integration Bouncie has a Zapier integration that allows you to connect Bouncie with other applications. You can use this integration to automate tasks and workflows between Bouncie and other applications without writing any code. ### Setup To use the Zapier integration, you will need to register an application on the [Bouncie Developer Portal](https://www.bouncie.dev/). Your application must have the following as a redirect URL: ``` https://zapier.com/dashboard/auth/oauth/return/App220583CLIAPI/ ``` You will be prompted to provide the application's `Client ID` and `Client Secret` when connecting your account while creating a Zap with a Bouncie trigger. **This application should only be used with the Zapier integration.** ## FAQ ### Why does the API return a 401 Unauthorized error? - The access token may be expired. See the [refresh an expired access token section](#3-refresh-an-expired-access-token) for more information on how to generate a fresh access token. - The Authorization header value may not be formatted correctly. Make sure to only include the access token and **not** the "Bearer" prefix. - The application may no longer have access to the user data that the access token was issued for. Verify the user shows up in the list in the Users & Devices tab for the application on the [Bouncie Developer Portal](https://www.bouncie.dev/). ### How much data can I expect to receive from webhooks? - Data volume depends on the number of devices authorized to your account and how often the vehicles they are installed in are driven. - The specific events you subscribe to play a significant role in overall data volume. For example: - `battery` events are sent only when battery voltage drops below a defined threshold. - `tripMetrics` is reported once per trip, upon its conclusion. - `tripData` events are transmitted continuously throughout the entirety of a trip and will make up the bulk of your data volume if enabled. - Devices may occasionally lose cellular connectivity — such as when operating in low-signal areas or parked underground. When this happens, trip data is temporarily stored on the device and transmitted once the connection is reestablished. Although the total volume of events remains unchanged, the data may be sent all at once over a short period of time. This can lead to brief spikes in webhook traffic. ### Why do I receive duplicate trip events? - See the [trip data documentation](/webhooks/tripData/post#handling-message-data-duplication) for more details on why duplication happens and how to handle it properly in your application. ### What happens if a webhook cannot be delivered? - If a webhook request times out or returns a 4xx or 5xx status code, Bouncie will automatically retry the request. Retries follow an exponential backoff policy to avoid overwhelming the receiving server. Retries will continue until a maximum number of attempts is reached. - If a webhook continues to fail after repeated retries, it will be automatically deactivated. This typically happens after prolonged periods of unresponsiveness or error responses. Once deactivated, no further events will be sent to that webhook URL until it is re-enabled. ```yaml # Bouncie API # Version: 1.0.0 # Data Integration Specification Bouncie offers data integrations in two varieties: - [Webhooks](#webhooks) (push) - [Rest API Endpoints](#rest-api-endpoints) (pull) The registration and setup for your application with Bouncie is done through the [Bouncie Developer Portal](https://www.bouncie.dev/). --- # Navigation 1. [Authorization](#authorization) 2. [Webhooks](#webhooks) 3. [Geo-Zones](#geo-zones-1) 4. [Zapier Integration](#zapier-integration) 5. [FAQ](#faq) ## Authorization Bouncie API uses [User Authentication with OAuth 2.0](https://oauth.net/articles/authentication/) to authorize users for your application. To obtain Authorization, you must first register your application on the [Bouncie Developer Portal](https://www.bouncie.dev/) and follow the authorization code flow below. 1. You prompt your user to a webpage where they can give you permission to access their data. 1. Once your user has approved, they will be redirected back to a redirect uri that you will have initially set up for your application on the [Bouncie Developer Portal](https://www.bouncie.dev) with an authorization code as a query parameter (This step is enough to start receiving events for any webhooks you have registered). 1. You then use that authorization code to get an access token which can be used to make requests to Bouncie API REST endpoints. ### 1. Have your application request authorization; the user will log in using their Bouncie account and grant access. To request authorization, redirect your user to with the following parameters: | Request Query Parameter | Value | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | client_id | This value is required. When you set up your application on the [Bouncie Developer Portal](https://www.bouncie.dev/), you can set your Client ID | | response_type | This value is required. It should be set to "code" | | redirect_uri | This value is required. This is the URI the user will be redirected back to once they have granted permission. The URI needs to have been added to your application's Redirect URI list on the [Bouncie Developer Portal](https://www.bouncie.dev/). The value of this parameter must exactly match one of the Redirect URIs you have set up, including upper or lowercase, terminal slashes etc | | state | This value is optional. When the user is redirected back to your app, whatever value you include as the state will also be included in the redirect. You can check to see if the value you sent for state is the same as the value you got back for added security | | code_challenge | This value is optional. Base64Url encoded `code_verifier` for using [PKCE](https://datatracker.ietf.org/doc/html/rfc7636). | | code_challenge_method | This value is optional. `S256` (recommended) or `plain`. Defaults to `S256` if `code_challenge` is provided. | | resource | This value is optional. URI of the protected resource (e.g. `https://api.bouncie.dev/v1/`). Echoed as `aud` claim in the access token per RFC 8707. | > For more information on using PKCE see the [RFC](https://datatracker.ietf.org/doc/html/rfc7636) #### Example An example of an authorization URL: `https://auth.bouncie.com/dialog/authorize?client_id=my-app&redirect_uri=http://www.example.com/&response_type=code&state=abcdefg` An example of the response URL if the user grants permission: `http://www.example.com/?code=I1uHE12LIK123PQRmnoGD1RnR12Ybrr99Tio1SQRpow12dabc&state=abcdefg` | Response Query Parameter | Value | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | code | An authorization code that can be exchanged for an access token. There is no expiration for the authorization code, however if the user goes through the authorization flow for your application again and a new authorization code is generated, the old authorization code will no longer be valid | | state | The value of the state parameter supplied in the request. | #### At this point, if you have any [Webhooks](#webhooks) set up, you will start receiving events for the user that has just granted your application permission ### 2. Have your application request access tokens. Once you have received an authorization code, you will need to exchange it with an access token by making a POST request to . The body of this POST (JSON) will be as follows: | Request Header Field | Value | | -------------------- | ---------------- | | Content-Type | application/json | | Request Body Field | Value | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | client_id | This value is required. When you set up your application on the [Bouncie Developer Portal](https://www.bouncie.dev/), you can set your Client ID | | client_secret | This value is required. It is provided to you when you set up your application on the [Bouncie Developer Portal](https://www.bouncie.dev/) | | grant_type | This value is required. It must be set to "authorization_code" | | code | This value is required. It is the authorization code returned by the initial endpoint | | redirect_uri | This value is required. It must match one of the Redirect URI's you have set up for your application on the [Bouncie Developer Portal](https://www.bouncie.dev/). This value is ONLY used for validation, there is no actual redirection that happens here | | code_verifier | This value is required if you are using [PKCE](https://datatracker.ietf.org/doc/html/rfc7636). | An alternative way to send the Client ID and the Client Secret is as an authorization header with the value set to a base64 encoded string as follows: | Request Header Field | Value | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Content-Type | application/json | | Authorization | If you do not send the Client ID and the Client Secret as part of the request body, you can send it using the Authorization header. The value **must** be a base64 encoded string and **must** have the following format Authorization: Basic _< base64 encoded client_id:client_secret >_ | A successful request for the access token will yield a JSON response with the following fields: | Response field | Value Type | Value Description | | -------------- | ---------- | -------------------------------------------------------------------------------------- | | access_token | string | An access token that can be provided in subsequent calls to Bouncie API REST endpoints | | refresh_token | string | A refresh token that can be exchanged for a new access token | | expires_in | int | The time period (in seconds) for which the access token is valid. | | token_type | string | Describes how the access token may be used. It is always set to "Bearer". | You can now make calls to Bouncie API REST endpoints by sending the access token as the request authorization header. ### 3. Refresh an expired access token. Once your access token has expired, you will need to exchange your refresh token for a new access token by making another POST request to . The body of this POST (JSON) will be as follows: | Request Header Field | Value | | -------------------- | ---------------- | | Content-Type | application/json | | Request Body Field | Value | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | client_id | This value is required. When you set up your application on the [Bouncie Developer Portal](https://www.bouncie.dev/), you can set your Client ID | | client_secret | This value is required. It is provided to you when you set up your application on the [Bouncie Developer Portal](https://www.bouncie.dev/) | | grant_type | This value is required. It must be set to "refresh_token" | | refresh_token | This value is required. It is the refresh token returned by the previous request to the endpoint | A successful request will yield a JSON response with the same fields as the previous request with a new access token and new refresh token. The previous refresh token will no longer be valid. Each refresh token will expire after some time if it is not used. If the refresh token expires, you can generate a new one by making a POST request to the endpoint again with the same POST body as described in [step 2](#2-have-your-application-request-access-tokens). --- ## Webhooks Webhooks can be used to be notified about events occurring on your vehicle. This can greatly your simplify the overhead for loading data, since polling the restful APIs may no longer be necessary. **Configuration is simple:** Provide Bouncie secure server side URL endpoint and specify the types of events you wish to receive. (ex: [https://myapp.mycompany.com/bouncie-webhook](https://myapp.mycompany.com/bouncie-webhook)). Webhooks can be set up for your application on the [Bouncie Developer Portal](https://www.bouncie.dev/). **_That’s it!_** Now when an event occurs for your any of your connected vehicles. Bouncie will POST JSON event payloads to your endpoint in real time. ### Webhook Security Webhooks use a unique key that you provide to secure calls. An `Authorization` header will be sent with every outgoing webhook that you can use to validate that the incoming request is actually from Bouncie. Additionally, Bouncie provides an `X-Bouncie-Authorization` header that is also included with every outgoing webhook. This header will have the same value as the `Authorization` header and can be used for validation in the same manner. Bouncie provides this header in the event that the platform your app is running on has removed the `Authorization` header. ```json // HTTP Headers { "Authorization": "yourKey", "X-Bouncie-Authorization": "yourKey", } ``` As part of the process of setting up your application you will provide the initial value for this key. ### Webhook Key rotation Webhook consumers can change their unique key by returning a new key in an `Authorization` response header in the response to the webhook. ### Retries URL endpoint(s) for webkook calls should respond with `2xx` level status code to indicate successful receipt. Bouncie will attempt to retry a webhook Request if it times out, responds with invalid JSON, or responds with a `4xx` or `5xx` level status code. A backoff policy will be used to prevent overloading the webhook endpoint. Bouncie will continue retrying until the maximum amount of retries are reached. ### Event Types #### Device - [Device Connected](webhooks/deviceConnect/post) - [Device Disconnected](webhooks/deviceDisconnect/post) - [VIN Change](webhooks/vinChange/post) #### Vehicle Health - [MIL](webhooks/mil/post) - [Low Battery](webhooks/battery/post) #### Trips - [Trip Start](webhooks/tripStart/post) - [Trip Data](webhooks/tripData/post) - [Trip Metrics](webhooks/tripMetrics/post) - [Trip End](webhooks/tripEnd/post) #### Geo-Zones - [Application Geo-Zone](webhooks/applicationGeozone/post) - [User Geo-Zone](webhooks/userGeozone/post) --- ## Rest API Endpoints ### Base URL - The base URL is [https://api.bouncie.dev/v1/](https://api.bouncie.dev/v1/). - All API requests must use HTTPS. Calls made over HTTP will fail. - Successful requests return JSON data (application/json). ### Authentication The Bouncie API uses the access token that is granted to you per user who grants access to their information. This access token is generated when you [obtain authorization](#authorization). ```json // HTTP Headers { "Authorization": "AccessTokenYouHaveGenerated", "Content-Type": "application/json" } ``` ### Responses and Errors Bouncie API uses standard HTTP response codes to indicate success or failure of an API request. | Responses | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | 200 - OK | A GET request succeeded. JSON response. | | 201 - Created | A POST response succeeded. JSON response. | | 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. JSON response`{ "errors": "This was a bad request because..." }` | | 401 - Unauthorized | No valid API key provided. | | 404 - Not Found | The requested resource doesn't exist. | | 50x - Application Error | An error occurred on Bouncie API | --- ## Geo-Zones Bouncie supports two types of Geo-Zones: User Geo-Zones, which are managed by users, and Application Geo-Zones, which are created and managed through the API. ### User Geo-Zones These are created and managed directly by users through the Bouncie app or web dashboard. Users can set up zones around locations of interest—like home, school, or work—and receive notifications when their vehicle enters or exits these areas. User Geo-Zones are personal and cannot be modified by external integrations. ### Application Geo-Zones Application Geo-Zones are designed for integrations that require programmatically defined zones. These zones are created and managed through the Bouncie API, allowing for dynamic setup and control independent of User Geo-Zones. Application Geo-Zones **do not appear** in the Bouncie client experience and do not trigger notifications to users. To create an Application Geo-Zone: 1. **Create a Location**: Define the geographic area by specifying coordinates and a radius or a polygon. Refer to the [Create Location](paths/v1-locations/post) endpoint for details. 2. **(Optional) Create a Schedule**: Define active time periods for the geozone. This step is optional. Refer to the [Create Schedule](paths/v1-schedules/post) endpoint for details. 3. **Create the Application Geo-Zone**: Use the IDs from the Location and Schedule (if applicable) to create the geozone. Refer to the [Create Application Geo-Zone](paths/v1-application-geozones/post) endpoint for details. --- ## Zapier Integration Bouncie has a Zapier integration that allows you to connect Bouncie with other applications. You can use this integration to automate tasks and workflows between Bouncie and other applications without writing any code. ### Setup To use the Zapier integration, you will need to register an application on the [Bouncie Developer Portal](https://www.bouncie.dev/). Your application must have the following as a redirect URL: ``` https://zapier.com/dashboard/auth/oauth/return/App220583CLIAPI/ ``` You will be prompted to provide the application's `Client ID` and `Client Secret` when connecting your account while creating a Zap with a Bouncie trigger. **This application should only be used with the Zapier integration.** ## FAQ ### Why does the API return a 401 Unauthorized error? - The access token may be expired. See the [refresh an expired access token section](#3-refresh-an-expired-access-token) for more information on how to generate a fresh access token. - The Authorization header value may not be formatted correctly. Make sure to only include the access token and **not** the "Bearer" prefix. - The application may no longer have access to the user data that the access token was issued for. Verify the user shows up in the list in the Users & Devices tab for the application on the [Bouncie Developer Portal](https://www.bouncie.dev/). ### How much data can I expect to receive from webhooks? - Data volume depends on the number of devices authorized to your account and how often the vehicles they are installed in are driven. - The specific events you subscribe to play a significant role in overall data volume. For example: - `battery` events are sent only when battery voltage drops below a defined threshold. - `tripMetrics` is reported once per trip, upon its conclusion. - `tripData` events are transmitted continuously throughout the entirety of a trip and will make up the bulk of your data volume if enabled. - Devices may occasionally lose cellular connectivity — such as when operating in low-signal areas or parked underground. When this happens, trip data is temporarily stored on the device and transmitted once the connection is reestablished. Although the total volume of events remains unchanged, the data may be sent all at once over a short period of time. This can lead to brief spikes in webhook traffic. ### Why do I receive duplicate trip events? - See the [trip data documentation](/webhooks/tripData/post#handling-message-data-duplication) for more details on why duplication happens and how to handle it properly in your application. ### What happens if a webhook cannot be delivered? - If a webhook request times out or returns a 4xx or 5xx status code, Bouncie will automatically retry the request. Retries follow an exponential backoff policy to avoid overwhelming the receiving server. Retries will continue until a maximum number of attempts is reached. - If a webhook continues to fail after repeated retries, it will be automatically deactivated. This typically happens after prolonged periods of unresponsiveness or error responses. Once deactivated, no further events will be sent to that webhook URL until it is re-enabled. # Base URL: https://api.bouncie.dev ``` -------------------------------- ### GET /v1/locations/ Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/locations/ ```markdown ### Parameters - **name** (string, query, optional): Name of the location (example: "Home") - **id** (string, query, optional): Unique Identifier of the location (example: "65f8a2b4c9d7e1234567890e") - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns locations #### 400 - Returns a list of validation errors ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/locations/?name=Home&id=65f8a2b4c9d7e1234567890e" ``` ``` -------------------------------- ### GET /v1/vehicles Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/vehicles ```markdown ### Parameters - **vin** (string, query, optional): Vehicle Identification Number for vehicle (example: "1HGBIQOJXMN109186") - **imei** (string, query, optional): Unique bouncie device identifier (example: "123456789012345") - **limit** (number, query, optional): Number of search results to limit (for paging) (example: 10) - **skip** (number, query, optional): Number of search results to skip (for paging) (example: 0) - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns an array of vehicles matching the given criteria ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/vehicles?vin=1HGBIQOJXMN109186&imei=123456789012345&limit=10&skip=0" ``` ``` -------------------------------- ### GET /v1/schedules/{scheduleId} Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/schedules/{scheduleId} ```markdown ### Parameters - **scheduleId** (string, path, required) - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns a schedule #### 404 - Responds with a status code of 404 if a schedule could not be found ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/schedules/{scheduleId}" ``` ``` -------------------------------- ### GET /v1/user-geozones/ Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/user-geozones/ ```markdown ### Parameters - **imei** (string, query, optional): IMEI of the device that will trigger the webhook (example: "123456789101112") - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns user geozones #### 400 - Returns a list of validation errors ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/user-geozones/?imei=123456789101112" ``` ``` -------------------------------- ### GET /v1/application-geozones/{applicationGeozoneId} Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/application-geozones/{applicationGeozoneId} ```markdown ### Parameters - **applicationGeozoneId** (string, path, required) - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns an application geozone #### 404 - Responds with a status code of 404 if an application geozone could not be found ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/application-geozones/{applicationGeozoneId}" ``` ``` -------------------------------- ### GET /v1/locations/{locationId} Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/locations/{locationId} ```markdown ### Parameters - **locationId** (string, path, required) - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns a location #### 404 - Responds with a status code of 404 if a location could not be found ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/locations/{locationId}" ``` ``` -------------------------------- ### GET /v1/trips Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/trips ```markdown ### Parameters - **imei** (string, query, optional): IMEI for the vehicle to retrieve trips for (example: "123456789012345") - **transaction-id** (string, query, optional): Unique Trip Identifier (example: "123456789012345-1735920000-202501") - **gps-format** (string, query, optional): One of: `polyline` or `geojson` (example: "polyline") - **starts-after** (string, query, optional): Will match trips with a starting time after this parameter. The window between `starts-after` and `ends-before` must be no longer than a week. If not provided, the last week will be used by default (example: "2026-01-01T08:30:00.000Z") - **ends-before** (string, query, optional): Will match trips with an ending time before this parameter (example: "2026-01-02T06:00:00.000Z") - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns an array of trips matching given criteria ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/trips?imei=123456789012345&transaction-id=123456789012345-1735920000-202501&gps-format=polyline&starts-after=2026-01-01T08:30:00.000Z&ends-before=2026-01-02T06:00:00.000Z" ``` ``` -------------------------------- ### GET /v1/user-geozones/{userGeozoneId} Source: https://docs.bouncie.dev/openapi.json API endpoint for GET /v1/user-geozones/{userGeozoneId} ```markdown ### Parameters - **userGeozoneId** (string, path, required) - **Authorization** (string, header, optional): User access token - **Content-Type** (string, header, optional) ### Responses #### 200 - Returns a user geozone #### 404 - Responds with a status code of 404 if a user geozone could not be found ### Example Usage ```bash curl -X GET "https://api.bouncie.dev/v1/user-geozones/{userGeozoneId}" ``` ```