NAV
Shell Javascript

Introduction

DispatchApi.io
We are the API to connect your software and process taxi orders. We give you access to every connected system! Every taxi company can install your booking or dispatch app, receive and process your rides.

Here you'll find reference documentation, guides and tutorials to help you start integrating DispatchApi.io into your dispatch-system, website or app as quickly as possible.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Sandbox API

When you receive your API key from the DispatchAPI team you'll want to start creating your integration. In order to make sure your code is ready for production you'll have to create your integration on the Sandbox API first.

All calls are basically the same as the production environment, there are some minor exceptions which we'll explain further down.

Ride statuses

The Sandbox API is not coupled with any external systems like for instance a Dispatch System. Because of this, the status of a Ride will never automatically change based on real life situations.

A ride that is created will automaticly be set to assigned with a Driver and Vehicle, after it will not change unless through the dashboard.

In order to test status changes for your rides you can head over to the Developer Dashboard and check out the Sandbox Tools section.

Events

In order for all parties to know about data changes like ride status changes we send out events through webhooks. The webhook URI can be defined in your app in the Developer Dashboard.

Don't have access to the Developer Dashboard? Contact your DispatchAPI support worker to have them change it for you!

Webhooks

{
    "id": "d0b9cdcb0777d0b9cdcb0777",
    "event_time": "2018-05-14T13:54:03.737Z",
    "event_type": "rides.status_changed",
    "meta": {
        "resource_id": "2a2f3da4",
        "resource_type": "rides",
        "status": "started"
    },
    "created":  "2018-05-14T13:54:03.737Z",
    "modified":  "2018-05-14T13:54:03.737Z",
    "resource_href": "https://api.dispatchapi.io/api/rides/2a2f3da4"
}

In order to be notified of changes in documents you have ‘touched’ you need to set up webhooks. When registering an ApiApp you are allowed to set up a webhook URL. DispatchApi will send an event object to this URL to notify you of changes to this document.

Event overview

Resource Event Description API App type
/rides resource_created Sent when the ride is created Dispatch Software
/rides status_changed Sent when the status of a ride changed General
/rides details_changed Sent when the ride information changed General
/passengers details_changed Sent when the details of a passenger changed General
/drivers details_changed Sent when the driver details changed Dispatch Software
/drivers status_changed Sent when the driver changed Dispatch Software
/vehicles status_changed Sent when the vehicles Dispatch Software

Address definitions

International address format

Default international address format:

{
	"internationalAlias": "Krasnapolsky Hotel in Amsterdam",
	"countryCode": "NL",
	"gps": {
		"lat": 52.372733,
		"lng": 4.894366
	}
}

To support addresses in all formats for all countries we have chosen to simplify the address format we use in DispatchApi.io. The minimum required address can be supplied as text and GPS location. Because this is not a formatted address we call this the internationalAlias. This is a description of the gps location. Best practice here is to use the GoogleMaps formatted address.

The downside to using this address format is the limitation to comprehensive price calculations that can be done with a more complete address.

Local address format

Address format for The Netherlands:

{
	"city": "Amsterdam",
	"streetName": "Oudezijdsvoorburgwal",
	"postalCode": "1012ES",
	"houseNumber": "1",
	"internationalAlias": "Cafe bar the bulldog",
	"poiCode": "AIR1",
	"countryCode": "NL",
	"gps": {
		"lat": 52.373805,
		"lng": 4.896701
	}
}

Airport Format

Address format for Airports (example is Schiphol Airport Amsterdam (AMS)): We use the international format for IATA codes to recognize Airports

{
	"poiCode": "AMS",
    "internationalAlias": "Schiphol Airport Amsterdam",
	"gps": {
		"lat": 52.373805,
		"lng": 4.896701
	}
}

We consider price calculation and online payments as one of our key functions. We also offer support for national address formats and systems. On request we might be able to extend the address format to your country. Look below for the available country formats.

The Netherlands

In the Netherlands we support the use of city name and postcode addresses. Please fill the address with the following properties.

Localization

We use ISO formats for a lot of standardized values like dates, currencies and languages. Make sure you use the same format when making API calls.

If you have any suggestions for new standards or questions about the proper usage of them please refer to the documentation below or contact your DispatchAPI support worker.

Timezones

We use the the ISO 8601 format for all dates and times.
(e.g. 2016-03-02T13:00:00Z)

Currencies

We use the ISO 4217 ‘code’ format for all currencies. Currencies are determined by the country of the taxi company.
(e.g. EUR)

Translations and Language

All communication will be done in English. All direct communication from the API to the passenger will be done in the set language of the passenger.

Our language IDs are comprised of two standards, namely ISO 639-1 and ISO 3166-1.

Currently we accept the following language IDs. Any other language IDs will simply return en-GB by default.

Code Description
en-GB English (Great Britain)
nl-NL Dutch

If you require extra languages please contact us at sales@dispatchapi.io for the possibilities.

Authentication

To make an authorized request, make sure you include the header:

curl -X GET \
  https://api.dispatchapi.io/api/status \
  -H 'Authorization: YOUR_KEY'

const request = require("request");

const options = { 
    method: 'GET',
    url: 'https://sandbox.dispatchapi.io/api/status',
    headers: { 
        Authorization: 'YOUR_KEY' 
    } 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

Make sure to replace YOUR_KEY with your API key.

DispatchAPI uses API keys to allow access to the API. You can request access by sending an email to support@dispatchapi.io.

DispatchAPI expects the the API key to be included in all API requests to the server.
The key is expected in the Authorization header like so:

Authorization: YOUR_KEY

Go ahead and follow one of the code examples on the right to make your first authorized request!

New Fleet Integration

This call is intended for 3rd party ride booking platform partners. For these partners we provide the option to create a new fleet as a YourDriverApp Group through one singe API call.

This integration call generates:

Step 1 Create an group and invite your contact

The endpoint for generating your accesstoken for a YourDriverApp Group is [POST] /integrations

Step 2 Retrieve and store your AccessToken

Step 3 Your contact needs to download the app, register with the phone number and accept the invite

Step 4. You are all set to [POST] /rides

Ride Flow

All rides in DispatchApi.io have a lifecycle that can end in one of the canceled or completed states. All rides are created in the matching state, as they are waiting for a driver to be dispatched. The Dispatch Software is responsible for updating the ride status and therefore triggering status changed events to the booking software.

Find a diagram of the lifecycle and ride statuses below:

Ride status table

Status Description
requested The ride is not confirmed to the passenger, and is currently being processed by DispatchAPI. The ride will be set to assigned or canceled
unassigned The ride has not yet been processed by the dispatch software and is waiting for a driver and vehicle to be dispatched (This is the default status)
assigned The ride has been accepted by a driver, yet the ride has not been activated. The active ride data is not accessible in this status
driving_to_pickup The ride had been accepted and the driver is on his/her way to the pickup location
arrived_at_pickup The ride had been accepted and the driver has arrived at the pickup location
started The client has been picked up and (if required) the taxi meter has been started.
completed The ride has been completed, the final amount is now available in the ride details.
canceled The ride has been canceled by the dispatch system
canceled_driver The ride has been canceled by the dispatched driver, this means that the driver will not pickup the client. We advice booking-apps not to act on this cancelation. For dispatch software we advise to reset the status to matching and re-dispatch another driver. If this is not possible use a PATCH on the ride to cancel the ride.
canceled_passenger The ride has been canceled by the passenger and the ride should not be processed.

Ride lifecycle diagram

Ride Flow Diagram

Ride offering

There's several ways to get your rides dispatched to one or more drivers at a time. In order to get your ride dispatched, we use the Offer object.

The Offer object describes how you want the Ride to be dispatched and who should receive it.

  1. In order to dispatch a ride, logically you'll have to create it first. Go ahead and POST your Ride.
  2. After your Ride has been created, you'll have to decide how you want it to be dispatched. We use the Offer object for this.
    1. Dispatch a ride to a company/group
    2. Dispatch a ride to a specific Driver based on the ID known in DispatchAPI
    3. Dispatch a ride to a specific Driver based on his/her phoneNumber
    4. Dispatch a ride to a group of drivers based on their IDs known in DispatchAPI
    5. Dispatch a ride to a group of drivers based on their phoneNumbers
  3. When u POST your Offer object, the DispatchAPI dispatch server will offer the ride to the driver(s) that fit your previous selection
  4. When the Ride was successfully dispatched and the Driver has accepted your Offer, you'll receive a webhook telling you the Ride has changed. You should check the status of the ride and when it has changed to assigned you'll know the Driver has been assigned to this Ride and will handle it from here.

To a Company Group

{
    "productType": "ride",
    "productId": "507f1f77bcf86cd799439011",
    "type": "company",
    "companyId": "7997b47f1f7c3901150f86cd",
    "settings": {
        "maxOfferTime": 120
    }
}

You can easily try to dispatch a Ride to a Company/Group by simply defining the companyId in the Offer object like so:

To a specific driver based on the ID known in DispatchAPI

{
    "productType": "ride",
    "productId": "507f1f77bcf86cd799439011",
    "type": "driver",
    "driverId": "150f867997b47f1f7c3901cd",
    "settings": {
        "maxOfferTime": 120
    }
}

You can dispatch a Ride directly to a Driver based on their ID like so:

To a specific driver based on their phoneNumber

{
    "productType": "ride",
    "productId": "507f1f77bcf86cd799439011",
    "type": "driver",
    "phoneNumber": "+31699998888",
    "settings": {
        "maxOfferTime": 120
    }
}

You can dispatch a Ride directly to a Driver based on his/her phoneNumber like so:

To a group of drivers based on their IDs known in DispatchAPI

{
    "productType": "ride",
    "productId": "507f1f77bcf86cd799439011",
    "type": "driver",
    "drivers": [
        "5a16dd9751f55068030cba59",
        "5a1d48c3934484588d494409",
        "5a1c1d2ed4e2eb3f9c680709"
    ],
    "settings": {
        "maxOfferTime": 120
    }
}

You can dispatch a Ride to a group of Drivers based on their IDs like so:

To a group of drivers based on their phoneNumbers

{
    "productType": "ride",
    "productId": "507f1f77bcf86cd799439011",
    "type": "driver",
    "phoneNumbers": [
        "+31699887766",
        "+31611223366",
        "+31644556622"
    ],
    "settings": {
        "maxOfferTime": 120
    }
}

You can dispatch a Ride to a group of drivers based on their phoneNumbers like so:

Filtering data

If you're searching for specific data or need to retrieve the relation of a resource as well as the resource itself, you'll need to use the filter functionality of the API. The filter is passed as a URI parameter in the API call.

Syntax

The filter is a URI parameter with a “stringified” JSON object as its value: ?filter={ Stringified-JSON }.

The stringified JSON should be in the following format: { filterType: spec, filterType: spec, ... }.

filterType type Description
fields Object, Array or String Specify fields to include in or exclude from the response.
include Object, Array or String Include results from related resources.
limit Number Limit the number of instances to return.
order String Specify sort order: ascending or descending.
skip Number Skip the specified number of instances.
where Object Specify search criteria; similar to a WHERE clause in SQL.

A filter using multiple filter types

{
    "where": {
        "id": "56baf939f85639cac1d87bee"
    },
    "include": [
        "driver",
        "vehicle"
    ]
}

Example: A filter using multiple filter types:

Example request: GET /rides?filter={"where":{"id":"56baf939f85639cac1d87bee"},"include":["driver","vehicle"]}

Filtering fields

A fields filter specifies properties (fields) to include or exclude from the results.

Get a resource and include its id and model but exclude its make

{ 
    "fields": {
        "id": true, 
        "make": false, 
        "model": true
    } 
}

Example: Get a resource and include its id and model but exclude its make

Including relations

An include filter enables you to include results from related resources in a query.

Get a resource and include its driver and vehicle

{
    "include": [
        "driver",
        "vehicle"
    ]
}

Example: Get a resource and include its driver and vehicle

Get a resource and include its rides and within it each driver and vehicle of that ride

{
    "include": {
        "rides": [
            "driver",
            "vehicle"
        ]
    }
}

Example: Get a resource and include its rides and within it each driver and vehicle of that ride

Limiting results

A limit filter limits the number of records returned to the specified number (or less).

Get the first 5 items of a query

{
    "limit": 5
}

Example: Get the first 5 items of a query

Ordering results

An order filter specifies how to sort the results: ascending (ASC) or descending (DESC) based on the specified property.

Order by one property

{ 
    "order": "propertyName <ASC|DESC>" 
}

Example: Order by one property

Order by two or more properties:

{ 
    "order": [
        "propertyName <ASC|DESC>", 
        "propertyName <ASC|DESC>"....
    ]
}

Example: Order by two or more properties:

Skipping results

A skip filter omits the specified number of returned records. This is useful, for example, to paginate responses.

Skip the first 10 records of a query

{ 
    "skip": 10
}

Example: Skip the first 10 records of a query

How to paginate results (Page 1 with 10 records per page)

{ 
    "skip": 0,
    "limit": 10
}

How to paginate results (Page 2 with 10 records per page)

{ 
    "skip": 10,
    "limit": 10
}

Example: How to paginate results

‘Where’ searches

A where filter specifies a set of logical conditions to match, similar to a WHERE clause in a SQL query.

Operators

You can use various operators in your “where” filter in order to find your desired results. Check the table below:

Operator Description
and Logical AND operator
or Logical OR operator
gt, gte Numerical greater than (>); greater than or equal (>=). Valid only for numerical and date values.
lt, lte Numerical less than (<); less than or equal (<=). Valid only for numerical and date values.
between True if the value is between the two specified values: greater than or equal to first value and less than or equal to second value.
inq, nin In / not in an array of values.
neq Not equal (!=)
regexp Regular expression.

To use operators follow this syntax: {where: {<and|or>: [condition1, condition2, ...] } }

‘Where’: Equivalence

Get a record where the name property equals “John”

{
    "where": {
        "name": "John"
    }
}

Example: Get a record where the name property equals “John”

‘Where’: gt lt

Get a record of a resource where passengerCount is less than 5

{
    "where": {
        "passengerCount": {
            "lt": 5
        }
    }
}

Example: Get a record of a resource where passengerCount is less than 5

Get a record of a resource where date is greater than 2014-04-01T18:30:00.000Z

{
    "where": {
        "date": {
            "gt": "2014-04-01T18:30:00.000Z"
        }
    }
}

Example: Get a record of a resource where date is greater than 2014-04-01T18:30:00.000Z

‘Where’: and or

Find a record where brand is “Ferrari” and model is “F50”

{
    "where": {
        "and": [
            {
                "brand": "Ferrari" 
            }, 
            {
                "model": "F50"
            }
        ]
    }
}

Example: Find a record where brand is “Ferrari” and model is “F50”

Find a record where brand is “BMW” or brand is “Mercedes”

{
    "where": {
        "or": [
            {
                "brand": "BMW" 
            }, 
            {
                "brand": "Mercedes"
            }
        ]
    }
}

Example: Find a record where brand is “BMW” or brand is “Mercedes”

Find a record where ( brand is “BMW” and model is “M4” ) or brand is “Mercedes”

{
    "where": {
        "or": [
            {
                "and": [
                    {
                        "brand": "BMW" 
                    }, 
                    {
                        "model": "M4"
                    }
                ]
            },
            {
                "brand": "Mercedes"
            }
        ]
    }
}

Example: Find a record where ( brand is “BMW” and model is “M4” ) or brand is “Mercedes”

‘Where’: between

Get a record of a resource where price between 0 and 15

{
    "where": {
        "price": {
            "between": [0,15]
        }
    }
}

Example: Get a record of a resource where price between 0 and 15

‘Where’: inq

Get a record of a resource where status is either “active” or “started”

{
    "where": {
        "status": {
            "inq": [
                "active",
                "started"
            ]
        }
    }
}

Example: Get a record of a resource where status is either “active” or “started”

‘Where’: Regular expressions

You can use regular expressions in a where filter, with the following syntax. You can use a regular expression in a where clause for updates and deletes, as well as queries. Essentially, regexp is just like an operator in which you provide a regular expression value as the comparison value.

Syntax: { where: {property: {regexp: expression} } }

Where expression can be a:

For more information on JavaScript regular expressions, see Regular Expressions (Mozilla Developer Network).

Returns instances of a resource of which the model property value starts with a capital “T”:

{
    "where": {
        "model": {
            "regexp": "^T"
        }
    }
}

Example: Returns instances of a resource of which the model property value starts with a capital “T”:

Integrations

This call is intended for 3rd party ride booking platform partners. For these partners we provide the option to create a new fleet as a YourDriverApp Group through one singe API call.

This integration call generates:

Integration process

  1. [POST] /Integrations
  2. Company Created
  3. Owner is created and invited
  4. DaApp Installed
  5. AccessToken Returned
  6. Driver registers and accepts invite to process your jobs

Request integration AccessToken

Integration schema

Example

{
  "Company": {
       "name": "Fast and Go", 
       "email": "info@yourdriverapp.com", 
       "phoneNumber": "+31600000000"
  },
  "Driver": {
      "fname": "John", 
      "lname": "Doe", 
      "email": "info@yourdriverapp.com", 
      "phoneNumber": "+31600000000"
  },
  "daAppId": "507f1f77bcf86cd799439011"
}

curl -X POST \
  https://api.dispatchapi.io/api/rides \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "Company": {
             "name": "Fast and Go", 
             "email": "info@yourdriverapp.com", 
             "phoneNumber": "+31600000000"
        },
        "Driver": {
            "fname": "John", 
            "lname": "Doe", 
            "email": "info@yourdriverapp.com", 
            "phoneNumber": "+31600000000"
        },
        "daAppId": "507f1f77bcf86cd799439011"
      }'

const request = require("request");
const options = { 
    method: 'POST',
    url: 'https://api.dispatchapi.io/api/rides',
    headers: { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body: {
        "Company": {
             "name": "Fast and Go", 
             "email": "info@yourdriverapp.com", 
             "phoneNumber": "+31600000000"
        },
        "Driver": {
            "fname": "John", 
            "lname": "Doe", 
            "email": "info@yourdriverapp.com", 
            "phoneNumber": "+31600000000"
        },
        "daAppId": "507f1f77bcf86cd799439011"
      },
    json: true 
};
request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
  "accessToken": "xxxx-xxxx-xxxx-xxxx",
  "companyId": "507f1f77bcf86cd799439011",
}
Property Type Required Possible values
id String false 507f1f77bcf86cd799439011
Company Object true Integration Company
Driver Object true Integration Driver
daAppId String false 507f1f77bcf86cd799439011

Integration Company

Example

{
  "name": "Fast and Go", 
  "email": "info@yourdriverapp.com", 
  "phoneNumber": "+31600000000"
}
Property Type Required Possible values
name String true Fast and Go
email String true info@yourdriverapp.com
phoneNumber String true +31600000000

Integration Driver schema

Example

{
  "fname": "John", 
  "lname": "Doe", 
  "email": "info@yourdriverapp.com", 
  "phoneNumber": "+31600000000"
}
Property Type Required Possible values
fname String true John
lname String true Doe
email String true info@yourdriverapp.com
phoneNumber String true +31600000000

API Reference

The following models are available through DispatchAPI. Make sure you stay up-to-date with this reference to make sure your integration with DispatchAPI will continue to run smoothly.

Companies

Company schema

Property Type Required Possible values
id String false 507f1f77bcf86cd799439011
name String true DispatchAPI
email String false sales@dispatchapi.io
phoneNumber String false +31611223344
city String false Amsterdam
state String false Noord-Holland
postalCode String false 1671GD
foreignId String false 507f1f77bcf86cd799439011
appSettings Object false {}

Get your company

curl "https://api.dispatchapi.io/api/companies/{id}"
  -H "Authorization: YOUR_KEY"

const request = require("request");

const options = { 
    method: 'GET',
    url: 'https://api.dispatchapi.io/api/companies/{id}',
    headers: { 
        Authorization: 'YOUR_KEY' 
    } 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
	"id": "507f1f77bcf86cd799439011",
	"foreignId": "507f1f77bcf86cd799439011",
	"name": "Hello, world!",
	"phoneNumber": "Hello, world!",
	"email": "Hello, world!",
	"status": "Hello, world!",
	"statusText": "Hello, world!",
	"mailingAddress": {
		"city": "Amsterdam",
		"streetName": "Oudezijdsvoorburgwal",
		"postalCode": "1012ES",
		"houseNumber": "1",
		"synonym": "Hilton Hotel",
		"internationalAlias": "Cafe bar the bulldog, Nieuwstraat 4, Medemblik",
		"gps": {
			"lat": "52.373805",
			"lng": "4.896701"
		},
		"poiCode": "AIR1",
		"countryCode": "NL"
	},
	"visitAddress": {
		"city": "Amsterdam",
		"streetName": "Oudezijdsvoorburgwal",
		"postalCode": "1012ES",
		"houseNumber": "1",
		"synonym": "Hilton Hotel",
		"internationalAlias": "Cafe bar the bulldog, Nieuwstraat 4, Medemblik",
		"gps": {
			"lat": "52.373805",
			"lng": "4.896701"
		},
		"poiCode": "AIR1",
		"countryCode": "NL"
	}
}

This endpoint retrieves your company based on its ID.

HTTP Request

GET https://api.dispatchapi.io/api/companies/{id}

Query Parameters

Parameter Default Description
id null The ID of your company
filter null Optionally a filter to tailor your result

Get company rides

curl "https://api.dispatchapi.io/api/companies/{id}/rides"
  -H "Authorization: YOUR_KEY"

const request = require("request");

const options = { 
    method: 'GET',
    url: 'https://api.dispatchapi.io/api/companies/{id}/rides',
    headers: { 
        Authorization: 'YOUR_KEY' 
    } 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

[{
	"passengerCount": 2,
	"intId": 101236,
	"origin": {
		"originId": "cd438dcc4b6cdb049245d448ead1c711",
		"name": "Karhoo"
	},
	"note": "Add your notes here",
	"departure": {
		"city": "Amsterdam",
		"streetName": "Oudezijdsvoorburgwal",
		"postalCode": "1012EH",
		"houseNumber": "3",
		"internationalAlias": "Hotel The Globe",
		"gps": {
			"lat": 52.375259,
			"lng": 4.900178
		},
		"countryCode": "NL"
	},
	"destination": {
		"city": "Schiphol",
		"streetName": "Aankomstpassage",
		"postalCode": "1118CX",
		"houseNumber": "1",
		"internationalAlias": "Schiphol Airport Amsterdam",
		"gps": {
			"lat": 52.308896,
			"lng": 4.760862
		},
		"countryCode": "NL"
	},
	"requestedDate": "2018-01-15T09:11:29.653Z",
	"status": "accepted",
	"language": "EN",
	"vehicleType": "saloon",
	"paymentMeta": {
		"method": "bankTransfer",
		"description": "Online iDeal payment",
		"origin": "online",
		"moment": "beforeRide"
	},
	"price": {
		"total": 4400,
		"currency": "EUR",
		"breakdown": {
			"route": 4136,
			"tax": 264,
			"toll": 0,
			"parking": 0,
			"waiting": 0,
			"discount": 325
		}
	},
	"type": "ride",
	"id": "5a5c96d64b22411dc1b06b1c",
	"created": "2018-01-15T11:56:06.561Z",
	"modified": "2018-01-15T11:56:06.561Z",
	"expired": "2023-01-15T11:56:06.558Z",
	"companyId": "507f1f77bcf86cd799439011",
	"rideLogId": "5a5c96d64b22411dc1b06b1a",
	"passenger": {
		"fname": "John",
		"lname": "Doe",
		"email": "john@doe.com",
		"language": "EN",
		"phoneNumber": "+31612345678"
	}
}]

This endpoint retrieves your the rides for your company based on its ID.

HTTP Request

GET https://api.dispatchapi.io/api/companies/{id}/rides

Query Parameters

Parameter Default Description
id null The ID of your company
filter null Optionally a filter to tailor your result

Vehicles

Vehicle schema

Property Type Required Possible values
id String false 507f1f77bcf86cd799439011
brand String true Ferrari
model String false F50
maxPassengers Number true 2
licensePlate String true 5-FDX-99
formattedLicensePlate String false 5FDX99
type String true saloon, estate, bus, minivan or limo
status String true Status
location Object true Location
statusModified Date false Date
healthChecked Boolean false true or false
activeVehicleId String false 507f1f77bcf86cd799439011
driverId String false 507f1f77bcf86cd799439011
companyId String false 507f1f77bcf86cd799439011

Create a new vehicle

curl -X POST \
  https://api.dispatchapi.io/api/vehicles \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "brand": "Ferrari",
  "model": "F50",
  "maxPassengers": "4",
  "licensePlate": "78-TVD-3",
  "formattedLicensePlate": "78TVD3",
  "type": "saloon",
  "status": {
    "state": "available",
    "description": "This vehicle is available",
    "code": 100,
    "origin": "driverApp"
  },
  "location": {
    "city": "Amsterdam",
    "streetName": "Dam",
    "postalCode": "1012 JS",
    "houseNumber": "15",
    "synonym": "Café Zwart",
    "internationalAlias": "string",
    "gps": {
      "lat": 52.372537,
      "lng": 4.894091
    },
    "gpsSpeed": 0,
    "gpsBearing": 0,
    "gpsAccuracy": 0,
    "gpsTime": "2018-02-06T13:05:57.111Z",
    "gpsOrigin": "driverApp",
    "gpsPriority": "front-end",
    "placesId": "ChIJy0YESccJxkcRARYOBTnAObs", 
    "description": "Café in Amsterdam",
    "poiCode": "",
    "countryCode": "NL"
  },
  "companyId": "507f1f77bcf86cd799439011"
}'

const request = require("request");

const options = { 
    method: 'POST',
    url: 'https://api.dispatchapi.io/api/vehicles',
    headers: { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body:  { 
        brand: 'Ferrari',
        model: 'F50',
        maxPassengers: '4',
        licensePlate: '78-TVD-3',
        formattedLicensePlate: '78TVD3',
        type: 'saloon',
        status: { 
            state: 'available',
            description: 'This vehicle is available',
            code: 100,
            origin: 'driverApp' 
        },
        location: { 
            city: 'Amsterdam',
            streetName: 'Dam',
            postalCode: '1012 JS',
            houseNumber: '15',
            synonym: 'Café Zwart',
            internationalAlias: 'string',
            gps: { 
                lat: 52.372537, 
                lng: 4.894091 
            },
            gpsSpeed: 0,
            gpsBearing: 0,
            gpsAccuracy: 0,
            gpsTime: '2018-02-06T13:05:57.111Z',
            gpsOrigin: 'driverApp',
            gpsPriority: 'front-end',
            placesId: 'ChIJy0YESccJxkcRARYOBTnAObs',
            description: 'Café in Amsterdam',
            poiCode: '',
            countryCode: 'NL' 
        },
        companyId: '507f1f77bcf86cd799439011' 
    },
    json: true 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
	"id": "5a79acf421e82c11c2d200ae",
	"brand": "Ferrari",
	"model": "F50",
	"maxPassengers": 4,
	"licensePlate": "78-TVD-3",
	"formattedLicensePlate": "78TVD3",
	"type": "saloon",
	"status": {
		"state": "available",
		"description": "This vehicle is available",
		"code": 100,
		"origin": "your_dispatch_system?"
	},
	"location": {
		"city": "Amsterdam",
		"streetName": "Dam",
		"postalCode": "1012 JS",
		"houseNumber": "15",
		"synonym": "Café Zwart",
		"internationalAlias": "string",
		"gps": {
			"lat": 52.372537,
			"lng": 4.894091
		},
		"gpsSpeed": 0,
		"gpsBearing": 0,
		"gpsAccuracy": 0,
		"gpsTime": "2018-02-06T13:05:57.111Z",
		"gpsOrigin": "driverApp",
		"gpsPriority": "front-end",
		"placesId": "ChIJy0YESccJxkcRARYOBTnAObs",
		"description": "Café in Amsterdam",
		"poiCode": "",
		"countryCode": "NL"
	},
	"created": "2018-02-06T13:26:12.089Z",
	"modified": "2018-02-06T13:26:12.089Z",
	"companyId": "507f1f77bcf86cd799439011"
}

This endpoint creates a vehicle

HTTP Request

POST https://api.dispatchapi.io/api/vehicles

Update vehicle details

curl -X PATCH \
  https://api.dispatchapi.io/api/vehicles/{id} \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": {
    "state": "unavailable",
    "description": "This vehicle is offline",
    "code": 199,
    "origin": "driverApp"
  },
  "companyId": "string"
}'

const request = require("request");

const options = {
    method: 'PATCH',
    url: 'https://api.dispatchapi.io/api/vehicles/{id}',
    headers: { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body: { 
        status: { 
            state: 'unavailable',
            description: 'This vehicle is offline',
            code: 199,
            origin: 'driverApp' 
        },
        companyId: 'string' 
    },
    json: true 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
	"id": "5a79b2a721e82c11c2d200b9",
	"brand": "Ferrari",
	"model": "F50",
	"maxPassengers": 4,
	"licensePlate": "78-TVD-3",
	"formattedLicensePlate": "78TVD3",
	"type": "saloon",
	"status": {
		"state": "unavailable",
		"description": "This vehicle is offline",
		"code": 199,
		"origin": "driverApp"
	},
	"location": {
		"city": "Amsterdam",
		"streetName": "Dam",
		"postalCode": "1012 JS",
		"houseNumber": "15",
		"synonym": "Café Zwart",
		"internationalAlias": "string",
		"gps": {
			"lat": 52.372537,
			"lng": 4.894091
		},
		"gpsSpeed": 0,
		"gpsBearing": 0,
		"gpsAccuracy": 0,
		"gpsTime": "2018-02-06T13:05:57.111Z",
		"gpsOrigin": "driverApp",
		"gpsPriority": "front-end",
		"placesId": "ChIJy0YESccJxkcRARYOBTnAObs",
		"description": "Café in Amsterdam",
		"poiCode": "",
		"countryCode": "NL"
	},
	"created": "2018-02-06T13:50:31.442Z",
	"modified": "2018-02-06T13:50:48.608Z",
	"companyId": "5a4c9680b2213be18a6ea19e",
	"statusModified": "2018-02-06T13:50:48.603Z"
}

This endpoint updates a vehicle based on its ID

HTTP Request

PATCH https://api.dispatchapi.io/api/vehicles/{id}

Query Parameters

Parameter Default Description
id null The ID of your vehicle

Drivers

Driver schema

Property Type Required Possible values
id String false 507f1f77bcf86cd799439011
fname String true John
lname String true Doe
phoneNumber String true +31622334455
emailAddress String false sales@dispatchapi.io
status String false pending, accepted, blocked or removed
type String false driver, operator or admin
ssn String false This is a social security number (e.g. BSN for NL)
companyId String false 507f1f77bcf86cd799439011
installationId String false 507f1f77bcf86cd799439011
activeVehicleId String false 507f1f77bcf86cd799439011
daAppId String false 507f1f77bcf86cd799439011
userId String false 507f1f77bcf86cd799439011
driverId String false 507f1f77bcf86cd799439011

Create a new driver

curl -X POST \
  https://api.dispatchapi.io/api/drivers \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "fname": "John",
  "lname": "Doe",
  "phoneNumber": "+31644556677",
  "emailAddress": "john@doe.nl",
  "status": "accepted",
  "type": "driver",
  "ssn": "Af3e1a45a4f1",
  "companyId": "507f1f77bcf86cd799439011"
}'

const request = require("request");

const options = { 
    method: 'POST',
    url: 'https://api.dispatchapi.io/api/drivers',
    headers: { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body: { 
        fname: 'John',
        lname: 'Doe',
        phoneNumber: '+31644556677',
        emailAddress: 'john@doe.nl',
        status: 'accepted',
        type: 'driver',
        ssn: 'Af3e1a45a4f1',
        companyId: '507f1f77bcf86cd799439011' 
    },
    json: true 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
	"fname": "John",
	"lname": "Doe",
	"phoneNumber": "+31644556677",
	"emailAddress": "john@doe.nl",
	"status": "accepted",
	"type": "driver",
	"ssn": "Af3e1a45a4f1",
	"id": "5a79b46921e82c11c2d200c9",
	"created": "2018-02-06T13:58:01.826Z",
	"modified": "2018-02-06T13:58:01.826Z",
	"companyId": "5a4c9680b2213be18a6ea19e"
}

This endpoint creates a driver

HTTP Request

POST https://api.dispatchapi.io/api/drivers

Update driver details

curl -X PATCH \
  https://api.dispatchapi.io/api/drivers/{id} \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "fname": "Jane",
  "emailAddress": "jane@doe.nl"
}'

const request = require("request");

const options = { 
    method: 'PATCH',
    url: 'https://api.dispatchapi.io/api/drivers/{id}',
    headers: { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body: { 
        fname: 'Jane',
        emailAddress: 'jane@doe.nl'
    },
    json: true 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
    "fname": "Jane",
    "lname": "Doe",
    "phoneNumber": "+31644556677",
    "emailAddress": "jane@doe.nl",
    "status": "accepted",
    "type": "driver",
    "ssn": "Af3e1a45a4f1",
    "id": "5a79b46921e82c11c2d200c9",
    "created": "2018-02-06T13:58:01.826Z",
    "modified": "2018-02-06T14:10:51.351Z",
    "companyId": "5a4c9680b2213be18a6ea19e"
}

This endpoint updates a driver based on its ID

HTTP Request

PATCH https://api.dispatchapi.io/api/drivers/{id}

Query Parameters

Parameter Default Description
id null The ID of your driver

Debtors

Debtor schema

Example

{
  "companyName": "DispatchAPI Business", 
  "emailAddress": "sales@dispatchapi.io", 
  "phoneNumber": "+316460123456", 
  "address": {
    "city": "Amsterdam",
    "streetName": "Oudezijdsvoorburgwal",
    "postalCode": "1012EH",
    "houseNumber": "3",
    "internationalAlias": "Hotel The Globe",
    "gps": {
      "lat": 52.375259,
      "lng": 4.900178
    },
    "countryCode": "NL"
  }, 
  "code": "DEB001",
  "note": ""
}
Property Type Required Possible values
id String false 507f1f77bcf86cd799439011
companyName String false DispatchAPI Business
emailAddress String false sales@dispatchapi.io
phoneNumber String false +316460123456
address Object true Location
code String false DEB001
note String false ``

Create a new debtor

curl -X POST \
  https://api.dispatchapi.io/api/debtors \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "companyName": "DispatchAPI Business", 
  "companyName": "DispatchAPI Business", 
  "emailAddress": "sales@dispatchapi.io", 
  "phoneNumber": "+316460123456", 
  "address": {
    "city": "Amsterdam",
    "streetName": "Oudezijdsvoorburgwal",
    "postalCode": "1012EH",
    "houseNumber": "3",
    "internationalAlias": "Hotel The Globe",
    "gps": {
      "lat": 52.375259,
      "lng": 4.900178
    },
    "countryCode": "NL"
  }, 
  "code": "DEB001",
  "note": ""
}'

const request = require("request");

const options = { 
    method: 'POST',
    url: 'https://api.dispatchapi.io/api/debtors',
    headers: { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body: {
      "companyName": "DispatchAPI Business",
      "emailAddress": "sales@dispatchapi.io",
      "phoneNumber": "+316460123456",
      "address": {
        "city": "Amsterdam",
        "streetName": "Oudezijdsvoorburgwal",
        "postalCode": "1012EH",
        "houseNumber": "3",
        "internationalAlias": "Hotel The Globe",
        "gps": {
          "lat": 52.375259,
          "lng": 4.900178
        },
        "countryCode": "NL"
      },
      "code": "DEB001",
      "note": ""
    },
    json: true 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
  "id": "507f1f77bcf86cd799439011",
  "companyName": "DispatchAPI Business",
  "emailAddress": "sales@dispatchapi.io",
  "phoneNumber": "+316460123456",
  "address": {
    "city": "Amsterdam",
    "streetName": "Oudezijdsvoorburgwal",
    "postalCode": "1012EH",
    "houseNumber": "3",
    "internationalAlias": "Hotel The Globe",
    "gps": {
      "lat": 52.375259,
      "lng": 4.900178
    },
    "countryCode": "NL"
  },
  "code": "DEB001",
  "note": ""
}

This endpoint creates an debtor

HTTP Request

POST https://api.dispatchapi.io/api/debtors

Update debtor details

curl -X PATCH \
  https://api.dispatchapi.io/api/rides/{id} \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "companyName": "DispatchAPI Business", 
  "code": "DEB002",
}'

const request = require("request");

const options = { 
    method: 'PATCH',
    url: 'https://api.dispatchapi.io/api/rides/{id}',
    headers: { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body: {
      "companyName": "DispatchAPI Business",
      "code": "DEB001",
    },
    json: true 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
  "id": "507f1f77bcf86cd799439011",
  "companyName": "DispatchAPI Business",
  "emailAddress": "sales@dispatchapi.io",
  "phoneNumber": "+316460123456",
  "address": {
    "city": "Amsterdam",
    "streetName": "Oudezijdsvoorburgwal",
    "postalCode": "1012EH",
    "houseNumber": "3",
    "internationalAlias": "Hotel The Globe",
    "gps": {
      "lat": 52.375259,
      "lng": 4.900178
    },
    "countryCode": "NL"
  },
  "code": "DEB002",
  "note": ""
}

Rides

Ride schema

Property Type Required Possible values
id String false 507f1f77bcf86cd799439011
passengerCount Number true 1
intId Number false 2018001
origin Object false {"originId" : "2", "name" : "DispatchAPI"}
note String false Please ring the doorbell when you arrive
flightNumber String false KL2326
departure Object true Location
destination Object false Location
requestedDate Date true Date
status String true Ride Status
language String true Language
vehicleType String false saloon, estate, bus, minivan or limo
foreignDispatchId String false B5161564
foreignBookingId String false A13115
debtorCode String false AB5545
paymentMeta Object false paymentMeta
metrics Object false metrics
priceMethod string true onMeter, fixed
metricsMethod string true onMeter, fixed
meta Object false meta
foreignMeta Object false foreignMeta
passenger Object false passenger
price Object true Price
eta Object false {"time": "274181", "distance": "1351"}
type String false ride
vehicleStatus Object false {}
events Object false events
vehicleId String false 507f1f77bcf86cd799439011
driverId String false 507f1f77bcf86cd799439011
operatorId String false 507f1f77bcf86cd799439011
rideId String false 507f1f77bcf86cd799439011
companyId String false 507f1f77bcf86cd799439011
userId String false 507f1f77bcf86cd799439011
passengerId String false 507f1f77bcf86cd799439011
shiftId String false 507f1f77bcf86cd799439011
rideLogId String false 507f1f77bcf86cd799439011

PaymentMeta schema

Example

{
  "method": "bankTransfer", 
  "description": "Online payment", 
  "origin": "online", 
  "psp": "stripe", 
  "moment": "beforeRide"
}
Property Type Required Possible values
method String true cash, debitcard, creditcard, bankTransfer, onAccount or coupon
description String true Free form string like: Online payment through Adyen
origin String true inTaxi, inApp, online or invoice
moment String true beforeRide or afterRide
psp String false Free form string like: Stripe or PayPall

Metrics schema

Example

{
  "distance": 20000, 
  "duration": 900, 
  "waitingtime": 60
}
Property Type Required Possible values
distance number true Distance in meters, any number
duration number true Ride duration in seconds, any number
waitingtime number true Waitingtime in seconds, any number

Price schema

Prices in DispatchAPI reflect the details on how a price is build up. For a ride to have a price, the total (in cents) and the currency are required. In order to have more insights in the buildup of the prices we have added the breakdown. The breakdown should contain amounts (in cents) INCLUDING VAT. The taxPercentage field can be used in order to calculate the VAT over the breakdown item. These fields are optional by a driver to be inserted in the Native YourDriverApp of DispatchAPI.

Example

{
"price": {
    "currency": "EUR",
    "total": 4400,
    "breakdown": { 
      "route": {
        "total": 4681,
        "taxPercentage": 9
      },
      "toll": {
        "total": 0,
        "taxPercentage": 21
      },
      "parking": {
        "total": 0,
        "taxPercentage": 21
      },
      "waiting": {
        "total": 0,
        "taxPercentage": 21
      },
      "cleaning": {
        "total": 0,
        "taxPercentage": 21
      },
     "discount": {
       "total": -325,
       "taxPercentage": 0
     },
      "additional": {
        "total": -325,
        "taxPercentage": 0
      }
    }
  }
}
Property Type Required Possible values
currency String true 3 Character (ISO 4217) currency codes, EUR
total number true Amount in cents: 4400
breakdown Object true containing a description of the amount

Passenger schema

Property Type Required Possible values
fname String true John
lname String true Doe
email String true sales@dispatchapi.io
language String true Language
phoneNumber String true +31622334455

Metadata

Sometimes it's necessary to communicate non-standard data through the API to a third party service. In order to do allow for this requirement we've introduced the meta and foreignMeta objects.

Meta example

{
  "wheelchair": true,
  "luggage": 2,
  "childSeats": 1,
  "babySeats": 1,
  "invoiceReference": "INV201009828",
  "guideDog": true,
  "companion": false,
  "cancelationPolicy": "cancelationPolicy",
  "pickupPolicy": "pickupPolicy",
  "requestedDateOnCall": true
}

Meta object

The meta object is used for a couple pieces of metadata we as DispatchAPI recognize to be used industry wide. Here's a table of the values we accept in the meta object.

Property Type Required Possible values
wheelchair Boolean false true or false
luggage Number false Any number for hold luggage, this will indicate that a passenger has to wait for the luggage to be unloaded for the airplane. This will also make an indication about the required vehicle capacity.
childSeats Number false Any number, a seat raiser used for children
babySeats Number false Any number, Safety seat for babys
guideDog Boolean false true or false
companion Boolean false true or false
invoiceReference string false Any text used to identify the job for invoicing
cancelationPolicy string false Any text referring to a company cancelationPolicy
pickupPolicy string false Any text referring to a company pickupPolicy used for this trip
requestedDateOnCall Boolean false This will indicate that the requesteDate has an onCall option to it. This means the client will call through the final time for the requestedDate

ForeignMeta example

{
  "sendCustomNotifications": true,
  "anyExternalValue": 66
}

ForeignMeta object

foreignMeta can be used for any data that is not widely used by third party services and platforms.

Events object

Property Type Required Possible values
assigned Date false Date
arrived Date false Date
started Date false Date
completed Date false Date

Create a new ride

curl -X POST \
  https://api.dispatchapi.io/api/rides \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "passengerCount": 2,
  "note": "Add your notes here",
  "requestedDate": "2018-01-15T09:11:29.653Z",
  "language": "EN",
  "vehicleType": "saloon",
  "status": "accepted",
  "departure": {
    "city": "Amsterdam",
    "streetName": "Oudezijdsvoorburgwal",
    "postalCode": "1012EH",
    "houseNumber": "3",
    "internationalAlias": "Hotel The Globe",
    "countryCode": "NL",
    "gps": {
      "lat": "52.375259",
      "lng": "4.900178"
    }
  },
  "destination": {
    "city": "Schiphol",
    "streetName": "Aankomstpassage",
    "postalCode": "1118CX",
    "houseNumber": "1",
    "internationalAlias": "Schiphol Airport Amsterdam",
    "countryCode": "NL",
    "gps": {
      "lat": "52.308896",
      "lng": "4.760862"
    }
  },
  "priceMethod": "onMeter",
  "metricsMethod": "onMeter",
  "metrics": {
    "distance": 0,
    "duration": 0,
    "waitingTime": 0
  },
  "price": {
    "currency": "EUR",
    "total": 4400,
    "breakdown": { 
      "route": {
        "total": 4681,
        "percentage": 9
      },
      "toll": {
        "total": 0,
        "percentage": 0
      },
      "parking": {
        "total": 0,
        "percentage": 0
      },
      "waiting": {
        "total": 0,
        "percentage": 0
      },
      "cleaning": {
        "total": 0,
        "percentage": 0
      },
      "discount": {
        "total": -325,
        "percentage": 0
      },
      "additional": {
        "total": 0,
        "percentage": 0
      }
    }
  },
  "passenger": {
    "fname": "John",
    "lname": "Doe",
    "email": "john@doe.com",
    "language": "EN",
    "phoneNumber": "+31612345678"
  },
  "paymentMeta": {
    "method": "bankTransfer",
    "description": "Online iDeal payment",
    "origin": "online",
    "moment": "beforeRide"
  }
}'

const request = require("request");

const options = { 
    method: 'POST',
    url: 'https://api.dispatchapi.io/api/rides',
    headers: { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body: { 
        passengerCount: 2,
        note: 'Add your notes here',
        requestedDate: '2018-01-15T09:11:29.653Z',
        language: 'EN',
        vehicleType: 'saloon',
        status: 'accepted',
        departure: { 
            city: 'Amsterdam',
            streetName: 'Oudezijdsvoorburgwal',
            postalCode: '1012EH',
            houseNumber: '3',
            internationalAlias: 'Hotel The Globe',
            countryCode: 'NL',
            gps: { 
                lat: '52.375259', 
                lng: '4.900178' 
            } 
        },
        destination: { 
            city: 'Schiphol',
            streetName: 'Aankomstpassage',
            postalCode: '1118CX',
            houseNumber: '1',
            internationalAlias: 'Schiphol Airport Amsterdam',
            countryCode: 'NL',
            gps: { 
                lat: '52.308896', 
                lng: '4.760862' 
            } 
        },
        price: {
            currency: 'EUR',
            total: 4400,
            breakdown: { 
               "route": {
                 "total": 4681,
                 "percentage": 9
               },
               "toll": {
                 "total": 0,
                 "percentage": 0
               },
               "parking": {
                 "total": 0,
                 "percentage": 0
               },
               "waiting": {
                 "total": 0,
                 "percentage": 0
               },
               "cleaning": {
                 "total": 0,
                 "percentage": 0
               },
               "discount": {
                 "total": -325,
                 "percentage": 0
               },
               "additional": {
                "total": 0,
                "percentage": 0
               }
             }
        },
        passenger: { 
            fname: 'John',
            lname: 'Doe',
            email: 'john@doe.com',
            language: 'EN',
            phoneNumber: '+31612345678' 
        },
        paymentMeta: { 
            method: 'bankTransfer',
            description: 'Online iDeal payment',
            origin: 'online',
            moment: 'beforeRide' 
        } 
    },
    json: true 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
    "passengerCount": 2,
    "intId": 101728,
    "origin": {
        "originId": "cd438dcc4b6cdb049245d448ead1c711",
        "name": "Karhoo"
    },
    "note": "Add your notes here",
    "departure": {
        "city": "Amsterdam",
        "streetName": "Oudezijdsvoorburgwal",
        "postalCode": "1012EH",
        "houseNumber": "3",
        "internationalAlias": "Hotel The Globe",
        "gps": {
            "lat": 52.375259,
            "lng": 4.900178
        },
        "countryCode": "NL"
    },
    "destination": {
        "city": "Schiphol",
        "streetName": "Aankomstpassage",
        "postalCode": "1118CX",
        "houseNumber": "1",
        "internationalAlias": "Schiphol Airport Amsterdam",
        "gps": {
            "lat": 52.308896,
            "lng": 4.760862
        },
        "countryCode": "NL"
    },
    "requestedDate": "2018-01-15T09:11:29.653Z",
    "status": "accepted",
    "language": "EN",
    "vehicleType": "saloon",
    "paymentMeta": {
        "method": "bankTransfer",
        "description": "Online iDeal payment",
        "origin": "online",
        "moment": "beforeRide"
    },
    "price": {
        "total": 4400,
        "currency": "EUR",
        "breakdown": { 
           "route": {
             "total": 4681,
             "percentage": 9
           },
           "toll": {
             "total": 0,
             "percentage": 0
           },
           "parking": {
             "total": 0,
             "percentage": 0
           },
           "waiting": {
             "total": 0,
             "percentage": 0
           },
           "cleaning": {
             "total": 0,
             "percentage": 0
           },
           "discount": {
             "total": -325,
             "percentage": 0
           },
           "additional": {
            "total": 0,
            "percentage": 0
           }
         }
    },
    "type": "ride",
    "id": "5a79c5e321e82c11c2d200db",
    "created": "2018-02-06T15:12:35.958Z",
    "modified": "2018-02-06T15:12:35.958Z",
    "expired": "2023-02-06T15:12:35.956Z",
    "companyId": "5a4c9680b2213be18a6ea19e",
    "rideLogId": "5a79c5e321e82c11c2d200d9",
    "passenger": {
        "fname": "John",
        "lname": "Doe",
        "email": "john@doe.com",
        "language": "EN",
        "phoneNumber": "+31612345678"
    }
}

This endpoint creates a ride

HTTP Request

POST https://api.dispatchapi.io/api/rides

Update ride details

curl -X PATCH \
  https://api.dispatchapi.io/api/rides/{id} \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "passengerCount": 3,
  "note": "Changed to 3 passengers",
  "status": "canceled"
}'

const request = require("request");

const options = { 
    method: 'PATCH',
    url: 'https://api.dispatchapi.io/api/rides/{id}',
    headers: { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body: { 
        passengerCount: 3,
        note: 'Changed to 3 passengers',
        status: 'canceled' 
    },
    json: true 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
    "passengerCount": 3,
    "intId": 101728,
    "origin": {
        "originId": "cd438dcc4b6cdb049245d448ead1c711",
        "name": "Karhoo"
    },
    "note": "Changed to 3 passengers",
    "departure": {
        "city": "Amsterdam",
        "streetName": "Oudezijdsvoorburgwal",
        "postalCode": "1012EH",
        "houseNumber": "3",
        "internationalAlias": "Hotel The Globe",
        "gps": {
            "lat": 52.375259,
            "lng": 4.900178
        },
        "countryCode": "NL"
    },
    "destination": {
        "city": "Schiphol",
        "streetName": "Aankomstpassage",
        "postalCode": "1118CX",
        "houseNumber": "1",
        "internationalAlias": "Schiphol Airport Amsterdam",
        "gps": {
            "lat": 52.308896,
            "lng": 4.760862
        },
        "countryCode": "NL"
    },
    "requestedDate": "2018-01-15T09:11:29.653Z",
    "status": "canceled",
    "language": "EN",
    "vehicleType": "saloon",
    "paymentMeta": {
        "method": "bankTransfer",
        "description": "Online iDeal payment",
        "origin": "online",
        "moment": "beforeRide"
    },
    "price": {
        "total": 4400,
        "currency": "EUR",
        "breakdown": { 
           "route": {
             "total": 4681,
             "percentage": 9
           },
           "toll": {
             "total": 0,
             "percentage": 0
           },
           "parking": {
             "total": 0,
             "percentage": 0
           },
           "waiting": {
             "total": 0,
             "percentage": 0
           },
           "cleaning": {
             "total": 0,
             "percentage": 0
           },
           "discount": {
             "total": -325,
             "percentage": 0
           },
           "additional": {
              "total": 0,
              "percentage": 0
            }
         }
    },
    "type": "ride",
    "id": "5a79c5e321e82c11c2d200db",
    "created": "2018-02-06T15:12:35.958Z",
    "modified": "2018-02-06T15:47:19.345Z",
    "expired": "2023-02-06T15:12:35.956Z",
    "companyId": "5a4c9680b2213be18a6ea19e",
    "rideLogId": "5a79c5e321e82c11c2d200d9",
    "passenger": {
        "fname": "John",
        "lname": "Doe",
        "email": "john@doe.com",
        "language": "EN",
        "phoneNumber": "+31612345678"
    }
}

This endpoint updates a driver based on its ID

HTTP Request

PATCH https://api.dispatchapi.io/api/ride/{id}

Query Parameters

Parameter Default Description
id null The ID of your ride

Ratings

Rating schema

Property Type Required Possible values
id String false 507f1f77bcf86cd799439011
comment String false Ferrari
score Number true 1, 2, 3, 4 or 5
type String true passenger or operator
driverId String false 507f1f77bcf86cd799439011
rideId String false 507f1f77bcf86cd799439011
companyId String false 507f1f77bcf86cd799439011
userId String false 507f1f77bcf86cd799439011
passengerId String false 507f1f77bcf86cd799439011

Create a new rating

curl -X POST \
  https://api.dispatchapi.io/api/ratings \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "comment": "The driver was very friendly!",
  "score": 5,
  "type": "passenger",
  "driverId": "5a79b46921e82c11c2d200c9",
  "rideId": "5a79c5e321e82c11c2d200db"
}'

const request = require("request");

const options = { 
    method: 'POST',
    url: 'https://api.dispatchapi.io/api/ratings',
    headers: { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body: { 
        comment: 'The driver was very friendly!',
        score: 5,
        type: 'passenger',
        driverId: '5a79b46921e82c11c2d200c9',
        rideId: '5a79c5e321e82c11c2d200db' 
    },
    json: true 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
    "comment": "The driver was very friendly!",
    "score": 5,
    "type": "passenger",
    "id": "5a7b13b721e82c11c2d200ec",
    "driverId": "5a79b46921e82c11c2d200c9",
    "rideId": "5a79c5e321e82c11c2d200db",
    "created": "2018-02-07T14:56:55.708Z",
    "modified": "2018-02-07T14:56:55.708Z",
    "expired": "2023-02-07T14:56:55.708Z"
}

This endpoint creates a rating

HTTP Request

POST https://api.dispatchapi.io/api/ratings

Update a rating

curl -X PATCH \
  https://api.dispatchapi.io/api/ratings/{id} \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "comment": "The driver was 15 minutes late.",
  "score": 2
}'

const request = require("request");

const options = { 
    method: 'PATCH',
    url: 'https://api.dispatchapi.io/api/ratings/{id}',
    headers: { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body: { 
        comment: 'The driver was 15 minutes late.', 
        score: 2 
    },
    json: true 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

{
    "comment": "The driver was 15 minutes late.",
    "score": 2,
    "type": "passenger",
    "id": "5a7b13b721e82c11c2d200ec",
    "driverId": "5a79b46921e82c11c2d200c9",
    "rideId": "5a79c5e321e82c11c2d200db",
    "created": "2018-02-07T14:56:55.708Z",
    "modified": "2018-02-07T15:05:09.306Z",
    "expired": "2023-02-07T14:56:55.708Z"
}

This endpoint updates a driver based on its ID

HTTP Request

PATCH https://api.dispatchapi.io/api/ratings/{id}

Query Parameters

Parameter Default Description
id null The ID of your rating

Offers

Offer schema

Property Type Required Possible values
id String false 507f1f77bcf86cd799439011
type String true driver or company
status String true ``
productType String true ride
settings String true {"maxOfferTime": 120}
drivers Array true ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439011"]
productId String false 507f1f77bcf86cd799439011
companyId String false 507f1f77bcf86cd799439011

Offer a ride

Please check the documentation over at ride offering

Prices

Price schema

Example Price object

{
  "total": 10000, 
  "currency": "EUR", 
  "breakdown": { 
    "route": {
      "total": 9174,
      "taxPercentage": 9
    },
    "toll": {
      "total": 0,
      "taxPercentage": 21
    },
    "parking": {
      "total": 0,
      "taxPercentage": 21
    },
    "waiting": {
      "total": 0,
      "taxPercentage": 21
    },
    "cleaning": {
      "total": 0,
      "taxPercentage": 21
    },
   "discount": {
     "total": 0,
     "taxPercentage": 0
   },
    "additional": {
      "total": 0,
      "taxPercentage": 0
    }
  }
}
Property Type Required Possible values
vehicleType String true Check the Vehicle schema
maxPassengers Number true 1
price Object true Check the JSON on the right
fixedPrice Boolean true true or false

Get prices per vehicle type

curl -X POST \
  https://sandbox.dispatchapi.io/api/prices \
  -H 'Authorization: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vehicleTypes": [
        "saloon",
        "estate",
        "bus"
    ],
    "checkAvailability": false,
    "passengerCount": 1,
    "requestedDate": "2017-18-01T12:30:00Z",
    "departure": {
        "city": "Amsterdam",
        "streetName": "Oudezijdsvoorburgwal",
        "postalCode": "1012ES",
        "houseNumber": "1",
        "internationalAlias": "Cafe bar the bulldog",
        "countryCode": "NL",
        "gps": {
            "lat": "52.373805",
            "lng": "4.896701"
        }
    },
    "destination": {
        "city": "Schiphol",
        "streetName": "Aankomstpassage",
        "postalCode": "1118AX",
        "houseNumber": "1",
        "internationalAlias": "Schiphol Airport Amsterdam",
        "countryCode": "NL",
        "gps": {
            "lat": "52.308896",
            "lng": "4.760862"
        }
    }
}'

const request = require("request");

const options = { 
    method: 'POST',
    url: 'https://sandbox.dispatchapi.io/api/prices',
    headers:  { 
        Authorization: 'YOUR_KEY',
        'Content-Type': 'application/json' 
    },
    body: { 
        vehicleTypes: ['saloon', 'estate', 'bus'],
        checkAvailability: false,
        passengerCount: 1,
        requestedDate: '2017-18-01T12:30:00Z',
        departure: { 
            city: 'Amsterdam',
            streetName: 'Oudezijdsvoorburgwal',
            postalCode: '1012ES',
            houseNumber: '1',
            internationalAlias: 'Cafe bar the bulldog',
            countryCode: 'NL',
            gps: { 
                lat: '52.373805', 
                lng: '4.896701' 
            } 
        },
        destination: { 
            city: 'Schiphol',
            streetName: 'Aankomstpassage',
            postalCode: '1118AX',
            houseNumber: '1',
            internationalAlias: 'Schiphol Airport Amsterdam',
            countryCode: 'NL',
            gps: { 
                lat: '52.308896', 
                lng: '4.760862' 
            } 
        } 
    },
    json: true 
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);
    console.log(body);
});

The above command returns JSON structured like this:

[
    {
        "vehicleType": "saloon",
        "maxPassengers": 4,
        "fixedPrice": true,
        "price": {
            "total": 6400,
            "currency": "EUR",
            "breakdown": { 
              "route": {
                "total": 6400,
                "taxPercentage": 9
              },
              "toll": {
                "total": 0,
                "taxPercentage": 21
              },
              "parking": {
                "total": 0,
                "taxPercentage": 21
              },
              "waiting": {
                "total": 0,
                "taxPercentage": 21
              },
              "cleaning": {
                "total": 0,
                "taxPercentage": 21
              },
             "discount": {
               "total": 0,
               "taxPercentage": 0
             },
              "additional": {
                "total": 0,
                "taxPercentage": 0
              }
            }
        }
    },
    {
        "vehicleType": "bus",
        "maxPassengers": 8,
        "fixedPrice": true,
        "price": {
            "total": 8150,
            "currency": "EUR",
            "tax" : {
                "total": 673,
                "percentage": 9
            },
            "breakdown": { 
              "route": {
                "total": 7477,
                "taxPercentage": 9
              },
              "toll": {
                "total": 0,
                "taxPercentage": 21
              },
              "parking": {
                "total": 0,
                "taxPercentage": 21
              },
              "waiting": {
                "total": 0,
                "taxPercentage": 21
              },
              "cleaning": {
                "total": 0,
                "taxPercentage": 21
              },
             "discount": {
               "total": 0,
               "taxPercentage": 0
             },
              "additional": {
                "total": 0,
                "taxPercentage": 0
              }
            }
        }
    }
]

This endpoint retrieves your company based on its ID.

HTTP Request

POST https://api.dispatchapi.io/api/prices

Shell Javascript