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' 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.
Setup
API connections are currently created and maintained by the Avinode and Schedaero support staff.
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-ApiToken *
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
Please note
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 eyJraWQiOiIxNkVBQkQ5RS1BM0...
Below is an example from Postman UI on how to configure the authorization.
Please note
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: 2023-01-01T09:00:00.007Z
X-Avinode-ApiVersion
This field must contain the API version that the application will use.
X-Avinode-ApiVersion: v1.0
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.
Please note: 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 is a required parameter and must always be populated with the name and version of the calling application.
X-Avinode-Product: Your API Application Name v1.0
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 |
For further explanation and suggested error handling of API solutions, please see Error handling guide.
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.
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.
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.
Please note: Service Rate Limits
Please note that Service Rate limits (below) are implemented for our Avinode Marketplace APIs, this is not a current response you will see from accessing Schedaero APIs.
X-Rate-Limit-Limit
The rate limit for the service that was invoked. This is the allowed number of calls per hour.
X-Rate-Limit-Remaining
The remaining number of calls allowed within the current hour.
X-Rate-Limit-Reset
In particular, note header "X-Rate-Limit-Reset" as it indicates a duration in seconds until your next API call could succeed.
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
| 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 |
IDs
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 Policies
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.
Basic Go Live requirements
All applications integrating with Avinode will have to comply with the below implementation checklist items, in addition to the specific use case requirements.
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 should have basic error handling capabilities as suggested in API Basics: Error Handling.
- 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.
Updated 5 months ago