Blacklane Connector Core Specification

Blacklane REST Connector

Core Specification
version 1.7.0
DRAFT

1
Blacklane Connector Core Specification

Confidentiality Note
Please note that this is a confidential document and shall not be shared with any unauthorized
third parties.

2
Blacklane Connector Core Specification

Document Control
Company Blacklane GmbH | Feurigstraße 59 |
10827 Berlin | Germany

Department IT & Product Development

Author IT - Partner Integrations

Revision History
Version Date Change Comment By

1.6.0 ISSUED 2016-09-27 Initial core package of Andreea Tomoiaga

the Blacklane API
containing the following
functionality: pricing,
booking, cancellation,
get details of a booking
and the Assets API.

1.6.1_ISSUED 2017-01-13 Added possibility to Andreea Tomoiaga

enter number of
passengers and luggage
at the moment of
booking and validate
these inputs.

1.6.2_ISSUED 2017-04-05 Updated URL path so Andreea Tomoiaga

that the „rest“ part is
removed.
Provided additional
explanations on the
expiration policy.

1.6.3_ISSUED 2017-10-13 Added passenger locale Andreea Tomoiaga

(localization for email
and SMS notifications).

Added Certification
Appendix.

1.7.0_DRAFT 2023-11-30 Consolidation of Jan-Wilm Wittrock

documentation;
addition of new
"service_class" values
"electric_class",
"electric_sedan" and
"sprinter_class"; removal
of "service_class" value
"economy"; removal of
"passenger_local" values
"fi", "sv", "ar"; removed
"luggage_number.hand"
information from assets;
addition of assets for

3
Blacklane Connector Core Specification

Version Date Change Comment By

new "service_class"
values "electric_class",
"electric_sedan" and
"sprinter_class"; review
and update of values for
"booking_status" field;
removal of
"confirmation_status"
field and
"estimated_confirmation
_at" field from API
responses of /bookings
requests; addition of
"external_user_id" field
to API responses of
/bookings requests

4
Blacklane Connector Core Specification

Index
1 Overview 6
1.1 Who Should Read This Document 6
1.2 How to Access the Blacklane API 6
1.3 Authentication & Authorization 6
1.4 Prices 8
1.5 Address Resolution 8
1.6 Vehicle Classes, Vehicle Types and Associated Information 9
1.7 Bookings 9
1.8 Guest Passenger 10
1.9 Payment Methods 10
1.10 Update 10
1.11 Cancellation 11
1.12 Get Details Of A Booking 11
1.13 Error Handling 11
1.14 Booking Statuses 12
2 Authorization 13
2.1 Authorization Request 13
2.2 Authorization Response 14
3 Prices 16
3.1 Prices Request 16
3.2 Prices Response 17
4 Booking 25
4.1 Booking Request 25
4.2 Booking Response 28
5 Update 46
5.1 Update Request 46
5.2 Booking Update Response 49
6 Cancellation 53
6.1 Cancellation Request 53
6.2 Cancellation Response 54
7 Get Booking Details 57
7.1 Get Booking Details Request 57
7.2 Get Booking Details Response 58
8 Assets API 63
8.1 Assets Endpoint 63
8.2 Assets Request 63
8.3 Assets Response 63
9 API Support Contact 66
10 Appendix - API Examples 67
11 Appendix - Certification Process 68

5
Blacklane Connector Core Specification

1 Overview
This document gives a detailed overview of the Blacklane RESTful API Core Interface, its purpose
being to facilitate an easy B2B integration for an API partner.

The interface consists of the following features: authentication and authorization, obtaining prices,
performing bookings, gathering the details of a previously made booking, updating a previously
made booking, cancellation of a previous booking and the assets API which offers retrieval of
Blacklane specific artifacts such as cancellation policy, meet and greet text and similar resources in
various languages, delivering also URLs to resources (vehicle images, Blacklane logo).

Subsequent sections describe general information needed in order to be able to integrate the
Blacklane API and lists the main aspects of each of the aforementioned features.

1.1 Who Should Read This Document

The main audience for this document is the technical team working on integrating the Blacklane
API and its primary aim is to consider all information needed in order to proceed with the
implementation in an optimal manner, such as: description of endpoints provided, encompassing
a detailed presentation of requests, responses and error messages.

Each message will be listed with all their fields, significance, data types, specifying if they are
mandatory or optional.

1.2 How to Access the Blacklane API

In order to be able to use the Blacklane API, you will need access to two environments:

● Sandbox
This represents the environment used in order to develop and test the Blacklane API. It
also includes any preparation activities needed before going live.

Accessible under the following URL:

https://rest-sandbox.blacklane.com/v1.0/oauth/token

● Production
This represents the actual production environment and access to it will be granted only
after all preparation for integration performed in the Sandbox environment has been
successfully accomplished.

Accessible under the following URL:

The production URL will be shared after a successful certification of the integration.

1.3 Authentication & Authorization

The authentication and authorization are performed using the OAuth2 protocol and these are
based on the client credentials assigned for an API partner. The result returned contains the
access token, its type and its validity period.

6
Blacklane Connector Core Specification

The client credentials consist of a client ID and a client secret, each client ID uniquely identifying
an API partner in a certain deployment environment (which is either Sandbox or Production). This
means that each API partner will have a unique client ID assigned for each environment.

The endpoint used to implement authentication is /oauth/token with HTTP method POST and it
implements a proactive approach of automatically extending the lifetime of valid tokens by issuing
new ones in a timely manner, as outlined in the example below.

1. In order to obtain a new valid token, the POST /oauth/token endpoint is invoked.

2. A valid token is returned successfully, let us call it token A which has a validity period of six
months.

3. Five months later, POST /auth/token is invoked again.

4. A new token, let us call it token B, will be generated successfully as result of the call at
point 3 above. Its validity interval will be six months.

5. At this moment we have two tokens, one with a validity interval of one month and the
other one with a validity interval of six months.

6. After one month we would have token A as expired already and token B with a validity
interval of five months.

This way we proactively generate tokens with a prolonged validity interval without making the API
client having to deal with error handling in case of token expiry, which would be the case, should
these tokens not be issued in advance.

1.3.1 Usage Sample

In order to get access to the Prices/Booking API, the client needs to be authenticated and should
get the authentication token first.

It is achievable through the POST request to the /oauth/token endpoint.

Request

curl -X POST -d"client_id=yourClientId&client_secret=yourClientSecret&grant_type=client_credentials"

Response

{
"result": {
"access_token": "newToken",
"token_type": "bearer",
"expires_in": 10271211
}
}

Each token has an expiration time returned in the response. The "expires_in" value is represented
in seconds and equals to 6 months by default. This means that the client can generate a token
once and use it for six months with all requests.

7
Blacklane Connector Core Specification

When six months pass by, the token will expire and the client has to create a new token again by
sending the request above.

In cases when the expired token is used at prices/booking requests then a token_expired error will
be returned in the response with a 401 HTTP status code.

Response

{
"errors": [
{
"message": "token_expired",
"description": "The provided access token has expired - please request a new one via POST
/oauth/token."
}
]
}

In such a case, a new token has to be issued again by sending the request above.

1.4 Prices
A precondition to use this functionality is to be successfully authenticated into the Blacklane
Sandbox or Production environment.

This feature is implemented through the /prices endpoint, with the HTTP method GET. It allows
an API partner to obtain the prices for a tour based on service type (either "transfer" or "hourly"),
departure date and time, pickup location and drop-off location. In case of hourly tours, duration is
supplied.

For a detailed description of the various options of specifying pickup and drop-off locations,
please read the subsequent section on „Address Resolution“.

Voucher codes can be entered, too, and will be taken into account as part of the price
computation.

A successful response from this call will contain pricing information for all vehicle types and
service classes provided by Blacklane.

For more details on the vehicle types and service classes available, please see the section on
„Service Classes, Vehicle Types and Associated Information“ below.

1.5 Address Resolution

This section describes the logic used in order to resolve pickup and drop-off locations provided as
input to either /prices or /bookings endpoints.

There are three options available, meaning that you can specify a location using the following
mechanisms (exclusive to each other):

8
Blacklane Connector Core Specification

1. Airport IATA
2. Address string + geo coordinates (we only accept address strings if combined with geo
coordinates)

If options that are not mutually exclusive are supplied, the following validation errors will be
generated: "pickup_conflict", "dropoff_conflict" and "pickup_and_dropoff_conflict", respectively,
depending on the field where the conflicting input occurred.

The system checks if the location data provided falls within the business districts currently
supported and if this is the case, the request will succeed.

1.6 Vehicle Classes, Vehicle Types and Associated Information

The table below explains the vehicle categories and vehicle makes, the number of allowed
passengers and luggage, private and shared characteristics of the available vehicles.

Vehicle Class Type Make (similar) Guests Luggage

Business Class sedan Mercedes E-Class, max. 3 max. 2

BMW 5 Series,
Cadillac XTS or
similar

Business Van van Mercedes V-Class, max 5 max. 5

Chevrolet
Suburban,
Cadillac Escalade
or similar

First Class sedan Mercedes S-Class, max. 3 max. 2

BMW 7 Series, Audi
A8 or similar

Electric Class sedan Jaguar I-PACE, max. 3 max. 2

Tesla Model S,
Tesla Model X or
similar

Electric Sedan sedan Mercedes-Benz max. 2 max. 2

EQS or similar

Sprinter Class sprinter Mercedes Sprinter max. 12 max. 12

or similar

1.7 Bookings
A precondition to use this functionality is to be successfully authenticated into the Blacklane
Sandbox or Production environment.

The possibility to place a booking for a tour with Blacklane is implemented through the /bookings
endpoint with HTTP method POST.

A booking will be placed based on the following input data: service type (either "transfer" or
"hourly"), departure date and time, pickup location and drop-off location, passenger data and

9
Blacklane Connector Core Specification

payment method (either „credit card“ or „corporate payment method“). Voucher codes can be
entered and will be taken into account as part of the price computation.

For more details on passenger data, please see section „Guest Passenger“ below.

For more details on payment, please see the section regarding „Payment Methods“ below.

If either the pickup or the drop-off location is an airport, then the airline code and flight number
are input data that can be supplied. External IDs identifying the source of the booking or external
user IDs identifying loyalty programs for a certain passenger can also be passed within a tour
booking.

In case of hourly tours, duration is required to be supplied.

Additional data such as special requests, a reference to include on the invoice, the pickup sign
and the possibility to configure SMS notifications can be supplied, too.

A successful return from this endpoint will contain all information associated with this booking,
including the confirmation number (the "booking_number" field).

1.8 Guest Passenger

In the case the booking is performed via B2B integration, coming from an API Partner, guest
bookings will be created.

This means that the provider passenger data received with the booking is treated on Blacklane
side as a guest user.

1.9 Payment Methods

Blacklane supports two types of payment that influence the way invoicing is handled:

● „credit card“ which requires input data such as credit card holder name, credit card
number, expiry year, expiry month and CVV. In this case, an invoice is generated for each
and every ride and is sent to the customer after the booking is successfully performed.

● „corporate payment method“ which requires a "corporation_uuid" to be supplied. This

"corporation_uuid" value will be established with Blacklane when starting the API
integration. In this case, an invoice is generated monthly and is sent to the
company/corporate which performed the bookings during that month.

1.10 Update
A precondition to use this functionality is to be successfully authenticated into the Blacklane
Sandbox or Production environment.

This feature allows an API partner to update a previously performed booking with Blacklane. The
endpoint that implements this functionality is /bookings with HTTP method PUT.

10
Blacklane Connector Core Specification

The booking to be updated can be specified either via Blacklane booking identifier (UUID),
Blacklane booking number, or through external ID.

1.11 Cancellation
A precondition to use this functionality is to be successfully authenticated into the Blacklane
Sandbox or Production environment.

This feature allows an API partner to cancel a previously performed booking with Blacklane. The
endpoint that implements this functionality is /bookings with HTTP method DELETE.

The booking to be cancelled can be specified either via booking confirmation number, or through
external ID or through Blacklane booking identifier (UUID).

The cancellation obeys to the cancellation policy as outlined in Blacklane’s terms and conditions:
https://www.blacklane.com/en/terms/

1.12 Get Details Of A Booking

A precondition to use this functionality is to be successfully authenticated into the Blacklane
Sandbox or Production environment.

This feature allows an API partner to retrieve a previously performed booking with Blacklane. The
endpoint that implements this functionality is /bookings with HTTP method GET.

The booking can be retrieved either via booking confirmation number, or through external ID or
via Blacklane booking identifier (UUID).

1.13 Error Handling

A uniform message structure and approach to error handling has been envisaged for all
endpoints.

The fields returned in case of error are as follows:

Name Description Data Type

message Unique key identifying the error. string (128)

description The error description. string (300)

errors The array of errors captured in a certain scenario. array of Error

For all error cases listed in subsequent „Errors“ sections below, for each and every endpoint, the
"message" field is the one to be used in order to perform error handling logic. Please note that
the associated description (the "description" field inside the "error") is subject to change.

11
Blacklane Connector Core Specification

1.14 Booking Statuses

The following statuses are encountered throughout the lifecycle of a booking/ride:

Status Explanation

confirmed The ride you booked has been confirmed by Blacklane.

before The chauffeur is on the way to the pickup location.

pickup The chauffeur arrived at the pickup location.

during The ride is ongoing, the passenger being on board.

wait_time The chauffeur is required to wait beyond the complimentary waiting time
at pickup or if the passenger requests some interruption during the ride.

route_changed The route of the ride has been changed by the chauffeur.

kilometers_exceeded The kilometers initially envisaged with the booking have been exceeded.

hours_exceeded The hours initially envisaged with the booking have been exceeded.

finished The ride has finished.

no_show The passenger did not show up at the specified pickup location in order
to take the ride.

driver_no_show The chauffeur did not show up at the specified pickup location in order
to perform the ride.

rejected The booking has been rejected.

driver_emergency_cancel The booking has been cancelled by the chauffeur.

canceled_by_passenger The booking has been cancelled by the passenger.

canceled_by_admin The booking has been cancelled by a Blacklane employee.

12
Blacklane Connector Core Specification

2 Authorization
This section describes the endpoint to be used in order to authenticate and authorize to the
Blacklane API. This is a precondition for doing any other operation, specified by all other
endpoints (prices, bookings, etc.).

Each API client will have a client ID and an associated client secret assigned, the management of
these being possible via the /oauth/token endpoint.

Credentials will have a certain expiration period associated with them but will dynamically
generate new tokens for a given client ID, as result of the invocation of this endpoint.

This way a proactive strategy of refreshing tokens with regards to their validity is performed so
that the API client does not have to reactively deal with token expiry.

Endpoint Call /oauth/token

Description Creates an access token based on the OAuth2

protocol for either a passenger or client.

HTTP Method POST

2.1 Authorization Request

2.1.1 HTTP Headers

Name Value

Content-Type application/json

2.1.2 Request Parameters

Name Description Required? Data Type

grant_type Grant type to be provided. Valid values are: yes string (32)
"client_credentials" and "password".
API clients are authenticated and authorized via
"client_credentials", the bookings performed
using these credentials being guest bookings.

client_id The "client_id" Blacklane has provided you with. yes string (255)

client_secret The "client_secret" Blacklane has provided you yes string (255)
with.

username The user’s email address. no string (255)

password The user's password. no string (255)

13
Blacklane Connector Core Specification

2.2 Authorization Response

2.2.1 HTTP Headers

Name Value

Content-Type application/json

2.2.2 Response Body (Success)

HTTP Status Code 200

Description Authorization token has been successfully created

or retrieved.

Name Description Data Type

access_token The access token in string format. string (32)

token_type The token’s type. Returned value is "bearer". string (32)

expires_in The amount of time (in seconds) for which the supplied token integer
is valid, for example 10271211.

2.2.3 Response Body (Failure)

Name Description Data Type

message Unique key identifying the error. string (128)

description The error description. string (300)

errors The array of errors captured in a certain scenario. array of Error

The next section outlines all possible values returned for the error related fields mentioned in the
table above.

2.2.4 Errors
HTTP Error Key Reason Error JSON Message
Status Code

422 grant_type_invalid Invalid grant_type. {

"errors": [
{
"message": "grant_type_invalid",
"description": "The provided grant_type
should be one of: client_credentials, password."
}
]
}

14
Blacklane Connector Core Specification

422 username_or Wrong username or {

_password_invalid password. "errors": [
{
"message":
"username_or_password_invalid",
"description": "The provided username or
password was incorrect."
}
]
}

422 client_invalid Invalid client_id or {

client_secret. "errors": [
{
"message": "client_invalid",
"description": "The provided client_id or
client_secret was incorrect or the client was
revoked."
}
]
}

15
Blacklane Connector Core Specification

3 Prices
This section describes the endpoint to be used in order to obtain a response with prices from
Blacklane.

Endpoint Call /prices

Description Retrieves prices for the ride details (location, time

etc.) provided.

HTTP Method GET

3.1 Prices Request

3.1.1 HTTP Headers

Name Description Required? Data Type

Authorization The user access token of "bearer" type that has yes string
been obtained previously as a successful response
after invoking the authorization endpoint.
Value: Bearer [user_access_token].

3.1.2 Request Parameters

Name Description Required? Data Type

depart_at The departure date-time expressed in ISO-8601 yes string

datetime format - e.g. "2015-11-21T14:00:00".

service_type The service type. yes string

Valid values are "transfer" and "hourly".

pickup_address Pickup address - e.g. "Oranienstraße 199, 10999, *see „Address string (255)
Berlin". Resolution”
section

pickup_latitude Pickup point latitude - e.g. "52.500023". *see „Address double

It is stored as decimal (9, 6). Resolution”
section

pickup_longitude Pickup point longitude - e.g. "13.424148". *see „Address double

It is stored as decimal (9, 6). Resolution”
section

pickup_airport_iata An airport IATA code replacing the pickup address *see „Address string (4)
- e.g. "BER" for Berlin Brandenburg Airport. Resolution”
section

pickup_place_id The Google Place ID identifying the pickup no string (255)

location.

dropoff_address Dropoff address - e.g. "Feurigstraße 59, 10827 *see „Address string (255)
Berlin". Resolution”
section

16
Blacklane Connector Core Specification

dropoff_latitude Dropoff point latitude - e.g. "52.485313". *see „Address double

It is stored as decimal (9, 6). Resolution”
section

dropoff_longitude Dropoff point longitude - e.g. " 13.357660". *see „Address double
It is stored as decimal (9, 6). Resolution”
section

dropoff_airport_iata An airport IATA code replacing the dropoff address *see „Address string (4)
- e.g. "BER" for Berlin Brandenburg Airport. Resolution”
section

dropoff_place_id The Google Place ID identifying the dropoff no string (255)

location.

duration Ride duration in seconds - e.g. "7200" for a 2-hour yes, if integer
ride. Please note that this is stored as unsigned "service_type"
integer. is "hourly"

corporation_uuid The corporation UUID to handle payment no string (255)

(alternative to credit card related fields).

voucher_code Voucher code - e.g. "BNG5SK8F". no string (255)

3.2 Prices Response

3.2.1 HTTP Headers

Name Value

Content-Type application/json

3.2.2 Response Body (Success)

HTTP Status Code 200

Description Successful /prices response.

Name Description Required? Data type

common A common consisting of the main booking yes common

parameters. For example: composite
type
{
"common": {
"depart_at": "2024-06-01T10:30:00+02:00",
"service_type": "transfer",
"pickup_address": "Berlin Brandenburg
Airport (BER), All terminals, Exit after baggage
claim, Flughafen 1, 12529 Berlin, Schönefeld",
"pickup_latitude": "52.388794",
"pickup_longitude": "13.518361",
"pickup_airport_iata": "BER",

17
Blacklane Connector Core Specification

"pickup_place_id":
"U:YTRlN2U0ZDQtMDVhOC00YzkwLTlhNWQtNW
VlNGY0ZGQ1YzA1",
"dropoff_address": "Blacklane GmbH,
Feurigstrasse 59, 10827, Berlin",
"dropoff_latitude": "52.484997",
"dropoff_longitude": "13.357138",
"estimated_duration": 1255
}

depart_at ISO-8601 datetime - e.g. "2015-11-21T14:00:00". yes string

service_type The service type, e.g. "transfer". yes string (20)

pickup_address Pickup address - e.g. "Oranienstraße 199, 10999, yes string (255)
Berlin".

pickup_latitude Pickup point latitude - e.g. "52.500023". yes double

pickup_longitude Pickup point longitude - e.g. "13.424148". yes double

pickup_airport_iata An airport IATA code - e.g. "BER" for Berlin no string (4)
Brandenburg Airport.

pickup_place_id The Google Place ID identifying the pickup no string (255)

location.

dropoff_address Dropoff address - e.g. "Feurigstraße 59, 10827 yes, if string (255)
Berlin". "service_type"
is "transfer"

dropoff_latitude Dropoff point latitude - e.g. "52.485313". yes, if double

"service_type"
is "transfer"

dropoff_longitude Dropoff point longitude - e.g. "13.357660". yes, if double

"service_type"
is "transfer"

dropoff_airport_iata An airport IATA code - e.g. "BER" for Berlin no string (4)
Brandenburg Airport.

dropoff_place_id The Google Place ID identifying the drop-off no string (255)

location.

estimated_duration The estimated duration of a transfer ride. yes, if integer

"service_type"
is "transfer"

included_distance The included distance for an hourly ride. yes, if integer

"service_type"
is "hourly"

duration The duration in seconds. It will be returned under yes, if integer

the "common" composite type. "service_type"
Considered as decimal (11, 4). is "hourly"

results An array of information including pricing for yes results array

available vehicle types. The array of "price_items" of composite
contains a decomposition of the price into types
components specified by "type". For example:

18
Blacklane Connector Core Specification

"results": [
{
"vehicle_type": "business_class",
"max_passengers": 3,
"max_luggage": 2,
"currency": "EUR",
"total_amount": 9873,
"net_amount": 8978,
"vat_amount": 895,
"vat_rate": 0.1,
"image_url":
"https://content.blacklane.com/api/business_class
_160x100.png",
"price_items": [
{
"type": "base_price",
"currency": "EUR",
"total_amount": 8719,
"net_amount": 7927,
"vat_amount": 792,
"vat_rate": 0.1
},
{
"type": "meet_and_greet",
"currency": "EUR",
"total_amount": 495,
"net_amount": 450,
"vat_amount": 45,
"vat_rate": 0.1
}
]

vehicle_type The vehicle type with possible values: yes string (30)
"business_class", "first_class", business_van",
"electric_class", "electric_sedan", "sprinter_class".

max_passengers Maximum number of passengers. yes integer

max_luggage Maximum number of luggage. yes integer

currency The currency. yes string (3)

total_amount Total amount in cents. yes integer

It will be stored as decimal (11, 4).

net_amount Net amount in cents. yes integer

It will be stored as decimal (11, 4).

vat_amount VAT amount in cents. yes integer

It will be stored as decimal (11, 4).

vat_rate VAT rate. yes double

It will be stored as decimal (11, 4).

image_url The URL to the vehicle image corresponding to the yes string (255)
vehicle class for which the price is computed.

type Specifies the type of "price_item"with possible yes string (255)

values "base_price", "meet_and_greet",
"lead_time_surcharge", "insurance" and "rebate".

19
Blacklane Connector Core Specification

3.2.3 Response Body (Failure)

Name Description Data Type

message Unique key identifying the error. string (128)

description The error description. string (300)

errors The array of errors captured in a certain scenario. array of Error

The next section outlines all possible values returned for the error related fields mentioned in the
table above.

3.2.4 Errors
HTTP Error Key Reason Error Description
Status Code (JSON Message)

401 unauthorized The access token is {

either missing or "errors": [
invalid. {
"message": "unauthorized",
"description": "The access token is either
missing or invalid."
}
]
}

401 token_expired The provided {

access token has "errors": [
expired. {
"message": "token_expired",
"description": "The provided access token
has expired - please request a new one via POST
/oauth/token."
}
]
}

422 depart_at_missing The departure_at {

parameter is "errors": [
missing. {
"message": "depart_at_missing",
"description": "The departure date is
missing."
}
]
}

422 depart_at_invalid The departure_at {

parameter is not a "errors": [
valid ISO-8601 {
datetime. "message": "depart_at_invalid",
"description": "The depart_at parameter
should be a valid ISO-8601 datetime object."

20
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

}
]
}

422 depart_at_in_the The departure_at {

_past parameter should "errors": [
be a date in the {
future. "message": "depart_at_in_the_past",
"description": "The departure date can not
be in the past."
}
]
}

422 depart_at_too_ The departure_at {

early parameter should "errors": [
be a date at least {
60 minutes in the "message": "depart_at_too_early",
future. "description": "You may only book at least
60 minutes prior to your departure."
}
]
}

422 depart_at_no_ No prices could be {

prices_found found for the "errors": [
provided depart_at {
parameter. "message": "depart_at_no_prices_found",
"description": "We could not calculate any
prices for your requested date.“
}
]
}

422 service_type_ The service_type {

missing parameter is "errors": [
missing. {
"message": "service_type_missing",
"description": "The service_type parameter
is missing."
}
]
}

422 service_type_ The service_type {

invalid parameter is "errors": [
invalid. {
"message": "service_type_invalid",
"description": "The service_type parameter
should be one of: transfer, hourly."
}
]
}

422 pickup_missing One or more {

pickup_* "errors": [

21
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

parameters are {
missing. "message": "pickup_missing",
"description": "Either pickup_airport_iata, or
all of the pickup_address, pickup_latitude,
pickup_longitude parameters have to be
provided."
}
]
}

422 pickup_invalid One or more of the {

provided pickup_* "errors": [
parameters are {
invalid. "message": "pickup_invalid",
"description": "One or more of the provided
pickup_* parameters are invalid."
}
]
}

422 dropoff_missing One or more {

dropoff_* "errors": [
parameters are {
missing. "message": "dropoff_missing",
"description": "Either dropoff_airport_iata,
or all of the dropoff_address, dropoff_latitude,
dropoff_longitude parameters have to be
provided.“
}
]
}

422 dropoff_invalid One or more of the {

provided dropoff_* "errors": [
parameters are {
invalid. "message": "dropoff_invalid",
"description": "One or more of the provided
dropoff_* parameters are invalid.“
}
]
}

422 pickup_conflict Conflicting pickup {

parameters. "errors": [
{
"message": "pickup_conflict",
"description": "The provided pickup_*
parameters are mutually exclusive."
}
]
}

422 dropoff_conflict Conflicting dropoff {

parameters. "errors": [
{
"message": "dropoff_conflict",

22
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

"description": "The provided dropoff_*

parameters are mutually exclusive."
}
]
}

422 pickup_and_dropof Conflicting pickup {

f_conflict and dropoff "errors": [
parameters. {
"message": "pickup_and_dropoff_conflict“,
"description": "The provided pickup_* and
dropoff_* parameters are mutually exclusive."
}
]
}

422 area_not_covered The provided {

pickup and dropoff "errors": [
locations are not {
covered by "message": "area_not_covered",
Blacklane "description": "The provided pickup and
dropoff locations are not covered by Blacklane."
}
]
}

422 duration_missing The duration {

parameter is "errors": [
missing. {
"message": "duration_missing",
"description": "Duration is missing."
}
]
}

422 duration_invalid The duration {

parameter should "errors": [
be a multiple of {
3600, equal or "message": "duration_invalid",
greater than 7200 "description": "The duration parameter
(2 hours). should be an integer equal or greater than 7200
(2 hours)."
}
]
}

422 corporation_uuid The {

_invalid corporation_uuid "errors": [
could not be {
resolved to an "message": "corporation_uuid_invalid",
existing "description": "The corporation_uuid
corporation. parameter could not be resolved to an existing
corporation."
}
]
}

23
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 voucher_code_ The voucher_code {

invalid was invalid. "errors": [
{
"message": "voucher_code_invalid",
"description": "The voucher code you
provided is invalid."
}
]
}

24
Blacklane Connector Core Specification

4 Booking
This section describes the endpoint to be used in order to place a booking for a ride with
Blacklane.

Endpoint Call /bookings

Description Creates a booking request.

HTTP Method POST

4.1 Booking Request

4.1.1 HTTP Headers

Name Description Required? Data Type

Authorization The user access token of "bearer" type that has yes string
been obtained previously as a successful response
after invoking the authorization endpoint.
Value: Bearer [user_access_token].

4.1.2 Request Parameters

Name Description Required? Data Type

depart_at The departure date-time expressed in ISO-8601 yes date-time

datetime format - e.g. "2015-11-21T14:00:00".

service_type The service type. yes string (20)

Valid values are "transfer" and "hourly".

vehicle_type Vehicle type, e.g. "business_class". yes string (30)

Valid values are "business_class", "business_van"
and "first_class", "electric_class", "sprinter_class".

pickup_address Pickup address - e.g. "Oranienstraße 199, 10999, *see „Address string (255)
Berlin". Resolution”
section

pickup_latitude Pickup point latitude - e.g. "52.500023". *see „Address double

It is stored as decimal (9, 6). Resolution”
section

pickup_longitude Pickup point longitude - e.g. "13.424148". *see „Address double

It is stored as decimal (9, 6). Resolution”
section

pickup_airport_iata An airport IATA code replacing the pickup address *see „Address string (4)
- e.g. "BER" for Berlin Brandenburg Airport. Resolution”
section

pickup_place_id The Google Place ID identifying the pickup no string (255)

location.

25
Blacklane Connector Core Specification

Name Description Required? Data Type

dropoff_address Dropoff address - e.g. "Feurigstraße 59, 10827 *see „Address string (255)
Berlin". Resolution”
section

dropoff_latitude Dropoff point latitude - e.g. "52.485313". *see „Address double

It is stored as decimal (9, 6). Resolution”
section

dropoff_longitude Dropoff point longitude - e.g. " 13.357660". *see „Address double
It is stored as decimal (9, 6). Resolution”
section

dropoff_airport_iata An airport IATA code replacing the dropoff address *see „Address string (4)
- e.g. "BER" for Berlin Brandenburg Airport. Resolution”
section

dropoff_place_id The Google Place ID identifying the dropoff no string (255)

location.

duration Ride duration in seconds - e.g. "7200" for a 2-hour yes, if integer
ride. Please note that this is stored as unsigned "service_type"
integer. is "hourly"

credit_card_holder Credit Card holder name. no string (255)

credit_card_number Credit Card number. no string (255)

credit_card_expiry_ Credit Card expiry month - e.g. "09" for the month no string (255)
month of September.

credit_card_expiry_y Credit Card expiry year - e.g. "2018". no string (255)

ear

credit_card_cvv Credit card CVV - e.g. "123". no string (3)

corporation_uuid The corporation UUID to handle payment no string (255)

(alternative to credit card related fields).

voucher_code Voucher code - e.g. "BNG5SK8F". no string (255)

passenger_count Number of passengers expected for the ride - e.g. no integer

"2".

luggage_count Number of check-in luggage expected for the ride, no integer

e.g. "1".

passenger_title Passenger's title. no string (255)

passenger_first_nam Passenger's first name. yes string (255)

e

passenger_last_nam Passenger's last name. yes string (255)

e

passenger_email Passenger's email. yes string (255)

passenger_mobile Passenger's mobile phone number. yes string (255)

airline_code Airline code for the flight, e.g. "AB" for Air Berlin. no string (2)
Discarded unless you provide the "flight_number".

26
Blacklane Connector Core Specification

Name Description Required? Data Type

flight_number Flight number without the airline code - e.g. no string (25)
"6446". Discarded unless you provide the
"airline_code".

pickup_sign Text to be written on the pick up sign, usually the no string (255)
name of a person or company - e.g. "John Doe".

special_requests Additional requirements by the passenger. no string (stored

as text, 64 KB
maximum)

send_sms Whether to send SMS notifications when the no boolean

chauffeur is on his way or has reached the pick-up
location.

reference A reference number to include in the invoice. no string (255)

billing_company_na Billing payer’s name. no string (255)

me

billing_title Billing details - payer’s title. no string (255)

billing_first_name Billing details - payer’s first name. no string (255)

billing_last_name Billing details - payer’s last name. no string (255)

billing_street_addre Billing details - street address. no string (255)

ss

billing_city Billing details - city. no string (255)

billing_postal_code Billing details - postal code. no string (255)

billing_country_cod Billing details - country code. no string (255)

e

passenger_locale Represents the locale of the passenger and no, string (2)
indicates the language in which language default is "en"
dependent assets such as meeting instructions
should be delivered. Currently the following
languages are supported: "en", "de" and "fr".

external_id An optional identifier for the ride provided by the no string (36)
API client. This value cannot be changed when
updating a booking.

external_user_id An optional identifier for the user provided by the no string (255)
API client. This value cannot be changed when
updating a booking.

nonce A unique nonce string to prevent double no string (36)

bookings.

27
Blacklane Connector Core Specification

4.2 Booking Response

4.2.1 HTTP Headers

Name Value

Content-Type application/json

4.2.2 Response Body (Success)

HTTP Status Code 201

Description Booking request has been created successfully.

Name Description Required? Data Type

uuid The UUID of the booking - e.g. yes string (36)

"19419389-c73c-4a0c-b7bb-38cdb9788c24".

booking_number The number associated with this booking - e.g. yes string (255)
"20150520-2945138".

external_id The external ID provided from the API client used no string (36)
as a means to uniquely identify the booking.
This value cannot be changed when updating a
booking.

external_user_id An optional identifier for the user provided by the no string (255)
API client. This value cannot be changed when
updating a booking.

booking_status The status of the booking. yes string (30)

For an explanation of relevant API statuses, please
see section 1.13 at the start of the document.

pickup_sign The text for the pickup sign. no string (255)

airline_code The airline code e.g. - "AB" for Air Berlin. no string (2)

flight_number The flight number e.g. "6446". no string (16)

reference A reference for the customer invoice e.g. - no string (255)

"INV-2431".

send_sms A flag indicating if an SMS should be sent or not. no boolean

depart_at The date and time of the departure ISO-8601 yes string
datetime format e.g. - "2015-11-21T14:00:00".

service_type The service type. yes string (20)

Valid values are "transfer" and "hourly".

estimated_confirmat The estimated date time for the confirmation in no string

ion_at ISO format e.g. - "2015-05-20T16:21:38".

passenger_count Number of passengers expected for the ride - e. g. no integer

"2".

28
Blacklane Connector Core Specification

Name Description Required? Data Type

luggage_count Number of check-in luggage expected for the ride, no integer

e. g. "1".

vehicle_type Vehicle type, e.g. "business_class". yes string (30)

Valid values are "business_class", "business_van",
"first_class", "electric_class", "sprinter_class".

vehicle_max_luggag The maximum luggage allowed for a certain yes integer

e vehicle type e.g. - "2".

vehicle_max_passen The maximum number of passengers allowed for a yes integer

gers certain vehicle type e.g. - "3".

confirmation_status The confirmation status of the booking e.g. - yes string (30)
"open". Possible values are: "open", "accepted"
and „rejected".

price Contains tour price information with details as yes price

conveyed by the following composite type: composite
type
"price": { containing
"currency": "EUR“, following
"total_amount“: 4217, fields:
"net_amount": 3543,
"vat_amount": 674, - currency:
"vat_rate": 0.19 string (3)
} (required)
-
All double amount values are stored as decimal total_amount:
(11, 4). double
(required)
- net_amount:
double -
(required)
- vat_amount:
double
(required)
- vat_rate:
double
(required)

estimated_duration The estimated duration of a transfer ride. yes, if integer

"service_type"
is "transfer"

included_distance The included distance for an hourly ride. yes, if integer

"service_type"
is "hourly"

duration The duration in seconds. It will be returned under yes, if integer

the "common" composite type. "service_type"
Considered as decimal (11, 4). is "hourly"

pickup_address Pickup address - e.g. "Oranienstraße 199, 10999, yes string (255)
Berlin".

pickup_latitude Pickup point latitude - e.g. "52.500023". yes double

pickup_longitude Pickup point longitude - e.g. "13.424148". yes double

29
Blacklane Connector Core Specification

Name Description Required? Data Type

pickup_airport_iata An airport IATA code - e.g. "BER" for Berlin no string (4)
Brandenburg Airport.

pickup_place_id The Google Place ID identifying the pickup no string (255)

location.

dropoff_address Dropoff address - e.g. "Feurigstraße 59, 10827 yes, if string (255)
Berlin". "service_type"
is "transfer"

dropoff_latitude Dropoff point latitude - e.g. "52.485313". yes, if double

"service_type"
is "transfer"

dropoff_longitude Dropoff point longitude - e.g. "13.357660". yes, if double

"service_type"
is "transfer"

dropoff_airport_iata An airport IATA code - e.g. "BER" for Berlin no string (4)
Brandenburg Airport.

dropoff_place_id The Google Place ID identifying the dropoff no string (255)

location.

passenger_title The passenger’s title e.g. "Mr", "Ms" or yes string (255)
"unknown"

passenger_first_nam The passenger's first name e.g. "Michael". yes string (255)
e

passenger_last_nam The passenger's last name e.g. "Mueller". yes string (255)
e

passenger_email The passenger’ s email e.g. yes string (255)

"[email protected]".

passenger_mobile The passenger’s mobile phone number e.g. yes string (255)
"+4900000000000".

passenger_locale The selected locale for the booking yes string (2)
communication.

special_requests Additional requirements by the passenger. no string

(stored as text,
64 KB
maximum)

billing_company_na Billing payer’s name. no string (255)

me

billing_title Billing details - payer’s title. no string (255)

billing_first_name Billing details - payer’s first name. no string (255)

billing_last_name Billing details - payer’s last name. no string (255)

billing_street_addre Billing details - street address. no string (255)

ss

billing_city Billing details - city. no string (255)

billing_postal_code Billing details - postal code. no string (255)

30
Blacklane Connector Core Specification

Name Description Required? Data Type

billing_country_cod Billing details - country code. no string (255)

e

corporation_uuid The corporation UUID provided with the booking no string (255)
request.

invoiced Flag indicating if the invoice corresponding to the yes boolean

booking has been created.

payment_method_t The type of payment method used for the yes string (255)
ype booking. Valid values are "collective_invoice",
"credit_card".

payment_method_l The label for the payment method used on yes string (255)
abel Blacklane side, e.g. the corporation name.

meeting_instruction Field indicating general meeting instructions for yes string (255)
s the chauffeur and passenger at various address
types.

4.2.3 Response Body (Failure)

Name Description Data Type

message Unique key identifying the error. string (128)

description The error description. string (300)

errors The array of errors captured in a certain scenario. array of Error

The next section outlines all possible values returned for the error related fields mentioned in the
table above.

4.2.4 Errors
HTTP Error Key Reason Error Description
Status Code (JSON Message)

401 unauthorized The access token is {

either missing or "errors": [
invalid. {
"message": "unauthorized",
"description": "The access token is either
missing or invalid."
}
]
}

31
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

401 token_expired The provided {

access token has "errors": [
expired. {
"message": "token_expired",
"description": "The provided access token
has expired - please request a new one via POST
/oauth/token."
}
]
}

422 depart_at_ The depart_at {

missing parameter is "errors": [
missing. {
"message": "depart_at_missing",
"description": "The departure date is
missing."
}
]
}

422 depart_at_ The depart_at {

invalid parameter is not a "errors": [
valid ISO-8601 {
datetime. "message": "depart_at_invalid",
"description": "The depart_at parameter
should be a valid ISO-8601 datetime object."
}
]
}

422 depart_at_in The depart_at {

_the_past parameter should "errors": [
be a date in the {
future. "message": "depart_at_in_the_past",
"description": "The departure date can not
be in the past."
}
]
}

422 depart_at_too The depart_at {

_early parameter should "errors": [
be a date at least {
60 minutes in the "message": "depart_at_too_early",
future. "description": "You may only book at least
60 minutes prior to your departure."
}
]
}

32
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 depart_at_no No prices could be {

_prices_found found for the "errors": [
provided depart_at {
parameter. "message": "depart_at_no_prices_found",
"description": "We could not calculate any
prices for your requested date.“
}
]
}

422 service_type The service_type {

_missing parameter is "errors": [
missing. {
"message": "service_type_missing",
"description": "The service_type parameter
is missing."
}
]
}

422 service_type_ The service_type {

invalid parameter is "errors": [
invalid. {
"message": "service_type_invalid",
"description": "The service_type parameter
should be one of: transfer, hourly."
}
]
}

422 pickup_ One or more {

missing pickup_* "errors": [
parameters are {
missing. "message": "pickup_missing",
"description": "Either pickup_airport_iata, or
all of the pickup_address, pickup_latitude,
pickup_longitude parameters have to be
provided."
}
]
}

422 pickup_invalid One or more of the {

provided pickup_* "errors": [
parameters are {
invalid. "message": "pickup_invalid",
"description": "One or more of the provided
pickup_* parameters are invalid."
}
]
}

33
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 dropoff_ One or more {

missing dropoff_* "errors": [
parameters are {
missing. "message": "dropoff_missing",
"description": "Either dropoff_airport_iata,
or all of the dropoff_address, dropoff_latitude,
dropoff_longitude parameters have to be
provided."
}
]
}

422 dropoff_ One or more of the {

invalid provided dropoff_* "errors": [
parameters are {
invalid. "message": "dropoff_invalid",
"description": "One or more of the provided
dropoff_* parameters are invalid."
}
]
}

422 pickup_conflict Conflicting pickup {

parameters. "errors": [
{
"message": "pickup_conflict",
"description": "The provided pickup_*
parameters are mutually exclusive."
}
]
}

422 dropoff_conflict Conflicting drop-off {

parameters. "errors": [
{
"message": "dropoff_conflict",
"description": "The provided dropoff_*
parameters are mutually exclusive."
}
]
}

422 pickup_and_ Conflicting pickup {

dropoff_conflict and dropoff "errors": [
parameters. {
"message": "pickup_and_dropoff_conflict“,
"description": "The provided pickup_* and
dropoff_* parameters are mutually exclusive."
}
]
}

34
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 area_not_ The provided {

covered pickup and dropoff "errors": [
locations are not {
covered by "message": "area_not_covered",
Blacklane. "description": "The provided pickup and
dropoff locations are not covered by Blacklane."
}
]
}

422 duration_ The duration {

missing parameter is "errors": [
missing. {
"message": "duration_missing",
"description": "The duration is missing."
}
]
}

422 duration_ The duration {

invalid parameter should "errors": [
be a multiple of {
3600, equal or "message": "duration_invalid",
greater than 7200 "description": "The duration parameter
(2 hours). should be a multiple of 3600, equal or greater
than 7200 (2 hours)."
}
]
}

422 vehicle_type The vehicle_type {

_missing parameter is "errors": [
missing. {
"message": "vehicle_type_missing",
"description": "The vehicle_type parameter
is missing."
}
]
}

422 vehicle_type The vehicle_type {

_invalid parameter is "errors": [
invalid. {
"message": "vehicle_type_invalid",
"description": "The provided vehicle_type is
invalid or is not available in the selected area."
}
]
}

35
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 payment_ A payment method {

method_ set of parameters "errors": [
missing must be specified: {
credit_card_*, "message": "payment_method_missing",
payment_method_ "description": "One or more of the
uuid or credit_card
corporation_uuid. _holder, credit_card
_number, credit_card
_expiry_month and credit_card
_expiry_year parameters are missing."
}
]
}

422 payment The provided {

_method payment method is "errors": [
_not not supported. {
_supported "message":
"payment_method_not_supported",
"description": "The provided payment
method is not supported."
}
]
}

422 insufficient The provided {

_funds payment method "errors": [
does not have the {
sufficient funds to "message": "insufficient_funds",
cover the "description": "The provided payment
transaction amount. method does not have the sufficient funds to
cover the transaction amount."
}
]
}

422 payment The payment {

_method method's limit has "errors": [
_limit been reached. {
_exceeded "message":
"payment_method_limit_exceeded",
"description": "Your payment method's limit
has been reached - please contact your payment
provider for further details."
}
]
}

422 transaction The transaction was {

_declined declined by the "errors": [
payment provider. {
"message": "transaction_declined",
"description": "The transaction was declined
by your payment provider - please contact your
payment provider for further details."
}

36
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

]
}

422 credit_card The credit_card {

_number _number parameter "errors": [
_missing is missing. {
"message": "credit_card_number_missing",
"description": "The credit_card_number
parameter is mandatory."
}
]
}

422 credit_card The provided {

_number credit_card_number "errors": [
_invalid parameter is {
invalid. "message": "credit_card_number_invalid",
"description": "The provided
credit_card_number parameter is invalid."
}
]
}

422 credit_card The credit_card {

_holder _holder parameter "errors": [
_missing is missing. {
"message": "credit_card_holder_missing",
"description": "The credit_card_holder
parameter is mandatory."
}
]
}

422 credit_card The provided {

_holder credit_card "errors": [
_invalid _holder parameter {
is invalid. "message": "credit_card_holder_invalid",
"description": "The provided
credit_card_holder parameter is invalid."
}
]
}

422 credit_card The {

_expiry credit_card_expiry_ "errors": [
_month month parameter is {
_missing missing. "message":
"credit_card_expiry_month_missing",
"description": "The
credit_card_expiry_month parameter is
mandatory."
}
]
}

37
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 credit_card The provided {

_expiry credit_card_expiry_ "errors": [
_month month parameter is {
_invalid invalid. "message":
"credit_card_expiry_month_invalid",
"description": "The provided
credit_card_expiry_month parameter is invalid."
}
]
}

422 credit_card The {

_expiry_year credit_card_expiry_ "errors": [
_missing year parameter is {
missing. "message":
"credit_card_expiry_year_missing",
"description": "The credit_card_expiry_year
parameter is mandatory."
}
]
}

422 credit_card The provided {

_expiry_year credit_card_expiry_ "errors": [
_invalid year parameter is {
invalid. "message":
"credit_card_expiry_year_invalid",
"description": "The provided
credit_card_expiry_year parameter is invalid."
}
]
}

422 credit_card The provided credit {

_expired card is expired or "errors": [
about to expire. {
"message": "credit_card_expired",
"description": "The provided credit card is
expired or about to expire."
}
]
}

422 corporation_uuid The {

_invalid corporation_uuid "errors": [
could not be {
resolved to an "message": "discount_id_invalid",
existing "description": "The provided
corporation. corporation_uuid parameter is either invalid or
the corporation is not accessible by this client."
}
]
}

38
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 payment_method_c Conflicting {

onflict payment methods "errors": [
parameters. {
"message": "payment_method_conflict",
"description": "The provided credit_card_*
and corporation_uuid parameters are mutually
exclusive."
}
]
}

422 voucher_code The voucher_code {

_invalid was invalid. "errors": [
{
"message": "voucher_code_invalid",
"description": "The voucher code you
provided is invalid."
}
]
}

422 passenger The passenger_title {

_title_missing is missing. "errors": [
{
"message": "passenger_title_missing",
"description": "The passenger_title
parameter is mandatory if other passenger_*
fields have been provided."
}
]
}

422 passenger The passenger_title {

_title_invalid is invalid. "errors": [
{
"message": "passenger_title_invalid",
"description": "The provided passenger_title
parameter is invalid."
}
]
}

422 passenger The passenger_first {

_first_name _name is missing. "errors": [
_missing {
"message":
"passenger_first_name_missing",
"description": "The passenger_first_name
parameter is mandatory if other passenger_*
fields have been provided."
}
]
}

39
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 passenger The {

_first_name passenger_first_na "errors": [
_invalid me is invalid. {
"message": "passenger_first_name_invalid",
"description": "The provided
passenger_first_name parameter is invalid."
}
]
}

422 passenger The {

_last_name passenger_last_na "errors": [
_missing me is missing. {
"message":
"passenger_last_name_missing",
"description": "The passenger_last_name
parameter is mandatory if other passenger_*
fields have been provided."
}
]
}

422 passenger The passenger_last {

_last_name _name is invalid. "errors": [
_invalid {
"message": "passenger_last_name_invalid",
"description": "The provided
passenger_last_name parameter is invalid."
}
]
}

422 passenger_email_m The {

issing passenger_email is "errors": [
missing. {
"message": "passenger_email_missing",
"description": "The passenger_email
parameter is mandatory if other passenger_*
fields have been provided."
}
]
}

422 passenger_ The {

email_invalid passenger_email is "errors": [
invalid. {
"message": "passenger_email_invalid",
"description": "The provided
passenger_email parameter is invalid."
}
]
}

40
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 passenger The {

_mobile passenger_mobile "errors": [
_missing is missing. {
"message": "passenger_mobile_missing",
"description": "The passenger_mobile
parameter is mandatory if other passenger_*
fields have been provided."
}
]
}

422 passenger The {

_mobile passenger_mobile "errors": [
_invalid is invalid. {
"message": "passenger_mobile_invalid",
"description": "The provided
passenger_mobile parameter is invalid."
}
]
}

422 airline_code The airline_code is {

_missing missing. "errors": [
{
"message": "airline_code_missing",
"description": "The airline_code parameter
is mandatory if the flight_number parameter has
been provided."
}
]
}

422 airline_code_ The airline_code is {

invalid invalid. "errors": [
{
"message": "airline_code_invalid",
"description": "The provided airline_code
parameter is invalid."
}
]
}

422 flight_number The flight_number {

_missing is missing. "errors": [
{
"message": "flight_number_missing",
"description": "The flight_number
parameter is mandatory if the airline_code
parameter has been provided."
}
]
}

41
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 flight_number The flight_number {

_invalid is invalid. "errors": [
{
"message": "flight_number_invalid",
"description": "The provided flight_number
parameter is invalid."
}
]
}

422 pickup_sign The pickup_sign is {

_invalid invalid. "errors": [
{
"message": "pickup_sign_invalid",
"description": "The provided pickup_sign
parameter is invalid."
}
]
}

422 special The {

_requests special_requests is "errors": [
_invalid invalid. {
"message": "special_requests_invalid",
"description": "The provided
special_requests parameter is invalid."
}
]
}

422 reference The reference is {

_invalid invalid. "errors": [
{
"message": "reference_invalid",
"description": "The provided reference
parameter is invalid."
}
]
}

422 external The external_id {

_id_invalid provided is invalid. "errors": [
{
"message": "external_id_invalid",
"description": "The provided external_id
parameter is invalid."
}
]
}

422 external_user_id The {

_invalid external_user_id "errors": [
provided is invalid. {
"message": „external_user_id_invalid“,
"description": "The provided
external_user_id parameter is invalid."

42
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

}
]
}

422 billing_company The {

_name_invalid billing_company_na "errors": [
me is invalid. {
"message":
"billing_company_name_invalid",
"description": "The provided
billing_company_name parameter is invalid."
}
]
}

422 billing_title_invalid The billing_title is {

invalid. "errors": [
{
"message": "billing_title_invalid",
"description": "The provided billing_title
parameter is invalid."
}
]
}

422 billing_first_name_i The {

nvalid billing_first_name is "errors": [
invalid. {
"message": "billing_first_name_invalid",
"description": "The provided
billing_first_name parameter is invalid."
}
]
}

422 billing_last_name_i The {

nvalid billing_last_name is "errors": [
invalid. {
"message": "billing_last_name_invalid",
"description": "The provided
billing_last_name parameter is invalid."
}
]
}

422 billing_street_ The {

address_invalid billing_street_addre "errors": [
ss is invalid. {
"message": "billing_street_address_invalid",
"description": "The provided
billing_street_address parameter is invalid."
}
]
}

43
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 billing_city_invalid The billing_city is {

invalid. "errors": [
{
"message": "billing_city_invalid",
"description": "The provided billing_city
parameter is invalid."
}
]
}

422 billing_postal_ The {

code_invalid billing_postal_code "errors": [
is invalid. {
"message": "billing_postal_code_invalid",
"description": "The provided
billing_postal_code parameter is invalid."
}
]
}

422 billing_country_ The {

code_invalid billing_country_cod "errors": [
e is invalid. {
"message": "billing_country_code_invalid",
"description": "The provided
billing_country_code parameter is invalid."
}
]
}

422 nonce_invalid The nonce is {

invalid. "errors": [
{
"message": "nonce_invalid",
"description": "The nonce you provided had
already been used by our api client."
}
]
}

422 passenger_count_ Passenger count is {

invalid not positive or "errors": [
exceeds vehicle {
capacity. "message": "passenger_count_invalid",
"description": "The number of passengers
should be an integer greater than 0 and it
should not exceed the passenger capacity of the
vehicle."
}
]
}

422 luggage_count_ Luggage count is {

invalid negative or "errors": [
exceeds vehicle {
capacity. "message": "luggage_count_invalid",

44
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

"description": "The number of check-in

luggage should be an integer greater than or
equal to 0 and it should not exceed the luggage
capacity of the vehicle."
}
]
}

45
Blacklane Connector Core Specification

5 Update
This section describes the endpoint to be used in order to update a booking for a ride with
Blacklane.

Endpoint Call /bookings

Description Updates a booking request.

HTTP Method PUT

5.1 Update Request

5.1.1 HTTP Headers

Name Description Required? Data Type

Authorization The user access token of "bearer" type that has been yes string
obtained previously as a successful response after
invoking the authorization endpoint.
Value: Bearer [user_access_token].

5.1.2 Request Parameters

Name Description Required? Data Type

identifier A path parameter which is passed in the request: yes string (255)
URL/bookings/{​identifier}
Valid values to pass as the identifier are the "uuid",
"booking_number" or "external_id" of the original
booking.

depart_at The departure date-time expressed in ISO-8601 yes date-time

datetime format - e.g. "2015-11-21T14:00:00".

service_type The service type. yes string (20)

Valid values are "transfer" and "hourly".

vehicle_type Vehicle type, e.g. "business_class". yes string (30)

Valid values are "business_class", "business_van" and
"first_class", "electric_class", "sprinter_class".

pickup_address Pickup address - e.g. "Oranienstraße 199, 10999, *see string (255)
Berlin". „Address
Resolution”
section

pickup_latitude Pickup point latitude - e.g. "52.500023". *see double

It is stored as decimal (9, 6). „Address
Resolution”
section

pickup_longitude Pickup point longitude - e.g. "13.424148". *see double

It is stored as decimal (9, 6). „Address

46
Blacklane Connector Core Specification

Name Description Required? Data Type

Resolution”
section

pickup_airport_iata An airport IATA code replacing the pickup address - *see string (4)
e.g. "BER" for Berlin Brandenburg Airport. „Address
Resolution”
section

pickup_place_id The Google Place ID identifying the pickup location. no string (255)

dropoff_address Dropoff address - e.g. "Feurigstraße 59, 10827 *see string (255)
Berlin". „Address
Resolution”
section

dropoff_latitude Dropoff point latitude - e.g. "52.485313". *see double

It is stored as decimal (9, 6). „Address
Resolution”
section

dropoff_longitude Dropoff point longitude - e.g. " 13.357660". *see double

It is stored as decimal (9, 6). „Address
Resolution”
section

dropoff_airport_iata An airport IATA code replacing the dropoff address - *see string (4)
e.g. "BER" for Berlin Brandenburg Airport. „Address
Resolution”
section

dropoff_place_id The Google Place ID identifying the dropoff location. no string (255)

duration Ride duration in seconds - e.g. "7200" for a 2-hour yes, if integer
ride. Please note that this is stored as unsigned "service_typ
integer. e" is
"hourly"

credit_card_holder Credit Card holder name. no string (255)

credit_card_number Credit Card number. no string (255)

credit_card_expiry_ Credit Card expiry month - e.g. "09" for the month of no string (255)
month September.

credit_card_expiry_y Credit Card expiry year - e.g. "2018". no string (255)

ear

credit_card_cvv Credit card CVV - e.g. "123". no string (3)

corporation_uuid The corporation UUID to handle payment no string (255)

(alternative to credit card related fields).

voucher_code Voucher code - e.g. "BNG5SK8F". no string (255)

passenger_count Number of passengers expected for the ride - e.g. no integer

"2".

luggage_count Number of check-in luggage expected for the ride, no integer

e.g. "1".

passenger_title Passenger's title "mr", "ms" or "unknown". no string (3)

47
Blacklane Connector Core Specification

Name Description Required? Data Type

passenger_first_nam Passenger's first name. yes string (255)

e

passenger_last_nam Passenger's last name. yes string (255)

e

passenger_email Passenger's email. yes string (255)

passenger_mobile Passenger's mobile phone number. yes string (255)

airline_code Airline code for the flight, e.g. "AB" for Air Berlin. no string (2)
Discarded unless you provide the "flight_number".

flight_number Flight number without the airline code - e.g. "6446". no string (25)
Discarded unless you provide the "airline_code".

pickup_sign Text to be written on the pick up sign, usually the no string (255)
name of a person or company - e.g. "John Doe".

special_requests Additional requirements by the passenger. no string (stored

as text, 64
KB
maximum)

send_sms Whether to send SMS notifications when the chauffeur no boolean

is on his way or has reached the pick-up location.

reference A reference number to include in the invoice. no string (255)

billing_company_na Billing payer’s name. no string (255)

me

billing_title Billing details - payer’s title. no string (255)

billing_first_name Billing details - payer’s first name. no string (255)

billing_last_name Billing details - payer’s last name. no string (255)

billing_street_addre Billing details - street address. no string (255)

ss

billing_city Billing details - city. no string (255)

billing_postal_code Billing details - postal code. no string (255)

billing_country_cod Billing details - country code. no string (255)

e

passenger_locale Represents the locale of the passenger and indicates no, string (2)
the language in which language dependent assets default is
such as meeting instructions should be delivered. "en"
Currently the following languages are supported:
"en", "de" and "fr".

48
Blacklane Connector Core Specification

5.2 Booking Update Response

5.2.1 HTTP Headers

Name Value

Content-Type application/json

5.2.2 Response Body (Success)

HTTP Status Code 200

Description Booking update request has been processed

successfully.

Name Description Required? Data Type

uuid The UUID of the booking - e.g. yes string (36)

"19419389-c73c-4a0c-b7bb-38cdb9788c24".

booking_number The number associated with the updated booking - yes string (255)
e.g. "20150520-2945138".

old_booking_numb The number associated with the original booking - no string (255)
er e.g. "20150520-2945139"

external_id The external ID provided from the API client used as a no string (36)
means to uniquely identify the booking. This value
stays unchanged from the original booking.

external_user_id An optional identifier for the user provided by the API no string (255)
client. This value stays unchanged from the original
booking.

booking_status The status of the booking. yes string (30)

For an explanation of relevant API statuses, please
see section 1.13 at the start of the document.

pickup_sign The text for the pickup sign. no string (255)

airline_code The airline code e.g. - "AB" for Air Berlin. no string (2)

flight_number The flight number e.g. "6446". no string (16)

reference A reference for the customer invoice e.g. - no string (255)

"INV-2431".

send_sms A flag indicating if an SMS should be sent or not. no boolean

depart_at The date and time of the departure ISO-8601 yes string
datetime format e.g. - "2015-11-21T14:00:00".

service_type The service type. yes string (20)

Valid values are "transfer" and "hourly".

estimated_confirmat The estimated date time for the confirmation, in ISO no string
ion_at format e.g. - "2015-05-20T16:21:38".

49
Blacklane Connector Core Specification

Name Description Required? Data Type

passenger_count Number of passengers expected for the ride - e. g. no integer

"2".

luggage_count Number of check-in luggage expected for the ride, e. no integer

g. "1".

vehicle_type Vehicle type, e.g. "business_class". yes string (30)

Valid values are "business_class", "business_van",
"first_class", "electric_class", "sprinter_class".

vehicle_max_luggag The maximum luggage allowed for a certain vehicle yes integer
e type e.g. - "2".

vehicle_max_passen The maximum number of passengers allowed for a yes integer

gers certain vehicle type e.g. - "3".

confirmation_status The confirmation status of the booking e.g. - "open". yes string (30)
Possible values are: "open", "accepted" and
"rejected".

price Contains tour price information with details as yes Price

conveyed by the following composite type: composite
type
"price": { containing
"currency": "EUR“, following
"total_amount“: 4217, fields:
"net_amount": 3543,
"vat_amount": 674, - currency:
"vat_rate": 0.19 string (3)
} (required)
-
All double amount values are stored as decimal (11, net_amount:
4). double -
(required)
-
total_amount
: double
(required)
-
vat_amount:
double
(required)
- vat_rate:
double
(required)

estimated_duration The estimated duration of a transfer ride. yes, if integer

"service_typ
e" is
"transfer"

included_distance The included distance for an hourly ride. yes, if integer

"service_typ
e" is
"hourly"

duration The duration in seconds. It will be returned under the yes, if integer
"common" composite type. "service_typ

50
Blacklane Connector Core Specification

Name Description Required? Data Type

Considered as decimal (11, 4). e" is

"hourly"

pickup_address Pickup address - e.g. "Oranienstraße 199, 10999, yes string (255)
Berlin".

pickup_latitude Pickup point latitude - e.g. "52.500023". yes double

pickup_longitude Pickup point longitude - e.g. "13.424148". yes double

pickup_airport_iata An airport IATA code - e.g. "BER" for Berlin no string (4)
Brandenburg Airport.

pickup_place_id The Google Place ID identifying the pickup location. no string (255)

dropoff_address Dropoff address - e.g. "Feurigstraße 59, 10827 yes, if string (255)
Berlin". "service_typ
e" is
"transfer"

dropoff_latitude Dropoff point latitude - e.g. "52.485313". yes, if double

"service_typ
e" is
"transfer"

dropoff_longitude Dropoff point longitude - e.g. "13.357660". yes, if double

"service_typ
e" is
"transfer"

dropoff_airport_iata An airport IATA code - e.g. "BER" for Berlin no string (4)
Brandenburg Airport.

dropoff_place_id The Google Place ID identifying the dropoff location. no string (255)

passenger_title The passenger’s title e.g. "Mr", "Ms" or "unknown" yes string (255)

passenger_first_nam The passenger's first name e.g. "Michael". yes string (255)
e

passenger_last_nam The passenger's last name e.g. "Mueller". yes string (255)
e

passenger_email The passenger’ s email e.g. yes string (255)

"[email protected]".

passenger_mobile The passenger’s mobile phone number e.g. yes string (255)
"+4900000000000".

passenger_locale The selected locale for the booking communication. yes string (2)

special_requests Additional requirements by the passenger. no string (stored

as text, 64
KB
maximum)

billing_company_na Billing payer’s name. no string (255)

me

billing_title Billing details - payer’s title. no string (255)

51
Blacklane Connector Core Specification

Name Description Required? Data Type

billing_first_name Billing details - payer’s first name. no string (255)

billing_last_name Billing details - payer’s last name. no string (255)

billing_street_addre Billing details - street address. no string (255)

ss

billing_city Billing details - city. no string (255)

billing_postal_code Billing details - postal code. no string (255)

billing_country_cod Billing details - country code. no string (255)

e

corporation_uuid The corporation UUID provided with the booking no string (255)
update request.

invoiced Flag indicating if the invoice corresponding to the yes boolean

booking has been created.

payment_method_t The type of payment method used for the booking. yes string (255)
ype Valid values are "collective_invoice", "credit_card".

payment_method_l The label for the payment method used on Blacklane yes string (255)
abel side, e.g. the corporation name.

meeting_instruction Field indicating general meeting instructions for the yes string (255)
s chauffeur and passenger at various address types.

5.2.3 Response Body (Failure)

Name Description Data Type

message Unique key identifying the error. string (128)

description The error description. string (300)

errors The array of errors captured in a certain scenario. array of Error

Please refer to section 4.2.4 for all possible values returned for the error related fields mentioned
in the table above.

52
Blacklane Connector Core Specification

6 Cancellation
This section describes the endpoint which is to be used by an API client in order to cancel a
previously successful booking with Blacklane.

A booking can be cancelled by providing any of the following fields (mutually exclusive):

1. the UUID of the booking;

2. the booking number which confirmed the successful booking; or

3. the external ID used to identify the booking (this is the external identifier used by the API
client in order to uniquely distinguish bookings and is usually received in cases when the
uuid or booking number is not received, regardless of reason).

Endpoint Call /bookings

Description Cancels a tour booking.

HTTP Method DELETE

6.1 Cancellation Request

6.1.1 HTTP Headers

Name Description Required? Data Type

Authorization The user access token of "bearer" type that has been yes string
obtained previously as a successful response after
invoking the authorization endpoint.
Value: Bearer [user_access_token].

6.1.2 Request Parameters

Name Description Required? Data Type

uuid Tour identifier as returned by the POST /bookings no string (36)

request, e.g.
"8e7dfc7b-ea5f-492c-b741-b143d0fc9ead".

booking_number Tour booking number as returned by the POST no string (255)

/bookings request, e.g. "20150520-2945138".

external_id An optional identifier for the ride provided by the API no string (30)
client.

53
Blacklane Connector Core Specification

6.2 Cancellation Response

6.2.1 HTTP Headers

Name Value

Content-type application/json

6.2.2 Response Body (Success)

HTTP Status Code 200 OK

Description In case the cancellation has been successfully

performed.

Name Description Required? Data Type

uuid The UUID of the booking that has been successfully yes string (36)
cancelled.

booking_number Tour booking number as returned by the POST or PUT yes string (255)
/bookings request, e.g. "20150520-2945138".

external_id The external ID that has been supplied as part of the no string (30)
request.

type The cancellation type, with the following values: yes string (20)
"free" or "full".

price The chargeable price for the booking after yes string
cancellation.

6.2.3 Response Body (Failure)

Name Description Data Type

message Unique key identifying the error. string (128)

description The error description. string (300)

errors The array of errors captured in a certain scenario. array of Error

The next section outlines all possible values returned for the error related fields mentioned in the
table above.

54
Blacklane Connector Core Specification

6.2.4 Errors
HTTP Error Key Reason Error Description
Status Code (JSON Message)

401 unauthorized The access token is {

either missing or "errors": [
invalid. {
"message": "unauthorized",
"description": "The access token is either
missing or invalid."
}
]
}

401 token_expired The provided {

access token has "errors": [
expired. {
"message": "token_expired",
"description": "The provided access token
has expired - please request a new one via POST
/oauth/token."
}
]
}

422 booking_identifier_ No booking {

missing identifier was "errors": [
provided. {
"message": "booking_identifier_missing",
"description": "You can use any of the
following parameters to specify the booking:
uuid, external_id, booking_number."
}
]
}

422 cancellation_not_all Either the booking {

owed was already "errors": [
cancelled or cannot {
be cancelled any "message": "cancellation_not_allowed",
more because the "description": "Either the booking was
ride is on-going or already cancelled or cannot be cancelled any
finished. more because the ride is on-going or finished."
}
]
}

422 booking_not_found The booking {

identified by either "errors": [
UUID external_id or {
booking_ "message": "booking_not_found",
number could not "description": "The booking identified by
be found. the given UUID, external_id or booking_number
could not be found."
}
]
}

55
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

422 booking_identifier_ The provided {

conflict booking identifiers "errors": [
are mutually {
exclusive. "message": "booking_identifier_conflict",
"description": "The provided booking
identifiers are mutually exclusive."
}
]
}

56
Blacklane Connector Core Specification

7 Get Booking Details

This section describes the endpoint to be used in order to obtain the details of previously
performed booking with Blacklane.

A booking can be located via any of the following fields (mutually exclusive):

1. the UUID of the booking;

2. the booking number which confirmed the successful booking; or

3. the external ID used to identify the booking (this is the external identifier used by the API
client in order to uniquely distinguish bookings and is usually received in cases when the
uuid or booking number is not received, regardless of reason).

Endpoint Call /bookings

Description Provides details of a previously made booking.

HTTP Method GET

7.1 Get Booking Details Request

7.1.1 HTTP Headers

Name Description Required? Data Type

Authorization The user access token of "bearer" type that has been yes string
obtained previously as a successful response after
invoking the authorization endpoint.
Value: Bearer [user_access_token].

7.1.2 Request Parameters

Name Description Required? Data Type

uuid Tour identifier as returned by the POST /bookings no string (36)

request, e.g.
"8e7dfc7b-ea5f-492c-b741-b143d0fc9ead".

booking_number Tour booking number as returned by the POST no string (255)

/bookings request, e.g. "20150520-2945138".

external_id An optional identifier for the ride provided by the API no string (30)
client.

57
Blacklane Connector Core Specification

7.2 Get Booking Details Response

7.2.1 HTTP Headers

Name Value

Content-type application/json

7.2.2 Response Body (Success)

The table below lists the fields inside the response of the Get Details endpoint, specifying their
significance and data types.

Name Description Required? Data Type

uuid The UUID of the booking - e.g. yes string (36)

"19419389-c73c-4a0c-b7bb-38cdb9788c24".

booking_number The number associated with this booking - e.g. yes string (255)
"20150520-2945138".

old_booking_numb The number associated with the original booking - no string (255)
er e.g. "20150520-2945139"

external_id The external ID provided from the API client used as a no string (36)
means to uniquely identify the booking.

external_user_id An optional identifier for the user provided by the API no string (255)
client.

booking_status The status of the booking. yes string (30)

For an explanation of relevant API statuses, please
see section 1.13 at the start of the document.

pickup_sign The text for the pickup sign. no string (255)

airline_code The airline code e.g. - "AB" for Air Berlin. no string (2)

flight_number The flight number e.g. "6446". no string (16)

reference A reference for the customer invoice e.g. - no string (255)

"INV-2431".

send_sms A flag indicating if an SMS should be sent or not. no boolean

depart_at The date and time of the departure ISO-8601 yes string
datetime format e.g. - "2015-11-21T14:00:00".

service_type The service type. yes string (20)

Valid values are "transfer" and "hourly".

estimated_confirmat The estimated date time for the confirmation, in ISO no string
ion_at format e.g. - "2015-05-20T16:21:38".

passenger_count Number of passengers expected for the ride - e. g. no integer

"2".

luggage_count Number of check-in luggage expected for the ride, e. no integer

g. "1".

58
Blacklane Connector Core Specification

Name Description Required? Data Type

vehicle_type Vehicle type, e.g. "business_class". yes string (30)

Valid values are "business_class", "business_van",
"first_class", "electric_class", "sprinter_class".

vehicle_max_luggag The maximum luggage allowed for a certain vehicle yes integer
e type e.g. - "2".

vehicle_max_passen The maximum number of passengers allowed for a yes integer

gers certain vehicle type e.g. - "3".

confirmation_status The confirmation status of the booking e.g. - "open". yes string (30)
Possible values are: "open", "accepted" and
„rejected".

price Contains tour price information with details as yes Price

conveyed by the following composite type: composite
type
"price": { containing
"currency": "EUR“, following
"total_amount“: 4217, fields:
"net_amount": 3543,
"vat_amount": 674, - currency:
"vat_rate": 0.19 string (3)
} (required)
-
All double amount values are stored as decimal (11, net_amount:
4). double -
(required)
-
total_amount
: double
(required)
-
vat_amount:
double
(required)
- vat_rate:
double
(required)

estimated_duration The estimated duration of a transfer ride. yes, if integer

"service_typ
e" is
"transfer"

included_distance The included distance for an hourly ride. yes, if integer

"service_typ
e" is
"hourly"

duration The duration in seconds. It will be returned under the yes, if integer
"common" composite type. "service_typ
Considered as decimal (11, 4). e" is
"hourly"

pickup_address Pickup address - e.g. "Oranienstraße 199, 10999, yes string (255)
Berlin".

59
Blacklane Connector Core Specification

Name Description Required? Data Type

pickup_latitude Pickup point latitude - e.g. "52.500023". yes double

pickup_longitude Pickup point longitude - e.g. "13.424148". yes double

pickup_airport_iata An airport IATA code - e.g. "BER" for Berlin no string (4)
Brandenburg Airport.

pickup_place_id The Google Place ID identifying the pickup location. no string (255)

dropoff_address Dropoff address - e.g. "Feurigstraße 59, 10827 yes, if string (255)
Berlin". "service_typ
e" is
"transfer"

dropoff_latitude Dropoff point latitude - e.g. "52.485313". yes, if double

"service_typ
e" is
"transfer"

dropoff_longitude Dropoff point longitude - e.g. "13.357660". yes, if double

"service_typ
e" is
"transfer"

dropoff_airport_iata An airport IATA code - e.g. "BER" for Berlin no string (4)
Brandenburg Airport.

dropoff_place_id The Google Place ID identifying the dropoff location. no string (255)

passenger_title The passenger’s title e.g. "Mr", "Ms" or "unknown" yes string (255)

passenger_first_nam The passenger's first name e.g. "Michael". yes string (255)
e

passenger_last_nam The passenger's last name e.g. "Mueller". yes string (255)
e

passenger_email The passenger’ s email e.g. yes string (255)

"[email protected]".

passenger_mobile The passenger’s mobile phone number e.g. yes string (255)
"+4900000000000".

passenger_locale The selected locale for the booking communication. yes string (2)

special_requests Additional requirements by the passenger. no string (stored

as text, 64
KB
maximum)

billing_company_na Billing payer’s name. no string (255)

me

billing_title Billing details - payer’s title. no string (255)

billing_first_name Billing details - payer’s first name. no string (255)

billing_last_name Billing details - payer’s last name. no string (255)

billing_street_addre Billing details - street address. no string (255)

ss

60
Blacklane Connector Core Specification

Name Description Required? Data Type

billing_city Billing details - city. no string (255)

billing_postal_code Billing details - postal code. no string (255)

billing_country_cod Billing details - country code. no string (255)

e

corporation_uuid The corporation UUID provided with the booking no string (255)
update request.

invoiced Flag indicating if the invoice corresponding to the yes boolean

booking has been created.

payment_method_t The type of payment method used for the booking. yes string (255)
ype Valid values are "collective_invoice", "credit_card".

payment_method_l The label for the payment method used on Blacklane yes string (255)
abel side, e.g. the corporation name.

meeting_instruction Field indicating general meeting instructions for the yes string (255)
s chauffeur and passenger at various address types.

7.2.3 Response Body (Failure)

Name Description Data Type

message Unique key identifying the error. string (128)

description The error description. string (300)

errors The array of errors captured in a certain scenario. array of Error

The next section outlines all possible values returned for the error related fields mentioned in the
table above.

7.2.4 Errors
HTTP Error Key Reason Error Description
Status Code (JSON Message)

401 unauthorized The access token is {

either missing or "errors": [
invalid. {
"message": "unauthorized",
"description": "The access token is either
missing or invalid."
}
]
}

61
Blacklane Connector Core Specification

HTTP Error Key Reason Error Description

Status Code (JSON Message)

401 token_expired The provided {

access token has "errors": [
expired. {
"message": "token_expired",
"description": "The provided access token
has expired - please request a new one via POST
/oauth/token."
}
]
}

422 booking_identifier_ No booking {

missing identifier was "errors": [
provided. {
"message": "booking_identifier_missing",
"description": "You can use any of the
following parameters to specify the booking:
uuid, external_id, booking_number."
}
]
}

422 booking_not_found The booking {

identified by either "errors": [
UUID, external_id {
or booking "message": "booking_not_found",
_number could not "description": "The booking identified by
be found. the given UUID, external_id or booking_number
could not be found."
}
]
}

422 booking_identifier_ The provided {

conflict booking identifiers "errors": [
are mutually {
exclusive. "message": "booking_identifier_conflict",
"description": "The provided booking
identifiers are mutually exclusive."
}
]
}

62
Blacklane Connector Core Specification

8 Assets API
The Assets API is offered in order to get access to Blacklane specific information meant for display
purposes in different languages, such as:

● Vehicle classes
● Vehicle models
● Service descriptions
● Maximum number of guests for a specific car class
● Maximum number of luggage for a specific car class
● Terms & Conditions URL
● Cancellation policy
● Meet & Greet text
● Vehicle image URL for a specific car class
● Blacklane logo URL

8.1 Assets Endpoint

In order to obtain Blacklane assets, the GET /assets endpoint needs to be used. It retrieves the
assets for the provided locale. You can get all assets, or request a particular asset information. For
example /assets/vehicle_types, or you can even use '.' to specify path more precisely
/assets/vehicle_types.business_class.

Tables below list the request and response structure, respectively.

8.2 Assets Request

8.2.1 HTTP Headers

Name Description Required? Data Type

Authorization The user access token of "bearer" type that has been yes string
obtained previously as a successful response after
invoking the authorization endpoint.
Value: Bearer [user_access_token].

Name Description Data Type

locale The parameter designating the locale. string (2)

Locales currently supported are "en", "de" and "fr".

8.3 Assets Response

8.3.1 HTTP Headers

Name Value

Content-type application/json

63
Blacklane Connector Core Specification

8.3.2 Response Body (Success)

HTTP Status Code 200 OK

Description In case the assets retrieval is successfully performed.

Name Description Data Type

vehicle_types A list of all vehicle types that are available within Blacklane. string

vehicle_class This is a collection of information for a specific vehicle class. collection of the
Inside this, the following information, listed below, will be fields as described
stored in the following fields: makes, description, passenger below
number, luggage number and the URL to the vehicle image
pertaining to the vehicle class.
Possible values are: "business_class", "business_van",
"first_class", "electric_class", "electric_sedan" and
"sprinter_class".

passenger_number The maximum number of passengers for a certain vehicle integer

class.

luggage_number The maximum number of luggage for a certain vehicle class. integer
Luggage that can be "check_in" is listed separately.

image_url The URL to the image pertaining to a certain vehicle class. string
Different sizes such as "medium", "small" will be listed as part
of this information.

makes The vehicle models corresponding to the specific vehicle class. string

description The service description offered with a certain vehicle class. string

logo_url The URL to the logo image containing separate links for string
different sizes "small" and "medium" as well as different
colors "black" and "white".

tos_url The Terms of Service URL. string

cancellation_policy The description of Blacklane’s cancellation policies for string

"transfer" and "hourly" services.

meet_and_greet Details of Blacklane’s meet & greet service described in string

"short" and "full" format.

8.3.4 Response Body (Failure)

This is the structure of the message in case an error is encountered:

Name Description Data Type

message Unique key identifying the error. string (128)

description The error description. string (300)

errors The array of errors captured in a certain scenario. array of Error

64
Blacklane Connector Core Specification

8.3.5 Errors
HTTP Status Error Key Reason Error Description
Code (JSON Message)

401 unauthorized The access token is {

either missing or "errors": [
invalid. {
"message": "unauthorized",
"description": "The access token is either
missing or invalid."
}
]
}

422 asset_path_invalid Asset can't be {

retrieved because "errors": [
of invalid request {
path. "message": "asset_path_invalid",
"description": "Provided asset path is
invalid."
}
]
}

429 too_many_requests The request has {

been throttled "errors": [
because it {
exceeded the limits "message": "too_many_requests",
for the client. "description": "You have exceeded the
number of requests allowed at this time. Please
try again later or contact Blacklane to raise your
request limit."
}
]
}

65
Blacklane Connector Core Specification

9 API Support Contact

In case of any questions regarding API usage, please send your inquiry to the following email
address: [email protected].

66
Blacklane Connector Core Specification

10 Appendix - API Examples

Blacklane will share a Postman collection with integration partners together with client specific
authentication credentials to access the sandbox environment upon request.

The Postman collection will include the following examples:

1. Authentication of API client

2. Prices request for a transfer booking
3. Prices request for an hourly booking
4. Booking creation for a transfer booking
5. Booking creation for an hourly booking
6. Booking update for a transfer booking
7. Booking update for an hourly booking
8. Booking cancelation
9. Booking retrieval
10. Assets retrieval
11. Assets retrieval by locale

67
Blacklane Connector Core Specification

11 Appendix - Certification Process

The process we use for certification of API integrations is less formal and it usually takes place
during a 1 hour call where we check your implementation in the Sandbox Environment.

The precondition for it is that the Pricing, Booking and Cancellation APIs are implemented and
work properly. Please check this before the meeting.

We will run through different scenarios involving performing bookings and then cancelling them.
Our main focus is to ensure that several important scenarios are covered, such as:

- Transfer from airport to street address

- Transfer from street address to airport
- Transfer from street address to street address
- Hourly booking from airport
- Hourly booking from street address

In case the pickup location is an airport, additional checks will be performed as follows:

- Check that an airport IATA is provided as a means to identify the pickup location
- Check the flight number that has been provided if the pickup is linked to a flight

For all bookings, we will verify that the pickup time is entered correctly. It should be the local
timezone of the pickup location and it means the exact moment in time when the guest expects
the chauffeur to pick him up at the pickup location provided.

Hourly bookings will be checked if they are established as being in the scope for implementation.

Additional checks can be performed around the Update API in order to check scenarios of editing
a previously placed booking. Scenarios covered are as follows:

- Edits with no changes to the price, e.g. email change or pickup sign change
- Edits with changes to the price, e.g change of pickup/dropoff location, pickup time or
vehicle class

Lastly, we would align on the production setup you would like to have, such as:
- Payment and billing options
- Notifications (emails and text messages)
- How are modifications to the booking addressed (define the operational procedure)

Our expectation would be that you present the integration by sharing screens with us during the
session so that we get an understanding of the whole look and feel and user experience in
general. Any other material sent in advance such as a presentation with the whole flow containing
relevant screenshots or giving access to the testing environment would be highly appreciated, but
not mandatory.

An important thing to check in the booking flow will be the displaying of the Blacklane Terms &
Conditions before the moment of booking.

If the certification was successful and no further adaptations are needed, you will receive the
necessary production credentials so that we can launch our integration LIVE.

68