Switchboard API Reference

Introduction

The Switchboard API is a RESTful API that provides access to various resources on the Switchboard platform. This reference not only provides an overview of available APIs, but allows you to execute them directly on the page in order to test and confirm API behavior.

Authentication

The Switchboard API uses API keys to authenticate requests. Head to Settings > API Keys on our web platform to generate and manage your API credentials. It is important to limit the number of API credentials generated as each key grants access to all scopes and resources.

Remember that your API credentials are a secret! Do not share it with others or expose it in any client-side code.

All API requests must include the HTTP headers x-api-id and x-api-key in the following manner:

x-api-id: $SWITCHBOARD_API_ID
x-api-key: $SWITCHBOARD_API_KEY

Example with curl command:

curl https://api.onswitchboard.com/v1/vehicles \
  -H "x-api-id: $SWITCHBOARD_API_ID" \
  -H "x-api-key: $SWITCHBOARD_API_KEY"

Rate Limits

The Switchboard API applies rate-limiting to incoming requests on a per-key basis to help maximize its stability. Users who exceed the rate-limit quotas will most likely encounter an error response with a status code 429 for subsequent requests.

For all endpoints, Switchboard allows a maximum of 60 requests per minute. Treat these limits as maximums and prevent any unnecessary loads whenever possible. We may reduce limits to prevent abuse, or increase limits to enable high-traffic applications.

Additionally, each response from the API will include the following headers to help monitor rate-limits:

X-RateLimit-Limit: the number of requests allowed in the current period

X-RateLimit-Remaining: the number of requests remaining in the current period

X-RateLimit-Reset: the number of seconds until the current period resets

Retry-After: the number of seconds to wait before retrying

Performing API Requests

This section provides examples on how to perform requests to the Switchboard API. To get started, ensure you have obtained a set of API credentials as mentioned in the previous section. To learn more about a specific endpoint, refer to the documentation located on the sidebar.

The examples laid out in this section will perform requests to the /v1/vehicles endpoint.

Fetching Vehicles

The following request queries for a list of vehicles. The corresponding response is shown below containing the list of vehicles and their attributes.

curl -X GET https://api.onswitchboard.com/v1/vehicles?limit=20&page=0 \
  -H "x-api-id: $SWITCHBOARD_API_ID" \
  -H "x-api-key: $SWITCHBOARD_API_KEY"

[
  {
    "id": "lnzTIBw9uT",
    "unitId": "001",
    "licensePlate": {
      "value": null,
      "jurisdiction": null
    },
    "vinNumber": null,
    "vehicleType": null,
    "nextInspectionDate": null,
    "inspectionFrequencyMonths": null,
    "dashcamHardwareId": null,
    "mviDecalNumber": null,
    "engineModuleId": null,
    "notes": null
  }
]

Creating a Vehicle

The following request creates a new vehicle. If successful, the corresponding response will return the newly created vehicle and its id.

curl -X POST https://api.onswitchboard.com/v1/vehicles \
  -H "Content-Type: application/json" \
  -H "x-api-id: $SWITCHBOARD_API_ID" \
  -H "x-api-key: $SWITCHBOARD_API_KEY" \
  -d '{
    "unitId": "002",
    "licensePlate": {
      "value": "ABC123",
      "jurisdiction": "BC"
    }
  }'

{
  "id": "u34d4Ebl18",
  "unitId": "002",
  "licensePlate": {
    "value": "ABC123",
    "jurisdiction": "BC"
  },
  "vinNumber": null,
  "vehicleType": null,
  "nextInspectionDate": null,
  "inspectionFrequencyMonths": null,
  "dashcamHardwareId": null,
  "mviDecalNumber": null,
  "engineModuleId": null,
  "notes": null
}

Authentication

This documentation reference allows you to perform requests against the Switchboard API directly on the page in order to test and confirm API behavior. To execute API calls from this page, you must first provide the correct authentication credentials below.

The API credentials set in this page will enable you to run any of the requests presented in this documentation. As such, please be aware that these are live requests, and performing these requests allows you to modify your existing data. Please confirm your intention before executing API calls present here.

API Credentials

Note: Refreshing the page will reset any credentials set previously.

API ID (x-api-id)

API Key (x-api-key)