Approval Services
This document describes the typical flow and expected behaviour of Approval Services via API.
ONBOARDING
Please be aware that, through this service, Altitude Angel will act as a broker for the issuance of airspace and landowner Approvals, including permission to operate within controlled/restricted airspace. As such, integrators will be required to complete an onboarding programme, prior to go-live, to ensure that Approval states and the associated workflows have been appropriately implemented.
Our expert Customer Success team will support and guide you through this simple process.
What is this API for?
We've designed our Approval Services API to act as a single, consistent interface into multiple countries' airspace authorisation systems. The concept is to present a single API regardless of the back-end authorization systems in place in each country, thereby minimising your time-to-development and associated development costs.
Using a canonical model, we believe that the complexity of local in-country systems can be abstracted away, insulating developers from lengthy certification, complex implementation and changing regulations/standards.
Thus, everything begins with a Flight Plan object. Within the flight plan, you specify the area in which you wish to fly (in any country), and we'll tell you whether authorization is required, whether it can be fulfilled automatically, or whether the country doesn't have a digital authorization system.
Flight Plans
Flight Plans are required to start flights, and is the part of the process concerned with acquiring permission from authorities ("approvers") in the planned flight area to carry it out.
When a flight plan is created, it can only be accessed and modified by the same client that it was created by.
If a created Flight Plan has the state of one of its approvals modified (e.g. a pending request being rejected), then a notificaton will be sent to the the configured webhook url, stating that there has been a change.
Setup
All Flight Plan endpoints implement the standard AA Auth process of Authorization as is standard across all Altitude Angel APIs, so the appropriate Bearer Token must be provided on the request.
For the purposes of this document, that will be a Client Credentials access token.
All DateTime
objects are ISO 8601 strings of a given time and date.
Getting Started
To get started, you can view our OpenAPI documentation.
Preview
Before creating the Flight Plan in a given area, you may make an initial preview call. This initial call is to see the approvals your flight plan may require and any approval options you must choose & provide.
Each Flight Part is a section of the overall flight that takes place within a certain geographical and temporal area. A flight can be broken up into as many or as few parts as desired, but each Flight Part for a single Plan must have a unique Id
.
Creating a flight plan
Assuming that you are happy with the preview, you may now want to create the actual flight plan, and "lock-in" to the approval options offered by the external approvers.
A successful request does not mean that the Flight Plan itself has been approved. It will still require approvals from each approver.
Approval Status
Each approval on your flight plan will be given an ApprovalState
.
An ApprovalStatus
encompasses the intricacies of flight approval and provides the information necessary to proceed.
Futher details and models are given in our OpenAPI documentation.
It is important to note that even if the flight plan is initially approved, it is possible for external approvers to revoke the authorisation at any point. Similarly, some authorisation may require manual intervention. For these reasons, whenever the status of a flight plan's approvals change, a notification will be sent to the configured webhook endpoint.
Cancelling a flight plan
Cancelling Flight Plans is an important feature to take note of because it confirms that the flight plan will not take place. For example, if a Flight Plan is initially approved but that approval is later rescinded, the Flight Plan must be cancelled manually through this endpoint to show that the operator is aware of the revocation.
Updating a Flight Plan
A created Flight Plan may be updated, such as the time in which a flight part takes place. These changes, however, will be subject to reapproval by the external approvers.
Approval Services Integration
Flight plans with Approval Services support have additional requirements beyond those of a regular flight plan.
1. Approvals Preview
The first step in this flow is to retrieve a preview of the approvals that will be required when the flight plan is formally submitted, by sending a Flight Plan Preview request (see our OpenAPI Documentation).
The relevant data returned here is the set of rateCards
available to the user. Each rate card returned here corresponds to payment required for a given approval (in approvals
), linked by the externalFacilityId
they both refer to.
If no rate cards are returned, then the flight plan does not require approval services and will not need to be augmented with the behaviour described in the remainder of this document.
2. Rate Cards
A rate card represents the approval services offered by a given approver, for the facility that they manage. The rate cards here and their options should be presented to the user creating the flight plan.
Facilities will typically provide a number of service levels, with a range of charges, and may even include a free option. Your user must select the rate they require.
Each rate card provided in the Approvals Preview step is independent - they correspond to different approvals, and all are required.
{
"externalFacilityId": "urn:aa:zone:8f90c6a3-29e4-41cc-951c-bb81ac4aadd9",
"externalFacilityName": "Example Facility",
"externalFacilityType": "airspace",
"externalFacilityEmail": "[email protected]",
"rateCard": {
"id": "5c4b5497-8edd-4078-bba5-d2a0e46d98f2",
"name": "Example Rate Card",
"rates": [
{
"id": "11f5a250-0d41-4594-9f0e-1a3d83afe6aa",
"name": "Basic Tier",
"rate": 5.0,
"ordinal": 2
},
{
"id": "4b542276-9fd5-48b5-a84b-0bc9bde1e0e4",
"name": "Premium Tier",
"rate": 10.0,
"ordinal": 1
}
],
"currency": "GBP",
"taxRate": 20.0,
"rateCardTerms": "https://example.com/facility-terms-and-conditions",
"rateCardTermsVersion": "2023-05-23T14:41:30.7374561Z",
"aaTerms": "https://example.com/aa-terms-and-conditions",
},
"rateCardAppliesAt": "2024-04-17T09:54:23.8034661+00:00"
}
rates
rates
These are the options that the user has for approval services in a given facility.
- One must be selected.
- Their cost is
rate
in the rate card'scurrency
- the given value does not include tax.- In the example above,
Premium Tier
would cost12.0 GBP
- the rate of the service, with the rate card'staxRate
andcurrency
.
- In the example above,
- They should be displayed to the user sorted by their
ordinal
property, ascending.- In the example above,
Premium Tier
should be displayed beforeBasic Tier
.
- In the example above,
rateCardTerms
rateCardTerms
These are terms and conditions for the rate card, as issued by the facility. These must be presented to the user for them to accept or decline.
aaTerms
aaTerms
These are the terms and conditions of use, as issued by Altitude Angel. These must be presented to the user for them to accept or decline.
3. Creating the Flight Plan
The rate card related information gathered should be attached to the create flight plan request to continue the integration with approval services, using:
facilityOptions
, the selected services for each facility.- Each item returned by
rateCards
from the preview request should have a corresponding entry.
- Each item returned by
termsAndConditionsAcceptedAt
, when the user accepted the terms and conditions.
For example, a flight plan created for the earlier preview may include the following properties:
{
"facilityOptions": {
"facilityId": "urn:aa:zone:8f90c6a3-29e4-41cc-951c-bb81ac4aadd9",
"services": {
"flight-plan-approvals": {
"serviceLevel": "11f5a250-0d41-4594-9f0e-1a3d83afe6aa",
"termsAndConditionsVersion": "2023-05-23T14:41:30.7374561Z"
}
},
},
"termsAndConditionsAcceptedAt": "2023-06-02T09:22:41.87103641Z"
}
Property | Description |
---|---|
facilityId | The ID of the facility this set of options is for. This corresponds to externalFacilityId in the rate card. |
services | The services being requested from the facility. This should be an object with the key flight-plan-approvals . |
serviceLevel | The ID of the service level the user wishes to make their flight plan under, as chosen from the rates of the rate card. |
termsAndConditionsVersion | The version of the rate card terms and conditions that the user accepted. This corresponds to rateCardTermsVersion in the rate card. If the version is not the latest version available, an error will be returned and a new preview call should be made to retrieve the latest version. |
termsAndConditionsAcceptedAt | The time at which the user accepted the terms and conditions. |
4. Paying for the Flight Plan
Payment, if required, is only taken after the flight plan has been approved by all relevant facilities. If payment is required but payment details are not provided, then the flight plan cannot be approved.
If the user selected a service level that is subject to payment, then they will be asked to enter payment details. This requirement will be indicated to them as an action that they need to take in order to receive said approval, in the status
property of the create flight plan response.
{
"state": "pending",
"actionRequired": true,
"shouldKeepWorkflowDecisionsAfterEdit": false,
"actions": [
{
"id": "d958458d-f22f-4392-bae2-a56a6ca1e8e8",
"description": "Provide Payment Information",
"type": "providePaymentDetails",
"requiredData": [
"https://ecommerce.altitudeangel.com/default/payment/method/external/V3JIcGxrS2NxM1VEMGtDejBXY1J6bWRoR3MzT3kreVVRVkhqdFdBdWhoeS93eTRpRFZaNXNTVjluZ2pvb043TVRVaHk1MWJZaHNzendEUHlUOUdMaFE9PQ"
]
}
]
}
In this case, an action of type providePaymentDetails
will be given, with the URL to do so provided in requiredData
.
The payment URL will be the only value in the
requiredData
array, forprovidePaymentDetails
actions.
This URL is unique per flight plan - each one can only pay for the plan it is associated with, and should only be given to the user whose responsibility it is to pay.
Example card numbers for TEST env:
Card Number | Description |
---|---|
4242424242424242 | Successful payment. |
4000002760003184 | Requires manual authentication after adding and trying to take payment. |
4000000000000341 | Will fail to take payment. |
5. Payment Failures
Because payment is not taken when payment details are entered but when the approval is granted, it is possible for the payment to have failed or require manual confirmation. This will be similarly surfaced as an action that the user needs to take, this time with type resolvePaymentFailure
.
{
"id": "bada634e-c720-4354-9d4b-f8eae64e1dd5",
"description": "Authentication Required",
"type": "resolvePaymentFailure",
"requiredData": [
"https://ecommerce.altitudeangel.com/default/payment/manualconfirmation/external/V3JIcGxrS2NxM1VEMGtDejBXY1J6bWRoR3MzT3kreVVRVkhqdFdBdWhoeS93eTRpRFZaNXNTVjluZ2pvb043TVRVaHk1MWJZaHNzendEUHlUOUdMaFE9PQ/transaction/825be665-d44c-4c8e-abd6-cc95df45a02c"
]
}
This URL is different to the one used for providePaymentDetails
.
6. Webhooks
If webhook notifications are enabled, the following payment-related webhooks may be issued:
flight-plan-approval-updated
flight-plan-approval-updated
{
"schema": "1",
"id": "dbd1bb011a9e4a4493506471daa77a77",
"type": "flight-plan-approval-updated",
"source": "flight.altitudeangel.com",
"subject": "id:flightPlan:4cd0572e-8de4-49b9-8122-dd03d896f443",
"time": 1718272748132,
"data": {
"approvalId": "533af4ad-39f6-4cda-91ce-d0a15c775220",
"flightPlanId": "4cd0572e-8de4-49b9-8122-dd03d896f443",
"flightPlanVersion": "2024-06-13T09:54:12Z"
}
}
Name | Type | Description |
---|---|---|
approvalId | string | The ID of the approval that has been updated. |
flightPlanId | string | The ID of the flight plan that this update refers to. |
flightPlanVersion | string | The version of the flight plan that this update refers to. |
These are issued when an approval for a flight plan changes. This can occur when:
- An approval has been actioned by an approver (e.g. approving it, so it transitions from
pending
toapproved
). - An action that the user needs to perform has been added to the approval, such as resolving a payment failure mentioned in
5. Payment Failures
. - The flight plan's approvals have been reset.
- This occurs if an approver rejects a plan, and then resets it back to pending. In this case, new approvals will be generated for the plan, and the old ones will be discarded.
To see the new state of the approval, GET
the full flight plan.
Updated 15 days ago