Enterprise

The Tuslr API makes it easy to tap into the digital mesh that runs across cities.   Make requests to our API endpoints and we’ll give you everything you need to create new and magical experiences for your users. The possibilities are endless!

All production API requests are made to:

https://api.Tuslr.com/

The current version of the API is v1.2.   Backwards incompatible changes will result in a version bump.   Some of our API endpoints require OAuth 2.0 credentials.   Please see the Authentication & Authorization guide to get started.

There is also a sandbox to use when developing and testing applications, with requests being made to:

https://sandbox-api.Tuslr.com/

¶ REST

The Tuslr API is a RESTful API.   This means that the API is designed to allow you to get, create, update and delete objects with the HTTP verbs GET, POST, PUT, PATCH, & DELETE.

¶ JSON

The Tuslr API speaks exclusively in JSON. This means that you should always set the Content-Type header to application/ Json to ensure that your requests are properly accepted and processed by the API.

¶ Authentication

All API calls require authentication using either a server token or bearer token depending on the endpoint.   Bearer tokens allow your application to access the Tuslr API on behalf of a user and are obtained after a user has authorized your application through one of the supported OAuth 2.0 authorization grants.   Bearer tokens are valid for authentication on all endpoints within the API.

For endpoints where user context is not necessary, such as GET /v1/products, you may use your application’s server token instead of having to authenticate a specific user.

Some endpoints such as Ride Request – Receipt require privileged scopes to be used in production by all Tuslr users.   For more information read about scopes.

¶ Cross-Origin Resource Sharing

The Tuslr API supports CORS for communicating from Javascript for these endpoints.   You will need to specify an Origin URI (found in the Settings tab under Security section) when creating your application to allow for CORS to be whitelisted for your domain.   Please note that your server_token is still considered sensitive and it is your responsibility to protect it.

var xhr = new XMLHttpRequest();

xhr.open(‘GET’, ‘https://api.Tuslr.com/v1.2/products?latitude=37.7759792&longitude=-122.41823’);

xhr.setRequestHeader(“Authorization”, “Token “);

xhr.send();

¶ Pagination

Some endpoints such as Rider History return a potentially lengthy array of objects.   In order to keep the response sizes manageable the API will take advantage of pagination.   Pagination is a mechanism for returning a subset of the results for a request and allowing for subsequent requests to “page” through the rest of the results until the end is reached.   Paginated endpoints follow a standard interface that accepts two query parameters, limit and offset and return a payload that follows a standard form.   These parameters names and their behavior are borrowed from PostgreSQL LIMIT and OFFSET keywords.

¶ Versioning

The Tuslr API is constantly being worked on to add features, make improvements, and fix bugs. This means that you should expect changes to be introduced and documented.   Whenever we make a significant change to an endpoint, we will increase the version number used in the path of the resource being requested.

However, there are some changes or additions that are considered backwards-compatible and your applications should be flexible enough to handle them.   These include:

Adding new endpoints to the API

Adding new attributes to the response of an existing endpoint

Changing the order of attributes of responses (JSON by definition is an object of unordered key/value pairs)

¶ Common Types

IDs in the Tuslr API are not guaranteed to be UUIDs and will be variable length.

Date and time will be expressed as an integer which represents the number of seconds since the Unix epoch in UTC.

Latitude and longitude will be expressed as floats, with the precision on both the request and response up to six decimal places.

Phone numbers will be expressed in E.164 format.

Country codes will be expressed as ISO 3166-1 alpha-3 code.

¶ HTTP Status Codes

Status Code  Description

200  OK.   Everything worked as expected.

201  Created.   We will return a 201 after a successful POST where a resource was created.

302  Retry request on given redirect URI.

400  Malformed request.

401  Unauthorized.   The request requires user authentication (not logged in).   Also used for invalid OAuth 2.0 credentials.

403  Forbidden.   Also used for unauthorized requests such as improper OAuth 2.0 scopes or permissions issues.

403  User not allowed.   User is banned and is not permitted to request a ride.

404  Not found.

406  Unacceptable content type.   Client sent an accepts header for a content type which does not exist on the server.   Body includes a list of acceptable content types, such as “Unacceptable content type. Request resource as: application/json.

409  A conflict needs to be resolved before the request can be made.

422  Invalid request.   The request body is parse-able however with invalid content or there are issues with a rider’s user account.

429  Too Many Requests.   Exceeded the rate limit for requests.

500  Internal Server Error.

503  The backend server is not available.

¶ Errors

Error responses will have a consistently formed JSON body.   The keys may include:

Key  Value

message  Human readable message which corresponds to the client error.

code  Underscored delimited string.

fields (optional)  A hash of field names that have validations. This has a value of an array with member strings that describe the specific validation error.

¶ Error Response

Status-Code: 422 Invalid Request

{

  “message”: “Invalid user”,

  “code”: “invalid”,

  “fields”: {

    “first_name”: [“Required”]

  }

}

¶ API Endpoints

Method  Endpoint  Description

GET  /products  List products

GET  /products/{product_id}  Get product details

GET  /estimates/price  Get price estimates

GET  /estimates/time  Get time estimates

GET  /me  Get user information

PATCH  /me  Apply a user promotion

GET  /history  Get user history

GET  /places/{place_id}  Get a saved place

PUT  /places/{place_id}  Update a saved place

POST  /requests/estimate  Get request estimate

POST  /requests  Create ride request

GET  /requests/{request_id}  Get ride details

DELETE  /requests/{request_id}  Cancel request

PATCH  /requests/{request_id}  Update request

GET  /requests/{request_id}/map  Get tracking map

GET  /requests/{request_id}/receipts  Get receipt Tuslr