API Conventions
6 min
base urls base urls are provided per environment and per location refer to the relevant location section for the specific base url applicable to your integration versioning the cabfare connect api is versioned the current version is v0 5 0 the api version is included in the base url path when a new version is released, the previous version will remain available for a transition period cabfare will notify integration partners of version changes with sufficient lead time to update their implementations request format all requests must use https include the content type application/json header include the x api key and x api secret authentication headers send request bodies as valid json response codes cabfare connect uses standard http status codes to indicate the outcome of every request code meaning common cause 200 ok request successful, response body contains data ping, subsidy validation, trip end with subsidy 202 accepted request accepted with a notable condition trip start where driver subsidy scheme status is not valid 204 no content request accepted, no response body driver logout, link request accepted, trip end without subsidy 400 bad request malformed or invalid request payload missing required fields, incorrect data types, invalid enum values 401 unauthorized missing or invalid credentials missing or incorrect x api key or x api secret 403 forbidden authenticated but operation not permitted driver or vehicle not authorised for subsidy scheme trips 404 not found referenced resource not found unknown device id, driver not currently logged in 409 conflict active session already exists duplicate tripid , existing active trip for vehicle 500 server error internal cabfare connect error contact support\@cabfare com mailto\ support\@cabfare com error response format for 4xx responses, cabfare connect returns a structured error body to help identify the cause { "status" 400, "error" "bad request", "detail" \[ { "field" "driverid", "message" "must not be blank" } ] } inspect the detail array for specific field level errors when troubleshooting a 400 response currency format all monetary amounts in cabfare connect are expressed in cents as integers, not dollars as floats a fare of $10 00 must be submitted as 1000 this applies to all fare amounts, subsidy amounts, lifting fees, and payment amounts across all endpoints identifiers the following identifiers must be consistent across all api calls within a session identifier description taximeterid unique identifier for the taxi meter device or system terminalid unique identifier for the payment terminal device or application driverid unique identifier for the accredited driver vehicleplate registered vehicle plate number tripid unique identifier for a single trip — must be unique per trip transactionid unique identifier for a single payment transaction inconsistent identifiers across the taxi meter and payment terminal are the most common cause of linking failures and session errors