📘

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

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's currency - the given value does not include tax.
  • In the example above, Premium Tier would cost 12.0 GBP - the rate of the service, with the rate card's taxRate and currency.
• They should be displayed to the user sorted by their ordinal property, ascending.
  • In the example above, Premium Tier should be displayed before Basic Tier.

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

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.
• 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"
}

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, for providePaymentDetails 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:

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

{
  "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"
  }
}

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 to approved).
• 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.