API Basics

All API services are based on the REST architectural style and they are all stateless. All calls to the APIs require a secure HTTPS connection. Supported security protocol is TLS 1.2.

Access and API permissions

Accessing the APIs require an active API connection on your Avinode (sandbox) account. API connections are currently created and maintained by Avinode support staff. Please contact your sales representative to get started on your project.

Permissions

Each API connection have a set of permissions that restricts which operations that can be called.

Company access

Each API connection is connected to one Avinode or SchedAero member’s company account. This is used to determine which company accounts’s data the API connection can access and potentially update. If the application needs to handle data for multiple companies, it needs to handle multiple API connections.

Application specific

If different kinds of applications are implemented, each application should be able to use separate API connections.

Automatic expiration

API connections that are not used for 60 days are automatically deactivated.

JSON input and output format

The API reference pages has information about the JSON format returned by all the available API operations and also the JSON format expected by any POST and PUT operation.
There is also a Swagger page available.

📘

API reference and Swagger access

Use your issued API token/authorization to try out the API at the API reference section, or at the Swagger page. Without credentials you can still browse what is available.

HTTP request headers

Several HTTP headers are required in every request to authenticate and provide other details about the call. Required headers are marked with a * below.

X-Avinode-Api Token *

This required header is a unique token identifying the calling application.
The value for the API token should not be editable by the users of the application. It is preferably hard coded into the application.

X-Avinode-ApiToken: 229B8C9E-B3F2-4FA6-8BAE-71DF00943C0E

🚧

IMPORTANT

The API token is used to identify the calling application. To prevent malicious callers from impersonating other software, the API token may not be shared with any external parties that is not directly involved in the project. Posting code examples, curl commands or similar to online forums or discussion groups where the API token is included is strictly forbidden.

Authorization *

The API uses Bearer Authentication. This requires the Authorization header to contain the unique authentication token that identifies the API connection used for this call. When sending this in the HTTP header the token must be prefixed by the word ‘Bearer’ in the style of OAUTH tokens.

Authorization: Bearer eyJraWQiOiIxNkVBQkQ5RS1BRjYyLTQ4NTEtODk5Qi1BM0...

Below is an example from Postman (software for sending REST API request calls) on how to configure the authorization.

19871987

🚧

IMPORTANT

Since the authorization token is used to identify and authorize the caller, it must be treated with the same care as any username and password. It may not be shared with any external parties that is not directly involved in the project. Posting code examples, curl commands, or similar to online forums or discussion groups where the authorization token is included is strictly forbidden.

Content-Type *

All request body data in any POST or PUT call should be sent in JSON format.

Content-Type: application/json

X-Avinode-SentTimestamp *

This required field must contain a timestamp formatted as per ISO-8601, and should be the current time in UTC. This is the time of creation for the message. The call will be rejected if this time is off by more than 5 minutes when the message is received. So it is important that the clock used by the application is up to date at all times.

X-Avinode-SentTimestamp: 2016-01-19T08:10:06.135Z

X-Avinode-ActAsAccount

Some API operations support sending a personal Avinode Marketplace account username. This means that this person will be registered as the user doing the action of the operation. For example when responding to an RFQ, the system will show the provided user (first name and last name) as the user responding to the quote. This will be visible to the broker in the Avinode request emails as well as in the Trips pages.

By not providing a user login or when providing a faulty or non-existing user login, the API will default to showing the company name instead anywhere this is applicable.

🚧

Required for specific API connections

The X-Avinode-ActAsAccount header will be required for some endpoints if the API connection is of the interactive type. Not providing the header will result in an HTTP 403 permission error.

X-Avinode-ActAsAccount: johnsmith64

X-Avinode-Product

This should always be populated with the name and version of the calling application.

X-Avinode-Product: Smart Flight Finder v2.3

Accept-Encoding

To optimize speed of your application or website, consider using GZIP compression. For example, when calling the aircraft search API and requesting a lot of additional data, using GZIP can significantly decrease response times.

Accept-Encoding: gzip

HTTP status codes

The APIs use conventional HTTP response codes to indicate success or failure of each API call. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, an authorization failed, etc.), and codes in the 5xx range indicate an API server error.

Code

Title

Description

200

OK

The request has succeeded.

201

Created

The request has been fulfilled and has resulted in one or more new resources being created.

400

Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax).

401

Unauthorized

The request has not been applied because it lacks valid authentication credentials for the target resource

403

Forbidden

The server understood the request but refuses to authorize it, e.g. no permissions, rate limit exceeded, etc.

404

Not found

The application requested a resource that does not exist

409

Simultaneous updates, operation aborted

Requests for the same object came in at the same time causing a conflict in the database

422

Unprocessable Entity

Validation failure, relationship failure, or state failure

429

Rate Limited

Your application is being rate limited due to high call volumes.

See "Service Rate Limits" below for more details

500

Internal Server Error

Internal failure

503

Service Unavailable

Service too busy

504

Gateway Timeout

Service temporary unavailable

HTTP response headers

Service Rate limits

The number of calls that one API connection can make to a given API endpoint may be limited to preserve overall system performance and stability.

After the number of calls has reached the rate limit, all calls to that endpoint will be denied with the HTTP 429 response code for a period of time. The following response headers will be returned on every rate limited call. In particular, note header "X-Rate-Limit-Reset" as it indicates a duration in seconds until your next API call could succeed.

The exact limits can vary per endpoint and we reserve the right to change them as needed to preserve system performance and stability. Generally speaking though our unit of time for call count windows is seconds. Our defaults for rate limiting look to accommodate a steady state of 1 call per second from a given client application to a given endpoint - with some fuzziness to allow for "bursting" of calls.

X-Rate-Limit-Limit  The rate limit for the endpoint that was invoked as the number of allowed calls.
X-Rate-Limit-Remaining  The remaining number of  calls allowed for the service.
X-Rate-Limit-Reset  The number of seconds until the call counter is reset.

Internationalization

Date and time

Dates and times are formatted according to ISO 8601.

Currency

Currency codes use the three letter code defined in ISO 4217. Price conversions are based on Forex data updated daily from Xignite.

Country codes

Country codes use the two letter code defined in ISO 3166-1 alpha-2.

Province codes

Province codes use the format defined in ISO 3166-2. Each code consists of two parts, separated by a hyphen. The first part is the two letter country code and the second part is a up to three letter code specifying the region in that country. For example “US-FL” for Florida.

Sparse fields

For some operations, there is information available that will only be included in the operation output if it is requested when making the API call. This extra information is requested by specifying one or more values in the operation’s field[operation] URL parameter. The API reference page for each operation have information about the available sparse fields (also knows as query params).

Query param descriptions

Query param name

Description

accountnames

Include first, middle, and last-name of user accounts that interacted with an RFQ (request for quote)

amenities

Information about the aircraft’s amenities

analytics

Analytics regarding a single piece of lift for a single RFQ (request for quote)

aviquote

Detailed information about the quote that Avinode generated on behalf of the seller for an RFQ (request for quote). For example the cost of any positioning legs required to do this flight

buyermessages

Lists all buyer messages associated with an RFQ (request for quote).

categorydetails

Detailed information about the aircraft category

homebase

Information about the aircraft’s homebase airport

insurance

Insurance information for the aircraft

latestquote

The latest added quote on a lift

liftaoc

Information about the operator’s AOC

office

Information about the buyer’s primary office

perfdetails

Information about the aircraft’s performance details

quoteattachments

Any attachments (PDF-files etc.) added to the quote

quotebreakdown

A detailed breakdown of the quote consisting of the different sections and line items

safety

Information about any safety ratings held by the operator of this aircraft

schedule

Information about when the seller last updated the availability information for this aircraft

sellercontactinfo

Contact details of the seller company

sellermessagelinks

Include direct links to the /tripmsgs endpoint in the response

sellerprofilephoto

Profile photo for this account in Avinode (URL)

sellerstats

Will add the following data points to the response:

quoteCount
The number of seller quotes considered in these statistics

underPricedQuoteCount
The count of seller quotes where the price was LESS THAN marketplace quote

underPricedQuoteAveragePercent
The absolute, average percent difference that seller quote prices are LESS THAN the marketplace quote

overPricedQuoteCount
The count of seller quotes where the price was GREATER THAN marketplace quote

overPricedQuoteAveragePercent
The absolute, average percent difference that seller quote prices are GREATER THAN the marketplace quote

medianResponseTimeMinutes
The median response time in minutes for the seller to respond to a request

responseRatePercent
The percentage of times that the seller responds to a request

priceAccuracyPercent
Percent of quotes with a price increase below a threshold. An accurate price will be below or matching the Avinode generated price, also allowing up to a 5% increase.
An average of the last 30 days of requests will be calculated.

startposition

Information about where the aircraft is positioned from to perform the first passenger segment

taildetails

Additional information about the aircraft

tailphotos

Links to photos of the actual aircraft

timestamps

Include updatedByBuyer and latestUpdatedDateBySeller fields in the response

typedetails

Detailed information about the aircraft type

typephotos

Links to generic photos of the aircraft type

ID's

Unless specifically stated in this documentation, the format of any object’s identifier is unspecified and can change at any time. Therefor an operation that currently returns an ID that looks like “abc-12345678” may change to, for example, “1234-ABCD-5678-EF90”. So the application should not try to extract parts of the these ID's for any reason. If the format of an ID changes, the API operations using this ID as input will continue to support previous formats.

The application should not display any API generated ID's to the user, unless this documentation specifically states that the particular ID can be displayed.

String handling

Data entered in string properties must conform to the following rules:

  • If a string contains multiple lines then new lines must either be sent as line feed (\n) or carriage return and line feed (\r\n).
  • If a string contains a backslash character (\) then it must be escaped with an additional backslash character (\\).
  • If a string contains a double quotation mark (") then this must be escaped with a backslash character (\").

Data returned in string properties should be display correctly to the users of the application, according to the rules above.

API additions and updates

Most additions and updates to the APIs will be backwards compatible. Any major changes impacting live applications will be communicated some time before the change is made, giving you ample time to make the necessary changes. This time is regulated in the API contracts. Information about additions and updates are listed on the Change log page.

New properties can, at any time, be added to an operations output. The application must be able to handle this without breaking.

Retry polices

If a call to the API fails for some reason, any retry policy should be sensibly implemented. This would most likely include concepts like exponential back-off, maximum number of retries etc. For some operations, retries are not allowed. The documentation page for each operation may have information about the recommended retry policy.

Automatic testing

No automatic tests are allowed to make calls to the API. This applies to all types of automatic testing like load tests, integration test suites etc. All logic generating calls to the API must be replaced by mock-ups when running automatic tests. This is true for both the live system and the sandbox environment.

API contracts

The contracts in place for each member or partner using the APIs regulates how the APIs can be used, and how the data returned by the APIs can be handled. Paragraphs regulating the following can be included.

  • Which API related use cases the application can implement
  • How and for how long certain data returned by the APIs can be stored
  • How, and to whom, data returned by the APIs can be shared

❗️

Abuse

Calling any API operations in any repetitive or automated fashion for the purpose of harvesting information is strictly forbidden.

👍

Implementation checklist

All items on this check list must be true in order for an application to be allowed to call the live Avinode Marketplace environment.

  • The application only implements API call related use cases that are approved by Avinode or SchedAero.
  • The application does not store any data, returned by the APIs, that is not allowed to store.
  • The application does not share any data, returned by the APIs, that is not allowed to share.
  • The application’s API token (the token sent in the X-Avinode-ApiToken HTTP header) is hard coded into the application and not configurable by the users of the application.
  • The application always sends its name and version in the X-Avinode-Product HTTP header.
  • The application does not display API generated ID's to the user, unless this documentation specifically states that the particular ID can be displayed.
  • The application does not, for any reason, extract any parts of an API generated ID.
  • The application handles Authentication Tokens with the appropriate level of security to avoid it from falling into the wrong hands.
  • The application escapes and handles string data according to the specified rules.
  • The application can handle that an operation suddenly returns properties that wasn’t returned at the time of implementation.
  • The application has sensible retry policies for failed calls to operations that allow retries.
  • Instances of the application built or deployed for development or testing purposes cannot call the live API servers or consume live web-hook notifications.

Did this page help you?