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.
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.
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-id: $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"
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 5 requests per second. 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
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.
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
}
]
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
}
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.
Note: Refreshing the page will reset any credentials set previously.