TCS API Documentation

Introduction

The TCSHUB API provides RESTful access to manage and query the licensing status of your drivers and vehicles as reported by the New York City Taxi and Limousine Commission.

Access is available to paid subscribers of the TCS App with a separate subscription to the API. To subscribe to the API service, sign in and click here for more information.

Authentication

All API requests require authentication via an API key passed in the request header.

You can provide your API key using one of the following methods:

X-API-Key header: X-API-Key: your-api-key-here
Authorization header: Authorization: Bearer your-api-key-here

Example using curl:

curl -H "X-API-Key: your-api-key-here" \
    https://app.tcshub.com/api/drivers

Note: For backward compatibility, API keys in query parameters are still supported but deprecated. Please use headers for all new integrations.

API Overview

The API follows REST conventions and supports full CRUD operations:

GET - Retrieve resources (list or single item)
POST - Create new resources
PUT - Update existing resources
DELETE - Delete resources

Important notes:

Response format is JSON only
Content-Type header should be application/json for POST and PUT requests
All endpoints use plural resource names (/api/drivers, /api/vehicles)
Standard HTTP status codes are returned (200, 201, 204, 400, 401, 404, 409, 500)

HTTP Status Codes

The API uses standard HTTP status codes:

200 OK - Successful GET or PUT request
201 Created - Successful POST request (resource created)
204 No Content - Successful DELETE request
400 Bad Request - Invalid request parameters
401 Unauthorized - Missing or invalid API key
404 Not Found - Resource not found
409 Conflict - Resource already exists (duplicate)
500 Internal Server Error - Server error

Drivers API

List All Drivers

GET /api/drivers

Returns a list of all active drivers in your account.

Example request:

curl -H "X-API-Key: your-api-key" \
    https://app.tcshub.com/api/drivers

Example response (200 OK):

[
 {
   "licenseNumber": "123456",
   "licenseeName": "John Doe",
   "licenseExpirationDate": "2016-10-05T04:00:00.000Z",
   "licenseType": "For-Hire-Vehicle Driver",
   "dmvStatus": "CURRENT",
   "dmvStatusChecked": "2014-11-05T04:00:00.000Z",
   "tlcStatus": "CURRENT",
   "tlcStatusChecked": "2014-11-05T04:00:00.000Z",
   "notes": null,
   "created": "2014-10-01T12:00:00.000Z"
 }
]

Get Single Driver

GET /api/drivers/:licenseNumber

Returns information for a specific driver.

Example request:

curl -H "X-API-Key: your-api-key" \
    https://app.tcshub.com/api/drivers/123456

Example response (200 OK):

{
 "licenseNumber": "123456",
 "licenseeName": "John Doe",
 "licenseExpirationDate": "2016-10-05T04:00:00.000Z",
 "licenseType": "For-Hire-Vehicle Driver",
 "dmvStatus": "CURRENT",
 "dmvStatusChecked": "2014-11-05T04:00:00.000Z",
 "tlcStatus": "CURRENT",
 "tlcStatusChecked": "2014-11-05T04:00:00.000Z",
 "notes": "Driver notes here",
 "created": "2014-10-01T12:00:00.000Z"
}

Example error response (404 Not Found):

{
 "error": "Driver not found"
}

Create Driver

POST /api/drivers

Creates a new driver in your account. The driver must exist in the TLC database.

Request body:

{
 "licenseNumber": "123456",
 "notes": "Optional driver notes"
}

Example request:

curl -X POST \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{"licenseNumber": "123456", "notes": "New driver"}' \
    https://app.tcshub.com/api/drivers

Example response (201 Created):

{
 "id": 123,
 "accountID": 1,
 "status": "ACTIVE",
 "baseLicenseNumber": "B12345",
 "licenseNumber": "123456",
 "licenseeName": "John Doe",
 "licenseExpirationDate": "2016-10-05",
 "licenseType": "For-Hire-Vehicle Driver",
 "notes": "New driver",
 "created": "2014-10-01T12:00:00.000Z"
}

Example error responses:

400 Bad Request: {"error": "License number is required"}
400 Bad Request: {"error": "License number does not match any current TLC licensee"}
409 Conflict: {"error": "Driver already exists"}

Update Driver

PUT /api/drivers/:licenseNumber

Updates an existing driver. Currently, only the notes field can be updated.

Request body:

{
 "notes": "Updated driver notes"
}

Example request:

curl -X PUT \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{"notes": "Updated notes"}' \
    https://app.tcshub.com/api/drivers/123456

Example response (200 OK):

{
 "licenseNumber": "123456",
 "licenseeName": "John Doe",
 "licenseExpirationDate": "2016-10-05T04:00:00.000Z",
 "licenseType": "For-Hire-Vehicle Driver",
 "dmvStatus": "CURRENT",
 "dmvStatusChecked": "2014-11-05T04:00:00.000Z",
 "tlcStatus": "CURRENT",
 "tlcStatusChecked": "2014-11-05T04:00:00.000Z",
 "notes": "Updated notes",
 "created": "2014-10-01T12:00:00.000Z"
}

Delete Driver

DELETE /api/drivers/:licenseNumber

Soft-deletes a driver (marks as DELETED, does not remove from database).

Example request:

curl -X DELETE \
    -H "X-API-Key: your-api-key" \
    https://app.tcshub.com/api/drivers/123456

Example response (204 No Content) - empty body

Driver Field Descriptions

licenseNumber - TLC license number of the driver
licenseeName - Full name of the licensee on file with the TLC
licenseExpirationDate - Expiration date of the TLC license
licenseType - Type of license: FHV, Medallion
tlcStatus - Status of driver's TLC license: CURRENT or NOT CURRENT (NOT CURRENT indicates the license is suspended or revoked)
tlcStatusChecked - Timestamp indicating when the last status check was performed by our system
dmvStatus - Status of driver's DMV license: CURRENT or NOT CURRENT (NOT CURRENT indicates the license is suspended or revoked)
dmvStatusChecked - Timestamp indicating when the last status check was performed by our system
notes - Custom notes field for your internal use
created - Timestamp when the driver was added to your account

Vehicles API

List All Vehicles

GET /api/vehicles

Returns a list of all active vehicles in your account.

Example request:

curl -H "X-API-Key: your-api-key" \
    https://app.tcshub.com/api/vehicles

Example response (200 OK):

[
 {
   "licenseNumber": "V123456",
   "licenseeName": "ABC Transportation",
   "baseLicenseNumber": "B12345",
   "dmvLicensePlate": "ABC1234",
   "vin": "1HGBH41JXMN109186",
   "modelYear": "2015",
   "licenseExpirationDate": "2017-05-15T04:00:00.000Z",
   "dmvStatus": "CURRENT",
   "dmvStatusChecked": "2014-11-05T04:00:00.000Z",
   "tlcStatus": "CURRENT",
   "tlcStatusChecked": "2014-11-05T04:00:00.000Z",
   "notes": null,
   "created": "2014-10-01T12:00:00.000Z"
 }
]

Get Single Vehicle

GET /api/vehicles/:licenseNumber

Returns information for a specific vehicle.

Example request:

curl -H "X-API-Key: your-api-key" \
    https://app.tcshub.com/api/vehicles/V123456

Example response (200 OK):

{
 "licenseNumber": "V123456",
 "licenseeName": "ABC Transportation",
 "baseLicenseNumber": "B12345",
 "dmvLicensePlate": "ABC1234",
 "vin": "1HGBH41JXMN109186",
 "modelYear": "2015",
 "licenseExpirationDate": "2017-05-15T04:00:00.000Z",
 "dmvStatus": "CURRENT",
 "dmvStatusChecked": "2014-11-05T04:00:00.000Z",
 "tlcStatus": "CURRENT",
 "tlcStatusChecked": "2014-11-05T04:00:00.000Z",
 "notes": "Vehicle notes here",
 "created": "2014-10-01T12:00:00.000Z"
}

Create Vehicle

POST /api/vehicles

Creates a new vehicle in your account. The vehicle must exist in the TLC database.

Request body:

{
 "licenseNumber": "V123456",
 "notes": "Optional vehicle notes"
}

Example request:

curl -X POST \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{"licenseNumber": "V123456", "notes": "New vehicle"}' \
    https://app.tcshub.com/api/vehicles

Example response (201 Created):

{
 "id": 456,
 "accountID": 1,
 "status": "ACTIVE",
 "baseLicenseNumber": "B12345",
 "licenseNumber": "V123456",
 "licenseeName": "ABC Transportation",
 "dmvLicensePlate": "ABC1234",
 "vin": "1HGBH41JXMN109186",
 "modelYear": "2015",
 "licenseExpirationDate": "2017-05-15",
 "notes": "New vehicle",
 "created": "2014-10-01T12:00:00.000Z"
}

Example error responses:

400 Bad Request: {"error": "License number is required"}
400 Bad Request: {"error": "License number does not match any current TLC licensed vehicle"}
409 Conflict: {"error": "Vehicle already exists"}

Update Vehicle

PUT /api/vehicles/:licenseNumber

Updates an existing vehicle. Currently, only the notes field can be updated.

Request body:

{
 "notes": "Updated vehicle notes"
}

Example request:

curl -X PUT \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{"notes": "Updated notes"}' \
    https://app.tcshub.com/api/vehicles/V123456

Example response (200 OK):

{
 "licenseNumber": "V123456",
 "licenseeName": "ABC Transportation",
 "baseLicenseNumber": "B12345",
 "dmvLicensePlate": "ABC1234",
 "vin": "1HGBH41JXMN109186",
 "modelYear": "2015",
 "licenseExpirationDate": "2017-05-15T04:00:00.000Z",
 "dmvStatus": "CURRENT",
 "dmvStatusChecked": "2014-11-05T04:00:00.000Z",
 "tlcStatus": "CURRENT",
 "tlcStatusChecked": "2014-11-05T04:00:00.000Z",
 "notes": "Updated notes",
 "created": "2014-10-01T12:00:00.000Z"
}

Delete Vehicle

DELETE /api/vehicles/:licenseNumber

Soft-deletes a vehicle (marks as DELETED, does not remove from database).

Example request:

curl -X DELETE \
    -H "X-API-Key: your-api-key" \
    https://app.tcshub.com/api/vehicles/V123456

Example response (204 No Content) - empty body

Vehicle Field Descriptions

licenseNumber - TLC license number of the vehicle
licenseeName - Full name of the licensee on file with the TLC
baseLicenseNumber - Base license number associated with the vehicle
dmvLicensePlate - DMV license plate number
vin - Vehicle Identification Number
modelYear - Model year of the vehicle
licenseExpirationDate - Expiration date of the TLC license
tlcStatus - Status of vehicle's TLC license: CURRENT or NOT CURRENT (NOT CURRENT indicates the license is suspended or revoked)
tlcStatusChecked - Timestamp indicating when the last status check was performed by our system
dmvStatus - Status of vehicle registration with DMV: CURRENT or NOT CURRENT (NOT CURRENT indicates the vehicle registration is suspended or revoked)
dmvStatusChecked - Timestamp indicating when the last status check was performed by our system
notes - Custom notes field for your internal use
created - Timestamp when the vehicle was added to your account

Legacy Endpoints

For backward compatibility, the following legacy endpoints are still supported but deprecated:

GET /api/driver/:licenseNumber (use /api/drivers/:licenseNumber instead)
GET /api/vehicle/:licenseNumber (use /api/vehicles/:licenseNumber instead)

Please migrate to the new RESTful endpoints for all new integrations.