DotTransfers API

Book ground transportation services on demand with our APIs RESTFul.

The RESTFul DotTransfers APIs will help you to develop your ground transportation platform worldwide. We developed a booking system based in APIs for developers to create or integrate a comprehensive solution to book ground transportation services into your system, site or application.

Our APIs allows you to:

  • Get geo-locations by user text search.

  • Get the list of available vehicles in the area and their rates.

  • Booking transfers services.

  • Cancel reservations.

  • Check reservations and their status.

  • Get passengers recent locations.

  • Request quotes.

  • Register new affiliates.


Start trying the APIs using our interactive panel

Get a trial AccessToken now

Integrate your business with our services

Get a production ApiKey now

Rest Basics

General information

Find information about how we build and version our REST APIs, how to use the APIs, and about useful bits.

DotTransfers advisories

Our REST API technical documentation contains confidential and proprietary information belonging to DotTransfers, which cannot be used or disclosed by you for any purpose other than those purposes that are expressly authorized by DotTransfers in your written agreement with DotTransfers.

When authentication is performed using a test token, the rates shown are not real.

Security

All request and response exchanges are sent over HTTPS.

All security is based on SSL and a valid authentication token.

API standards

DotTransfers REST APIs use the data structures that JavaScript Object Notation (JSON) defines for its data-interchange format. Our REST APIs strictly define values that you can pass as request parameters. The API descriptions identify the data type for each parameter in the request and all data types in the responses. For more information, see json.org.

API version strategy

Each of our REST APIs are versioned. When any of these APIs are called, an application must include the API version in the request URI, in the form of vn, where n represents the version number.

Example

http://api.dottransfers.com/v1/locations?query=jfk

Version compatibility

  • Changes to existing API versions. An existing API version will receive fixes and minor changes that expose new behavior when the changes are backward compatible and do not impact clients negatively.

  • New API versions. A new API version will be added when new functionality and major changes are not backward compatible.

  • Multiple concurrent versions. DotTransfers will maintain multiple concurrent versions of an API. Before a version becomes obsolete, DotTransfers will provide adequate notification before removing the version from service.

Endpoints and URIs

To see the complet list of the URIs, use the interactive panel.

Request method and URI format

The request URL and URI structure for DotTransfers REST APIs conform to standard HTTP 1.1 request format.

The structure of the URI and URL use these basic formats:

  • URIs with request parameters.

  • URIs with variables.

URIs with request parameters

Basic structure example:

v1/locations?query=jfk

Where:

/v1 is the individual API release version.

/locations is the URI of a requested object or resource.

query=jfk is the parameter and value pair (jfk is the IATA code for John F. Kennedy International Airport).

URIs with variables

Basic structure example:

v1/bookings/services/{serviceCode}

URI variables are shown in curly braces ({ }). You must replace the variable information with a value. In the preceding example, replace the whole word (including the curly braces) with a transfer service code, such as 3775.

Method and URL example

GET http://api.dottransfers.com/v1/locations?query=jfk

Where:

GET is the HTTP method. The HTTP method is the verb that performs the action on the resource in the URI.

https://api.dottransfers.com/v1 is the base URL.

Autentication and Authorization

Authentication

To use DotTransfers' API you need an AcessToken in order to be authenticated in our system. There are two ways to get an AccessToken: requesting for a trial AccessToken or registering as an integrator in our system and generating an ApiKey and with this, get a Production AccessToken.

How to get a trial AccessToken

  1. Request for a trial AccessToken:

    Get a trial AccessToken now


  2. Copy the generated AccessToken to use it from our interactive panel or from a test application.

    The AccessToken obtained will be valid for 6 months or 100 hits. When authentication is performed using a trial AccessToken, the rates shown are not real.

How to get a Production AccessToken

  1. Create an account in our system:

    Create an account now...


  2. You will get an e-mail with the instructions on how to get you ApiKey.



  3. From your application, get an AccessToken calling the following method.

    The AccessToken will be valid for 12 hours.
    Request
    POST /auth/accessToken
    Content-Type:application/json
    {
      "apiKey": "yourProductionApiKey"
    }
    Response
    {
      "token": "yourProductionAccessToken",
      "expiresIn": null,
      "maxHits": null
    }
  4. Save this AccessToken in your application. You will also be able to use it from our interactive panel

Authorization

To use the DotTransfers' API operations, the client must send into every request's header the AccessToken, obtained from the /auth/accessToken method.

Request
GET http://api.dottransfers.com/v1/locations?query=MCO
Access-Token:yourProductionAccessToken

Status codes and errors

Common HTTP status codes

After your request is processed, the HTTP servers return a response with an HTTP status code. The following table shows common status codes.

Code Status Description
200 OK Operation successful.
204 OK Operation successful with no content.
400 Bad Request Request invalid or incomplete.
401 Unauthorized Incorrect or no credentials found in header.
403 Forbidden Operation not allowed due to violation of business rules.
404 Not Found Requested resource not found.
500 Internal Server Error Server encountered and internal error while attempting to process the request. The response body will include a unique identifier that we can use to help locate the problem.
503 Service Unavailable Servers are up but busy at the moment. Try again later.

Application error format

Application or business errors are returned when an API call fails because of incorrect or missing request parameters, incorrectly formatted or missing values, operation not allowed due to violation of business rules, or when the service cannot find results to fulfill a request. These errors occur during authentication requests, authenticated API calls, or call processing.

The call, responds with the apropiate HTTP status code with a statusMessage containing extra data of the error.

The error response is a single object statusMessage.

{
  "descrip": "BadRequest",
  "code": "400",
  "errorUniqueId": "ac97b9cf6def43febeec51a7abc665e0",
  "errorCode": "",
  "timeStamp": "2014-11-05T02:51:08.4539735Z",
  "message": "Validation failed for one or more entities. See 'ValidationErrors' from for more details.",
  "messageDetail": "",
  "validationErrors": {
    "accessTokenRequest": "Parameter \"accessTokenRequest\" was not specified.\r\n"
  }
}
Important: Error messages are not localized and are intended to be references for the developer. They shouldn't be displayed directly to the user.

Suppress response codes

If your application does not support HTTP status codes, you can add suppress_response_codes parameter at the end of the URL in the request and this will always return a 200 HTTP status code (although there was an error) but in the property statusMessage.code will contain the real HTTP code.
POST http://api.dottransfers.com/v1/bookings/services&suppress_response_codes

Links Nodes

DotTransfers REST APIs implements HATEOAS (Hypermedia as the Engine of Application State). Client applications can interact with these links by using hypermedia that the DotTransfers servers provide dynamically. Our REST APIs include a Links node in every resource.

Example

The GET method of services resource , responds with the following links:

{
  "code": "775",
  "scheduleDate": "2014-12-20T17:30:00",
  "serviceType": "PTP",
  ...
  "passenger": {
    "firstName": "Pan",
    "lastName": "Peter",
    "eMail": "peterpan@dot.com",
    "phone": null,
    "cellPhone": null
  },
  "passengerCount": 1,
  "luggageCount": 1,
  "freeCancellationDueDate": "2014-12-20T18:30:00",
  "links": [
    {
      "rel": "self",
      "hRef": "http://api.dottransfers.com/v1/bookings/services/775"
    },
    {
      "rel": "cancel",
      "hRef": "http://api.dottransfers.com/v1/bookings/services/775/freecancellations"
    }
  ]
}

The self link is the complete URL of the request that generated the response.
The cancel link is the complete URL to cancel the service.

Interactive Panel

DotTransfer provides an interactive panel with which you can test the APIs, see the parameters and the definitions of the request and response classes, and the error list.

You can use it with a trial or production AccessToken:
Interactive Panel

Getting Started

Using DotTransfers APIs is cost-free. Visit DotTransfers… for further commercial information.

First thing to be made to be able to use DotTransfers' API is to get an AcessToken in order to be authenticated in our system. There are two ways to get the AccessToken: requesting for a trial AccessToken or registering as an integrator in our system and generate an ApiKey and with this, get a Production AccessToken.

How to get a trial AccessToken

  1. Request for a trial AccessToken

    Get a trial AcessToken now…


  2. Copy the generated AccessToken to use it from our interactive panel or from a test application.

    The AccessToken obtained will be valid for 6 months or 100 hits. When authentication is performed using a trial AccessToken, the rates shown are not real.

How to get a Production AccessToken

  1. Create an account in our system:

    Create an account now...


  2. You will get an email with the instructions on how to get you ApiKey.



  3. You will get an e-mail with the instructions on how to get you ApiKey.

    The AccessToken will be valid for 12 hours.
    Request
    POST /auth/accessToken
    Content-Type:application/json
    {
      "apiKey": "yourProductionApiKey"
    }
    Response
    {
      "token": "yourProductionAccessToken",
      "expiresIn": null,
      "maxHits": null
    }
  4. Save this AccessToken in your application. You will also be able to use it from our interactive panel

How to book a transfer

The main goal of DotTransfers APIs is to allow you to book transfers worldwide. We will show you the steps to book a transfer with the folling example:

  1. Get the list of available vehicles and rates for a transfer from a hotel to an airport:

    Request
    GET http://api.dottransfers.com/v1/bookings/ratedservices?scheduleDate=2014-12-17T18:30&originSearchText=miami+beach+resort+%26+spa&destinationSearchText=mia
    Access-Token:yourProductionAccessToken
    Response
    [
      {
        "scheduleDate": "2014-12-17T18:30:00",
        "scheduleDateUtc": "2014-12-17T23:30:00Z",
        "vehicle": {
          "category": "STD",
          "descrip": "Standard Sedan",
          "obs": "Standard Sedan",
          "imageUrl": "http://app.dottransfers.com/UsrDocuments/Suppliers/Images/VehiclesTypes/VehCate_1_US.jpg",
          "maxPax": 3,
          "maxLuggage": 2,
          "features": "|AC|Airport Meet & Greet|Chofer profesional|Celular|",
          "featuresIds": "|31|33|34|36|",
          "finalRate": 103.15,
          "quantity": 1,
          "minimumTimeRequired": 180
        },
        "rutePoints": [
          {
            "action": "PU",
            "order": 0,
            "location": {
              "name": "Miami Beach Resort & Spa, Collins Avenue, Miami Beach, FL, United States",
              "address": "4833 Collins Ave, Miami Beach, FL 33140, United States",
              "address2": null,
              "summary": "Miami Beach Resort & Spa, 4833 Collins Ave, Miami Beach, FL 33140, United States",
              "countryCode": "US",
              "latitude": "25.823953",
              "longitude": "-80.121568",
              "category": "establishment",
              "isConcrete": "yes",
              "searchText": null,
              "objectToken": null,
              "timeZone": {
                "timeZoneId": "America/New_York",
                "timeZoneName": "Eastern Standard Time",
                "rawOffset": -18000,
                "dstOffset": -14400
              }
            },
            "flight": null
          },
          {
            "action": "DO",
            "order": 1,
            "location": {
              "name": "Miami International Airport (MIA)",
              "address": "Miami, Florida, United States",
              "address2": null,
              "summary": "Miami International Airport (MIA) - Miami, Florida, United States",
              "countryCode": "US",
              "latitude": "25.7931995391846",
              "longitude": "-80.2906036376953",
              "category": "airport;establishment",
              "isConcrete": "yes",
              "searchText": null,
              "objectToken": null,
              "timeZone": null
            },
            "flight": null
          }
        ],
        "timeRequired": 0,
        "roundTrip": "no",
        "serviceType": "PTP",
        "objectToken": "08eb9a4f492e4c23b8fbcd73cd93c327",
        "links": []
      }
    ]
  2. Insert the booking. For this, you must send the requester and passenger data, and the ratedService.objectToken obtained in previous request. This token contains data from a rated transfer service that include the schedule date, vehicle type, rate and the rute points as a unity.

    Request
    POST http://api.dottransfers.com/v1/bookings/services
    Access-Token:yourProductionAccessToken
    {
      "requester": {
        "firstName": "Peter",
        "lastName": "Pan",
        "email": "peterpan@dot.com",
        "phone": "",
        "title": "Sr",
        "languageCode": "en"
      },
      "serviceRequest": [
        {
          "passenger": {
            "company": none,
            "firstName": "Peter",
            "lastName": "Pan",
            "email": "peterpan@dottransfers.com",
            "phone": "",
            "cellPhone": "",
            "title": "Sr",
            "languageCode": "en"
          },
          "passengerCount": "1",
          "luggageCount": "1",
          "comments": "",
          "ratedServiceObjectToken": "08eb9a4f492e4c23b8fbcd73cd93c327",
          "flight": null,
          "complementaryAddressData": null
        }
      ]
    }
    Response
    [
      {
        "code": "7315",
        "scheduleDate": "2014-12-17T18:30:00",
        "scheduleDateUtc": "2014-12-17T23:30:00Z",
        "serviceType": "PTP",
        "rutePoints": [
          {
            "action": "PU",
            "order": 0,
            "location": {
              "name": "Miami Beach Resort & Spa, Collins Avenue, Miami Beach, FL, United States",
              "address": "4833 Collins Ave, Miami Beach, FL 33140, United States",
              "address2": null,
              "summary": "Miami Beach Resort & Spa, 4833 Collins Ave, Miami Beach, FL 33140, United States",
              "countryCode": "US",
              "latitude": "25.823953",
              "longitude": "-80.121568",
              "category": "establishment",
              "isConcrete": "yes",
              "searchText": null,
              "objectToken": null,
              "timeZone": {
                "timeZoneId": "America/New_York",
                "timeZoneName": "Eastern Standard Time",
                "rawOffset": -18000,
                "dstOffset": -14400
              }
            },
            "flight": null
          },
          {
            "action": "DO",
            "order": 1,
            "location": {
              "name": "Miami International Airport (MIA)",
              "address": "Miami, Florida, United States",
              "address2": null,
              "summary": "Miami International Airport (MIA) - Miami, Florida, United States",
              "countryCode": "US",
              "latitude": "25.793199539184",
              "longitude": "-80.29060363769",
              "category": "airport;establishment",
              "isConcrete": "yes",
              "searchText": null,
              "objectToken": null,
              "timeZone": null
            },
            "flight": null
          }
        ],
        "timeRequired": 0,
        "passenger": {
          "company": null,
          "firstName": "Peter",
          "lastName": "Pan",
          "eMail": "peterpan@dottransfers.com",
          "phone": "",
          "cellPhone": "",
          "title": "Sr",
          "languageCode": "en"
        },
        "passengerCount": 1,
        "luggageCount": 1,
        "roundTrip": "no",
        "comments": "",
        "vehicle": {
          "category": "STD",
          "descrip": "Standard Sedan",
          "obs": "Standard Sedan",
          "imageUrl": "http://app.dottransfers.com/UsrDocuments/Suppliers/Images/VehiclesTypes/VehCate_1_US.jpg",
          "maxPax": 3,
          "maxLuggage": 2,
          "features": "|AC|Airport Meet & Greet|Chofer profesional|Celular|",
          "featuresIds": "|31|33|34|36|",
          "finalRate": 103.15,
          "quantity": 1,
          "minimumTimeRequired": 180
        },
        "status": "Online Payment pending",
        "freeCancellationDueDate": "2014-12-17T21:30:00Z",
        "paymentGatewayUrl": "https://redapp.dottransfers.com/paygateway/Default.aspx?enc=3i6VYsQS5uB9N",
        "paymentConfirmationCode": "",
        "links": [
          {
            "rel": "self",
            "hRef": "http://api.dottransfers.com/v1/bookings/services/7315"
          },
          {
            "rel": "cancel",
            "hRef": "http://api.dottransfers.com/v1/bookings/services/7315/freecancellations"
          }
        ]
      }
    ]
The booking will be inserted but will be in the "Online Payment pending" status. The response contains a link to redirect the user to the payment gateway.

Documentation

Auth operations

Obtaining an AccessToken

To use DotTransfers' API you need an AcessToken in order to be authenticated in our system. DotTransfers APIs uses an ApiKey to identify your acount. You need an ApiKey to get a production AccessToken.

HTTP method and endpoint

POST /auth/accessToken

Interactive Panel

To try it or see the parameters and errors' list, use our interactive panel.

Example

This example gets an AccessToken.

Request
POST http://api.dottransfers.com/v1/auth/accessToken
Content-Type:application/json
{
  "apiKey": "yourProductionApiKey"
}
Response
{
  "token": "yourProductionAccessToken",
  "expiresIn": 720,
  "maxHits": null
}

Usage Notes

To use the dotTransfer's API operations, the client must send the AccessToken into every request header.

GET http://api.dottransfers.com/v1/locations?query=MCO
Access-Token:yourProductionAccessToken

Error response

For more information about HTTP status codes and error response formats, see Status codes and errors.

Verb Response ErrorCode Reason
POST 401 Unauthorized Access denied because an invalid, inactive or removed ApiKey.
POST 401 Unauthorized ERR.USR.INVALIDCREDENTIALS Access denied because user not found or incorrect password.

Locations operations

Geolocate locations

Gets a list with one or many geolocated locations resulting from a query made through search by text. Geocoding is the process of converting addresses (like "1600 Amphitheatre Parkway, Mountain View, CA") into geographic coordinates (like latitude 37.423021 and longitude -122.083739). These geolocated locations are required and used as origin and destination when obtaining rates in the booking operations (ratedServices).

The search text can be:

  • Airport Name
  • Airport IATA code
  • Hotel name
  • Establishment name (theatre, hospital, etc.)
  • A simple address
  • A complete address

The more precise the search text is, the more precise will be the result. For example, if the search text is “airports florida”, the result will be all the airports in Florida. If the search text is MCO (IATA's code for Orlando International Airport) you will get the exact result.

Example

Search text Response description
MCO Gets Orlando International Airport.
airports florida Gets all airports in Florida, United States.
miami beach resort & spa, miami Gets the exact hotel address.
miami beach resort Gets a list of establishments with that name all over the world.
4833 Collins Ave Gets different geolocations with that name since the same address could be found in different cities.
4833 Collins Ave, miami beach, FL Gets only one geolocation for this address.

Use this API when you wish to give to the user the option of searching and/or geolocating an origin and a destination for then using them to get service rates for that transfer.

HTTP method and endpoint

GET /locations

Interactive Panel

To try or see the parameters and errors' list, use our Interactive Panel

Request
GET http://api.dottransfers.com/v1/locations?query=MCO
Response
[
  {
    "name": "Orlando International Airport (MCO)",
    "address": "Orlando, Florida, United States",
    "address2": null,
    "summary": "Orlando International Airport (MCO) - Orlando, Florida, United States",
    "countryCode": "US",
    "latitude": "28.4293994903564",
    "longitude": "-81.3089981079102",
    "category": "airport;establishment",
    "isConcrete": "yes",
    "objectToken": "779547971e3542ab8e0634fe3483afae"
  }
]

Usage notes

  • If when calling locations only one result is obtained, you will be able to use it directly to obtain rates. If more than one result is obtained, you will need to show it to the users for them to select a result or ask for more precise information for the search text in order to refine the search.

    The category property of a locationInfo object contains the description of the category resulting from the geolocation of a location. A locationInfo object might contain one or many categories.

    This property is important since, depending on each category and if it is used to define the origin of a transfer, it determines if a request of additional information to the user before booking will be needed. For example, if the resulting category is airport, the request of the flight information such as airline, flights number, etc. will be needed.
    Possible Values
    Category Notes
    airport If the locationInfo is used as origin of the transfer, it requires the flight information in order to book a transfer.
    establishment It does not require additional information to book a transfer, unless the passenger specifies it.
    street_address If the locationInfo is used as origin of the transfer, it requires specifying additional contact information, such as floor, office, etc.
    political This category is filtered.
  • The call to locations only returns the concrete locations where a driver can contact the passenger. For example, an address or a hotel are concrete locations, but for the opposite, a country or city are not.
  • The property objectTokenis an identifier that represents an object stored in the cache of our system to prevent that the object's information is altered. When the APIs require it, instead of sending or assigning an object, an objectTokenwill need to be assigned, and then the API will recover that object in its original status.
  • The objectTokenof the locationInfo are required, as one of its variables of query of origin and/or destination, to request for rates of transfer services.

Booking Operations

The booking API's operations will let you query transfer service rates, vehicle availability, make reservations from transfer services, and make queries and cancellations.

  • Search for Rates (rated services)
  • Book a Transfer Service
  • Get a Service
  • Cancel a Service

This method returns a list of different vehicle categories with their features and rates that can perform the passenger's transfer, either from point to point (from an origin to a destination), or at disposal (from a specific origin and for the time required) at a specific date and time.
We call this data "rated service" (ratedService). A ratedService contains data of a rated transfer service that includes the scheduled date, vehicle's category and features, rates and route points for the service, as a unity.
The ratedService is required for booking.

This method requires three parameters:

  • A date (necessary to know when will the pick up be).
  • An origin (necessary to know where will the pick up be)
  • A destination, or time of use (with this data, in addition to the date and origin, we can find the available vehicles list and their rates for this trip).

There are different ways to specify an origin and a destination. The following table shows the description of each of them and their possible combinations to send them as parameters for this method:

From any of this:

Origin Description
originLat, originLng Defines an origin through the inverse geocoding of the specified geographic coordinates (latitude and longitude).
originSearchText Defines an origin through the geocoding of the address specified by text.
NOTE: If the geoconding's result contains only one location, is taken as a valid origin. If the result does not contain a location or has more than one, is taken as invalid origin.
originSearchText Defines an origin through an objectoToken that corresponds to a locationInfo previously geolocalized by the method GET /locations.

To any of this:

Destination Description
destinationLat, destinationLng Defines a destination through the inverse geocoding of the specified geographic coordinates (latitude and longitude).
destinationSearchText Defines a destiny through the geocoding of the address specified by text.
NOTE: If the geocoding's result contains only one location, is taken as a valid origin. If the result does not contain a location or has more than one, is taken as invalid destination.
destinationObjectToken Defines a destination through an objectoToken that corresponds to a locationInfo, previously geolocalized by the method GET /locations.
time Defines a disposal transfer service.

Suitability

Use this method when you have data of origin, destination or time at disposal of the trip you would like to make and wish to request for rates and vehicles available for that service, in order to make a booking then.


HTTP method and endpoint

GET /bookings/ratedservices

Parameters

  • scheduleDate
  • originLat
  • originLng
  • originSearchText
  • originObjectToken
  • destinationLat
  • destinationLng
  • destinationSearchText
  • destinationObjectToken
  • time

Interactive Panel

To try it or see the parameters and errors' list, use our interactive panel.

Example

This example searches for vehicles and rates of a transfer from the "miami beach resort & spa" to the Miami International Airport.

Request
GET http://api.dottransfers.com/v1/bookings/ratedservices?scheduleDate=2014-12-17T18:30&originSearchText=miami+beach+resort+%26+spa&destinationSearchText=mia
Access-Token:yourProductionAccessToken
Response
[
  {
    "scheduleDate": "2014-12-17T18:30:00",
    "scheduleDateUtc": "2014-12-17T23:30:00Z",
    "vehicle": {
      "category": "STD",
      "descrip": "Standard Sedan",
      "obs": "Standard Sedan",
      "imageUrl": "http://app.dottransfers.com/UsrDocuments/Suppliers/Images/VehiclesTypes/VehCate_1_US.jpg",
      "maxPax": 3,
      "maxLuggage": 2,
      "features": "|AC|Airport Meet & Greet|Chofer profesional|Celular|",
      "featuresIds": "|31|33|34|36|",
      "finalRate": 103.15,
      "quantity": 1,
      "minimumTimeRequired": 180
    },
    "rutePoints": [
      {
        "action": "PU",
        "order": 0,
        "location": {
          "name": "Miami Beach Resort & Spa, Collins Avenue, Miami Beach, FL, United States",
          "address": "4833 Collins Ave, Miami Beach, FL 33140, United States",
          "address2": null,
          "summary": "Miami Beach Resort & Spa, 4833 Collins Ave, Miami Beach, FL 33140, United States",
          "countryCode": "US",
          "latitude": "25.823953",
          "longitude": "-80.121568",
          "category": "establishment",
          "isConcrete": "yes",
          "searchText": null,
          "objectToken": null,
          "timeZone": {
            "timeZoneId": "America/New_York",
            "timeZoneName": "Eastern Standard Time",
            "rawOffset": -18000,
            "dstOffset": -14400
          }
        },
        "flight": null
      },
      {
        "action": "DO",
        "order": 1,
        "location": {
          "name": "Miami International Airport (MIA)",
          "address": "Miami, Florida, United States",
          "address2": null,
          "summary": "Miami International Airport (MIA) - Miami, Florida, United States",
          "countryCode": "US",
          "latitude": "25.7931995391846",
          "longitude": "-80.2906036376953",
          "category": "airport;establishment",
          "isConcrete": "yes",
          "searchText": null,
          "objectToken": null,
          "timeZone": null
        },
        "flight": null
      }
    ],
    "timeRequired": 0,
    "roundTrip": "no",
    "serviceType": "PTP",
    "objectToken": "08eb9a4f492e4c23b8fbcd73cd93c327",
    "links": []
  }
]

Usage Notes

When to use originLat y originLng and/or destinationLat and destinationLng? Use these parameters if:

  • Your application allows the user to select origin and destination in a map and get the geographic coordinates.
  • You already have the geographic coordinates of origin and destination from another service or a database.
  • Your application can access the GPS and take the user's location as origin.

When to use originSearchText and/or destinationSearchText? Use these parametes if:

  • Your application has a preloaded list with the IATA codes and allows you to select one of this for origin as well as destination.
  • If your application asks the user to enter the IATA code of an airport for origin as well as destination.
  • If you have a complete and exact location´s postal address, including city and country.
With these parameters, the GET ratedServices method will try to geocodify according to the search text. If the geocoding result contains only one location, it is taken as a valid point. If the result does not contain a location or has more than one, it is taken as an invalid point.

When to use originObjectToken and/or destinationObjectToken? Use these parameters if:

  • Your application allows the user to search for a location with the GETlocations method through a search text that returns a list of suggestions according to that text, and then allows selecting one of the resulting locationInfo (if more than one result is obtained). To assign a locationInfo as origin or destination you must assign the property locationInfo.objectToken as a parameter.

When to use time? Use this parameter when:

  • Your application allows the user to select “time” when willing to have a vehicle at disposal.
If you use the parameter time it requires assigning an origin with any of the parameters.

Error response

For more information about HTTP status codes and error response formats, see Status codes and errors.

Verb Response ErrorCode Reason
GET 404 Not Found ERR.USR.SAVEDLOCATIONNOTFOUND SavedLocation not found.

Book a Transfer Service (services)

It allows to generate a booking of transfer service.

For this, you must set the requester and passenger data, and the ratedService.ObjectToken obtained in the GET /bookings/ratedServices. This token contains data from a rated transfer service that includes the scheduled date, vehicle type, rate and the route points as a unity.

After using this method, the booking will be inserted but it will be in the "Online Payment Pending" status. The response contains a link that redirects the user to the payment gateway. For further information, please view Payment documentation.

The reservation can be cancelled any time. A cancellation may be with charge or not. This will depend on the cancellation date and the property value service.freeCancellationDueDate. The property value service.freeCancellationDueDate varies according to the transfer's origin and the vehicle category. For further information, please view Cancel a Service.

Service Status

After inserting a transfer service in our system, it will go through different status. The following table describes the different transfers' states.

StatusCode Status Description
PaymentPending Online Payment pending The reservation has been generated but the payment is pending.
PaymentExpired Online Payment expired The limit time to pay for the Reservation has expired. The reservation has been cancelled.
Reserved Reserved The Reservation is confirmed.
CancelledSupplier Cancelled by Supplier The service provider has cancelled the reservation.
CancelledRequesterFree Cancelled by requester The requester has cancelled the reservation (free of charge).
CancelledRequesterCost Cancelled by requester (with cost) The requester has cancelled the reservation (with charges).
InProgres In progres When the driver is on the way to pick the passengers up.
WithPax With Passenger When driver and passenger meet and are on the way to the destination place.
NoShow No Show When the driver is at the origin place but the passenger is not there.
CancelledInProgressSupplier Cancelled in progress (by Supplier) When the driver is on the way to pick the passenger up but had to cancel the service for any technical or traffic problem, or bad weather conditions.
CancelledInProgressPax Cancelled in progress (by Passenger) When driver and passenger meet at the origin place, but the passenger decides not to use the service.
Realized Realized When the driver leaves the passenger at the destination, or the trip finishes.
Down Down The Reservation has been generated but none of the service providers accepted the service for any inconsistency or for lack of availability. An agent will contact the passenger to explain the reason and find a solution.

ComplementaryAddressData and Flight

  • If the locationInfo of the transfer's origin category is "street_address" the property complementaryAddressData must be set with more precise contact data such as floor, apartment or office number, etc. Otherwise, assign the property flight must be set to null.
  • If the locationInfo of the transfer's origin contains the category “airport”, the propery flight must be set with the flight information such as airline, flights number, etc. Otherwise, assign the property flight must be set to null.
To know the category of the origin's locationinfo, you must read the ratedServices.rutePoints[0].location.category property, obtained previously with the GET /bookings/ratedServices method.

Suitability

Use this method to confirm and insert a transfer booking after asking to the user the origin and destination/time, selected the vehicle and its rates (ratedService) and asking the requester and passenger data.

HTTP method and endpoint

POST /bookings/services

Parameters

  • serviceRequest (body)

Interactive Panel

To try it or see the parameters and errors' list, use our interactive panel.

Example

This example inserts a new transfer service with a ratedService.ObjectToken that represent a ratedService with a trip from a hotel to the MIA airport.

Request
POST http://api.dottransfers.com/v1/bookings/services
Access-Token:yourProductionAccessToken
{
  "requester": {
    "firstName": "Peter",
    "lastName": "Pan",
    "email": "peterpan@dot.com",
    "phone": "",
    "title": "Sr",
    "languageCode": "en"
  },
  "serviceRequest": [
    {
      "passenger": {
        "company": none,
        "firstName": "Peter",
        "lastName": "Pan",
        "email": "peterpan@dottransfers.com",
        "phone": "",
        "cellPhone": "",
        "title": "Sr",
        "languageCode": "en"
      },
      "passengerCount": "1",
      "luggageCount": "1",
      "comments": "",
      "ratedServiceObjectToken": "08eb9a4f492e4c23b8fbcd73cd93c327",
      "flight": null,
      "complementaryAddressData": null
    }
  ]
}
Response
[
  {
    "code": "7315",
    "scheduleDate": "2014-12-17T18:30:00",
    "scheduleDateUtc": "2014-12-17T23:30:00Z",
    "serviceType": "PTP",
    "rutePoints": [
      {
        "action": "PU",
        "order": 0,
        "location": {
          "name": "Miami Beach Resort & Spa, Collins Avenue, Miami Beach, FL, United States",
          "address": "4833 Collins Ave, Miami Beach, FL 33140, United States",
          "address2": null,
          "summary": "Miami Beach Resort & Spa, 4833 Collins Ave, Miami Beach, FL 33140, United States",
          "countryCode": "US",
          "latitude": "25.823953",
          "longitude": "-80.121568",
          "category": "establishment",
          "isConcrete": "yes",
          "searchText": null,
          "objectToken": null,
          "timeZone": {
            "timeZoneId": "America/New_York",
            "timeZoneName": "Eastern Standard Time",
            "rawOffset": -18000,
            "dstOffset": -14400
          }
        },
        "flight": null
      },
      {
        "action": "DO",
        "order": 1,
        "location": {
          "name": "Miami International Airport (MIA)",
          "address": "Miami, Florida, United States",
          "address2": null,
          "summary": "Miami International Airport (MIA) - Miami, Florida, United States",
          "countryCode": "US",
          "latitude": "25.793199539184",
          "longitude": "-80.29060363769",
          "category": "airport;establishment",
          "isConcrete": "yes",
          "searchText": null,
          "objectToken": null,
          "timeZone": null
        },
        "flight": null
      }
    ],
    "timeRequired": 0,
    "passenger": {
      "company": null,
      "firstName": "Peter",
      "lastName": "Pan",
      "eMail": "peterpan@dottransfers.com",
      "phone": "",
      "cellPhone": "",
      "title": "Sr",
      "languageCode": "en"
    },
    "passengerCount": 1,
    "luggageCount": 1,
    "roundTrip": "no",
    "comments": "",
    "vehicle": {
      "category": "STD",
      "descrip": "Standard Sedan",
      "obs": "Standard Sedan",
      "imageUrl": "http://app.dottransfers.com/UsrDocuments/Suppliers/Images/VehiclesTypes/VehCate_1_US.jpg",
      "maxPax": 3,
      "maxLuggage": 2,
      "features": "|AC|Airport Meet & Greet|Chofer profesional|Celular|",
      "featuresIds": "|31|33|34|36|",
      "finalRate": 103.15,
      "quantity": 1,
      "minimumTimeRequired": 180
    },
    "status": "Online Payment pending",
    "freeCancellationDueDate": "2014-12-17T21:30:00Z",
    "paymentGatewayUrl": "https://redapp.dottransfers.com/paygateway/Default.aspx?enc=3i6VYsQS5uB9N",
    "paymentConfirmationCode": "",
    "links": [
      {
        "rel": "self",
        "hRef": "http://api.dottransfers.com/v1/bookings/services/7315"
      },
      {
        "rel": "cancel",
        "hRef": "http://api.dottransfers.com/v1/bookings/services/7315/freecancellations"
      }
    ]
  }
]

Usage notes

Number of passengers and amount of luggage: your application must ask the user to specify the number of passengers and luggage, but it must limit this amount too, according to the available capacity in the selected vehicle. To know the vehicle's capacity, read the ratedService.vehicle.maxPax and ratedService.vehicel.maxLuggage properties, obtained previously with the method GET /bookings/ratedServices.

Error response

For more information about HTTP status codes and error response formats, see Status codes and errors.

Verb Response ErrorCode Reason
POST 403 Forbidden ERR.CLIENT.INACTIVE Inactive client account.
POST ERR.CLIENT.CREDITLIMIT Credit limit exceeded.
POST ERR.SRVREQ.PAYMENTMETHOD.NOTALLOWED Payment method not allowed.
POST ERR.SRVREQ.OVERWRITTENFINALRATE OverwrittenFinalRate can not be lower than the FinalRate.

Get a Service

It allows getting a transfer service.

Suitability

Use this method when you want to ask for the information of a transfer service and show it to the user as a summary after making a reservation, or when you want to see its status after making a payment or a cancellation.

HTTP method and endpoint

GET /bookings/services/{serviceCode}

Parameters

  • serviceCode

Interactive Panel

To try it or see the parameters and errors' list, use our interactive panel.

Example

This example gets the transfer service with serviceCode 7728.

Request
GET http://api.dottransfers.com/v1/bookings/services/7728
Access-Token:yourProductionAccessToken
Response
[
  {
    "code": "7728",
    "scheduleDate": "2014-12-17T18:30:00",
    "scheduleDateUtc": "2014-12-17T23:30:00Z",
    "serviceType": "PTP",
    "rutePoints": [
      {
        "action": "PU",
        "order": 0,
        "location": {
          "name": "Miami Beach Resort & Spa, Collins Avenue, Miami Beach, FL, United States",
          "address": "4833 Collins Ave, Miami Beach, FL 33140, United States",
          "address2": null,
          "summary": "Miami Beach Resort & Spa, 4833 Collins Ave, Miami Beach, FL 33140, United States",
          "countryCode": "US",
          "latitude": "25.823953",
          "longitude": "-80.121568",
          "category": "establishment",
          "isConcrete": "yes",
          "searchText": null,
          "objectToken": null,
          "timeZone": {
            "timeZoneId": "America/New_York",
            "timeZoneName": "Eastern Standard Time",
            "rawOffset": -18000,
            "dstOffset": -14400
          }
        },
        "flight": null
      },
      {
        "action": "DO",
        "order": 1,
        "location": {
          "name": "Miami International Airport (MIA)",
          "address": "Miami, Florida, United States",
          "address2": null,
          "summary": "Miami International Airport (MIA) - Miami, Florida, United States",
          "countryCode": "US",
          "latitude": "25.793199539184",
          "longitude": "-80.29060363769",
          "category": "airport;establishment",
          "isConcrete": "yes",
          "searchText": null,
          "objectToken": null,
          "timeZone": null
        },
        "flight": null
      }
    ],
    "timeRequired": 0,
    "passenger": {
      "company": null,
      "firstName": "Peter",
      "lastName": "Pan",
      "eMail": "peterpan@dottransfers.com",
      "phone": "",
      "cellPhone": "",
      "title": "Sr",
      "languageCode": "en"
    },
    "passengerCount": 1,
    "luggageCount": 1,
    "roundTrip": "no",
    "comments": "",
    "vehicle": {
      "category": "STD",
      "descrip": "Standard Sedan",
      "obs": "Standard Sedan",
      "imageUrl": "http://app.dottransfers.com/UsrDocuments/Suppliers/Images/VehiclesTypes/VehCate_1_US.jpg",
      "maxPax": 3,
      "maxLuggage": 2,
      "features": "|AC|Airport Meet & Greet|Chofer profesional|Celular|",
      "featuresIds": "|31|33|34|36|",
      "finalRate": 103.15,
      "quantity": 1,
      "minimumTimeRequired": 180
    },
    "freeCancellationDueDate": "2014-12-17T21:30:00Z",
    "paymentGatewayUrl": "https://redapp.dottransfers.com/paygateway/Default.aspx?enc=3i6VYsQS5uB9N",
    "paymentConfirmationCode": "",
    "links": [
      {
        "rel": "self",
        "hRef": "http://api.dottransfers.com/v1/bookings/services/7315"
      },
      {
        "rel": "cancel",
        "hRef": "http://api.dottransfers.com/v1/bookings/services/7315/freecancellations"
      }
    ]
  }
]

Get Services by status or status group

It allows getting transfer services by your state or group of states.

A group of states, allows you to filter different states with similar features. For example, to show the user all canceled services, you can filter by Canceled group and this will get the services in state CancelledSupplier, CancelledRequesterFree, CancelledRequesterCost, CancelledInProgressSupplier and ancelledInProgressPax.

The following table shows the groups of states and their relationship with the states:

StatusCode Group
PaymentPending PaymentPending
PaymentExpired Canceled
Reserved Reserved
CancelledSupplier Canceled
CancelledRequesterFree Canceled
CancelledRequesterCost Canceled
InProgress InProgress
WithPax InProgress
NoShow Canceled
CancelledInProgressSupplier Canceled
CancelledInProgressPax Canceled
Realized Realized
Down Canceled

Suitability

Use this method when you want to ask for the information of a transfer services and show it to the user as realiced or pending transfers services list.

HTTP method and endpoint

GET /bookings/services?status=Reserved
GET /bookings/services?statusGroup=Canceled

Parameters

  • status
  • statusGroup

Interactive Panel

To try it or see the parameters and errors' list, use our
interactive panel for GET /bookings/services?status=Reserved.

Example

This example gets the transfer services with statusGroup Reserved.

Request
GET http://api.dottransfers.com/v1/bookings/services?statusGroup=Reserved
Access-Token:yourProductionAccessToken
Response
A list of services.

Error response

For more information about HTTP status codes and error response formats, see Status codes and errors.

Verb Response ErrorCode Reason
GET 403 Forbidden ERR.FILTER.TOOSHORT The filter must be more specific.
GET 403 Forbidden ERR.FILTER.UNAUTHORIZEDPROFILE Not authorized filter for the profile of the authenticated user.
GET 404 Not Found User not found.

Cancel a Service

It allows to cancel a transfer service with or without charges according to the transfer's cancelation date and the limit time to cancel without charges. (freeCancellationDueDate).

If you need to cancel with freecancellations but the current date is greater than the expire date without charges, you will get a 403 http code. If you are trying to cancel a reservation with cancellations but the current date is the same or less than the expire date cancellation time without charges, you will get a 403 http code.

Suitability

Use this method when you want to give the user the possibility to cancel a transfer service that has been previously booked.

HTTP method and endpoint

PUT /bookings/services/{serviceCode}/freecancellations
PUT /bookings/services/{serviceCode}/cancellations

Parameters

  • serviceCode

Interactive Panel

To try it or see the parameters and errors' list, use our
interactive panel for PUT /bookings/services/{serviceCode}/freecancellations.
or
interactive panel for PUT /bookings/services/{serviceCode}/cancellations.

Example

This example cancels the transfer service with serviceCode 7728.

Request
GET http://api.dottransfers.com/v1/bookings/services/7728/freecancellations
Access-Token:yourProductionAccessToken
{
  "reason": "My appointment was canceled",
  "requester": {
    "firstName": "Peter",
    "lastName": "Pan",
    "email": "peterpan@dottransfers.com",
    "phone": "",
    "cellPhone": "",
    "title": "",
    "languageCode": ""
  }
}
Response
{
  "links": [
    {
      "rel": "self",
      "hRef": "http://api.dottransfers.com/v1/bookings/services/7315"
    }
  ]
}

Error response

For more information about HTTP status codes and error response formats, see Status codes and errors.

PUT /bookings/services/{serviceCode}/freecancellations error codes:
Verb Response ErrorCode Reason
PUT 403 Forbidden ERR.SERVICE.NOTFREECANCELLATION Cancellation is not free of charge. You must use bookings/services/{serviceCode} /cancellations.
PUT 403 Forbidden ERR.SERVICE.UNCANCELABLE Service already cancelled.
PUT 404 Not found
PUT /bookings/services/{serviceCode}/cancellations error codes:
Verb Response ErrorCode Reason
PUT 403 Forbidden ERR.SERVICE.FREECANCELLATION Cancellation must be free of charge. You must use bookings/services/{serviceCode} /freecancellations.
PUT 403 Forbidden ERR.SERVICE.UNCANCELABLE Service already cancelled.
PUT 404 Not found

Payment

When the reservation is created, it remains in the “Online Payment pending” status until it is paid. If the reservation is not paid before the limit time, the status of the reservation will change to "Online Payment expired". If paid on time, it will change to "Reserved".

In order to pay for a reservation you will need to redirect the user to our payment gateway. The link to the gateway and the limit time to make the payment will need to be taken from the properties services.paymentGatewayUrl and service.paymentDueDate. These properties are obtained in the response after inserting a reservation through the method POST /bookings/services or when obtaining the service data through the method GET /bookings/services.

After making the payment, the application will be able to make a query to verify that it is in the “Reserved” status and to obtain and show the user the transaction confirmation code through the property service.paymentConfirmationCode.

Return to the application

A Return URL to your application could be configured when inserting a transfer service with the method POST /bookings/services. In order to do that you will need to specify the URL in the property serviceRequest.returnUrlFromPaymentGateway.
When you redirect the user to the payment gateway and the user finishes the transaction, the gateway will automatically redirect the user to the provided URL making a POST with the following parameters:

Parameter Description
serviceCode The service code corresponding to the transaction.
transactionStatus The transaction status.

TransactionStatus

Code Name Description
1 Ok It shows that the transaction ended correctly.
2 UserCancel It shows that the user cancelled the transaction.
3 ErrorCanRetry serviceCodeIt shows that the transaction ended with an error and could not be completed but the user can retry.
4 Error It shows that the transaction ended with an error and could not be completed.
5 AlreadyPaid It shows that the transfer has been already paid.
6 PaymentExpired It shows that the limit time to make the online payment expired.