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.


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



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.




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


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


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

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


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.






The request has succeeded.



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


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).



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



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


Not found

The application requested a resource that does not exist


Simultaneous updates, operation aborted

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


Unprocessable Entity

Validation failure, relationship failure, or state failure


Rate Limited

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

See "Service Rate Limits" below for more details


Internal Server Error

Internal failure


Service Unavailable

Service too busy


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.


Date and time

Dates and times are formatted according to ISO 8601.


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



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


Information about the aircraft’s amenities


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


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


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


Detailed information about the aircraft category


Information about the aircraft’s homebase airport


Insurance information for the aircraft


The latest added quote on a lift


Information about the operator’s AOC


Information about the buyer’s primary office


Information about the aircraft’s performance details


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


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


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


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


Contact details of the seller company


Include direct links to the /tripmsgs endpoint in the response


Profile photo for this account in Avinode (URL)


Will add the following data points to the response:

The number of seller quotes considered in these statistics

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

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

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

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

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

The percentage of times that the seller responds to a request

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.


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


Additional information about the aircraft


Links to photos of the actual aircraft


Include updatedByBuyer and latestUpdatedDateBySeller fields in the response


Detailed information about the aircraft type


Links to generic photos of the aircraft type


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



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?