Documentation Powered by ReDoc

Mobile API (1.0.0)

Download OpenAPI specification:Download

Bookings and Rides Team: it-bookings-rides@blacklane.com License: Blacklane - All Rights Reserved (2018-present) Terms of Service

Mobile API is a wrapper layer that serves as a mobile app gateway (or proxy) to Athena for some of the more complex requests. Authentication is done on Athena side, so endpoints usually require client_id, client_secret and Authorization headers to be specified. For more information about Atehna authentication, see Athena's API docs. For more information about this service, check out the project's GitHub page.

GitHub Project

Authentication

ClientID

A unique client ID that allows the caller to access this service. Comes from Athena.

Security Scheme Type API Key
Header parameter name: client_id

ClientSecret

A unique client secret that allows the caller to access secure parts of this service. One secret is tied to exactly one client.

Security Scheme Type API Key
Header parameter name: client_secret

BearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Health

Health and availability checks

Service availability check

If service is operational, this just responds with an HTTP OK.

Responses

Response samples

Content type
text/plain
OK

Users

Operations related to user's account data

Fetches current user's operational data

This endpoint takes the original set of user properties that Athena returns for user account data from /users/me, and adds corporate information from /corporations/me.

Authorizations:
ClientIDClientSecretBearerAuth
header Parameters
client_id
required
string
Example: maobkd9284tjh68eagfb4vv29enfs

Header token for a unique client ID (required in Athena)

client_secret
required
string
Example: qwertyuio34567896789

Header token that is uniquely paired with a client ID (required in Athena)

Authorization
required
string
Example: Bearer gadgoiaj3nm3b153goiudfsasdoiu

Header token used as Bearer authentication (required in Athena)

Responses

Response samples

Content type
application/json
{
  • "corporation_uuid": "afsuio-k1j3n5-iosjafoqmenthfgpjo-f2e9i0f0",
  • "corporation_name": "Zulu Corporation",
  • "rewards_numbers":
    [
    ],
  • "rewards_programs":
    [
    ]
}

Bookings

Data related to user's rides

Fetches stats and useful bookings overview data for the current user

Particularly useful for reporting, tracking and mobile app home screen, this endpoint will collect information from booking data sources about the past, current and upcoming rides for the current user.

Authorizations:
ClientIDClientSecretBearerAuth
header Parameters
client_id
required
string
Example: maobkd9284tjh68eagfb4vv29enfs

Header token for a unique client ID (required in Athena)

client_secret
required
string
Example: qwertyuio34567896789

Header token that is uniquely paired with a client ID (required in Athena)

Authorization
required
string
Example: Bearer gadgoiaj3nm3b153goiudfsasdoiu

Header token used as Bearer authentication (required in Athena)

Responses

Response samples

Content type
application/json
{
  • "numberOfFinishedRides": 12,
  • "numberOfTotalBookings": 301,
  • "earliestUnfinishedRide": "A 'booking' object from Athena"
}

Flights

Flight verification and flight data

Fetches detailed flight information from a 3rd-party source

Acts like a proxy for the request to Athena's /flights/lookup endpoint and responds with the same result. No extra properties are added, thus, for brevity and flexibility refer to Athena documentation to find more details.

Responses

Payments

Operations related to user's payment methods

Fetches all payment methods for the current user

Combines current user's private and corporate payment methods (if user belongs to a corporation). This endpoint also adds a synthetic Invoice payment method in case the user's corporation allows collective invoicing.

Authorizations:
ClientIDClientSecretBearerAuth
query Parameters
kinds
string
Example: kinds=credit_card,paypal_account

Query param, specifies kinds of payment methods to fetch (comma-separated). Currently supported are credit_card and paypal_account, but all available kinds can be fetched per-user from Athena's /payment_methods/setup endpoint. If not specified, defaults to credit_card

header Parameters
client_id
required
string
Example: maobkd9284tjh68eagfb4vv29enfs

Header token for a unique client ID (required in Athena)

client_secret
required
string
Example: qwertyuio34567896789

Header token that is uniquely paired with a client ID (required in Athena)

Authorization
required
string
Example: Bearer gadgoiaj3nm3b153goiudfsasdoiu

Header token used as Bearer authentication (required in Athena)

Responses

Response samples

Content type
application/json
{
  • "defaultUuid": "ofij1o-asoifjas-09f09as0f9a-490usf09-1mwerml",
  • "corporation":
    {
    },
  • "paymentMethods":
    [
    ]
}

Saves a payment method into the current user's payment methods

Payment methods are created using the payment processor's SDK (such as Braintree). After creating a payment method, payment processor should provide a unique nonce as a result of that operation - this nonce should be sent to this endpoint to be able to connect our systems with the provided payment data. No real card or account data is ever sent through this API, it just accepts nonces.

Authorizations:
ClientIDClientSecretBearerAuth
header Parameters
client_id
required
string
Example: maobkd9284tjh68eagfb4vv29enfs

Header token for a unique client ID (required in Athena)

client_secret
required
string
Example: qwertyuio34567896789

Header token that is uniquely paired with a client ID (required in Athena)

Authorization
required
string
Example: Bearer gadgoiaj3nm3b153goiudfsasdoiu

Header token used as Bearer authentication (required in Athena)

Request Body schema: application/json
is_business_card
boolean

Internal property, set it only if this card should be associated with the user's corporation. In case the user does not belong to a corporation, this flag is ignored

payment_method_nonce
string <nonce>

A unique nonce that comes from the payment processor (such as Braintree) after creating a payment method using their SDK

Responses

Request samples

Content type
application/json
{
  • "is_business_card": true,
  • "payment_method_nonce": "gsomfg2935i029efdokmsbfme"
}

Response samples

Content type
application/json
{
  • "uuid": "ofij1o-asoifjas-09f09as0f9a-490usf09-1mwerml",
  • "type": "string",
  • "ownership": "string",
  • "isDefault": true,
  • "creditCardIssuer": "MasterCard",
  • "lastDigits": "3012",
  • "creditCardExpiryMonth": "09",
  • "creditCardExpiryYear": "2043",
  • "creditCardHolder": "Max Mustermann",
  • "accountEmail": "john@blacklane.com",
  • "corporation":
    {
    }
}

Fetches detailed information about a specific payment method

Responds with more information about the given payment method, such as security verification config (i.e. 3DS token data)

Authorizations:
ClientIDClientSecretBearerAuth
path Parameters
uuid
required
string <uuid> (paymentMethodUuid)
Example: ofij1o-asoifjas-09f09as0f9a-490usf09-1mwerml

Path variable, uniquely identifies a payment method

query Parameters
currency
required
string
Example: currency=EUR

Query param, specifies the currency for which to fetch the security configuration. It should be in ISO 4217 format, a standardized 3-letter international abbreviation

header Parameters
client_id
required
string
Example: maobkd9284tjh68eagfb4vv29enfs

Header token for a unique client ID (required in Athena)

client_secret
required
string
Example: qwertyuio34567896789

Header token that is uniquely paired with a client ID (required in Athena)

Authorization
required
string
Example: Bearer gadgoiaj3nm3b153goiudfsasdoiu

Header token used as Bearer authentication (required in Athena)

Responses

Response samples

Content type
application/json
{
  • "paymentMethod":
    {
    },
  • "verification":
    {
    }
}