API Access

API Access

There is an API for read-only access to bookings and aircraft booked out.

You might find API access useful if you need to extend the system for yourself. For example:

  • Automatically send an email to staff near the end of the day if there are any out of hours flights booked. This could be used to make sure the aircraft keys are left out instead of being locked up.
  • Show today's bookings on a screen in the office. You should consider whether to expose member's names to other people (the system hides other member names unless they have opted in to being contacted).
  • Extract billing transactions and transfer them to your bookkeeping package, e.g. Xero, Quickbooks, MYOB.

 

Authentication

The API uses simple authentication. The tokens are managed in Admin > API Access, which means they can be set up independently of your users. Therefore they do not depend on staff leaving the business. The token is a long string which looks something like "fb1f233e08aeef0a213dc87cea70cedbd7dbcd0a2229cac4f64e14e3c462cc8e". For each token you can grant access to different parts of the system, for example you could grant access for an application to read which aircraft are booked out, but not grant access to your billing system.

When making a request, include an authorisation header containing your token, for example:

curl -H "Accept: application/json" -H "Authorization: Bearer fb1f233e08aeef0a213dc87cea70cedbd7dbcd0a2229cac4f64e14e3c462cc8e" https://acme.flightschoolbooking.com/club/bookings

Parameters

Parameters can be sent in the query string, e.g.

https://acme.flightschoolbooking.com/club/bookings?page=0

Response format

Responses are returned in JSON.

When a URL is included in an object's output, you can use this URL  as an endpoint to re-read the same object. This means you can follow the progress of a specific booking or booked out record if you need to.

Mathew Waters Sat, 03/10/2020 - 15:19

Users

Users

This API is used to read the list of users. For information about how to get started using the APIs available, see API Access.

Parameters

  • page (integer)
    Zero-based page number. The query returns up to 50 rows per page. Based on has_more you might increment the page and request the next set of results.
  • role (string)
    One of the built-in roles (air_experience, student, lapsed_student, associate_member, member, lapsed_member, engineer, safety_staff, instructor, office, owner).
  • name (string)
  • email (string)
    Set the name or email parameter to search for a specific user (exact match)

 

Output

  • total (integer)
    Total number of records available (not affected by the page parameter).
  • has_more (boolean)
    True if there are more records available by incrementing the page parameter. When false you have read the whole list.
  • change_id (string)
    A string value which indicates whether any records have changed. If you have read all data previously and the next read returns the same change_id, nothing has changed. However, if the value changes you might discard your current result set and read again from the first page.
  • rows  (array)
    Each row contains information about a user.

 

Each row contains the following fields.

  • id (integer)
  • url (string)
  • name (string)
  • email (string)
  • can_log_in (bool)
  • price_group (string)
  • roles (array)
  • created (integer)
    Timestamp for the time the user account was created.
  • accessed (integer)
    If the user has logged in, this is the last time they were active.
  • date_of_birth (Y-m-d)
  • membership_renewal_date (Y-m-d)
  • medical_renewal_date (Y-m-d)
  • revalidation_next_due (Y-m-d)
  • home_phone_number (string)
  • work_phone_number (string)
  • mobile_phone_number (string)
  • address (string)
  • next_of_kin_details (string)
  • previous_experience (string)
  • comments (string)
  • internal_notes (string)

Notes

Not all fields are present for every user.

Example

curl -H "Accept: application/json" -H "Authorization: Bearer fb1f233e08aeef0a213dc87cea70cedbd7dbcd0a2229cac4f64e14e3c462cc8e" "https://acme.flightschoolbooking.com/club/user"

(Use your own site's URL, replacing acme with the name of your subdomain and use your own token)

Mathew Waters Mon, 16/11/2020 - 10:27

Bookings

Bookings

This API is used to read the future bookings. For information about how to get started using the APIs available, see API Access.

Parameters

  • page (integer)
    Zero-based page number. The query returns up to 50 rows per page. Based on has_more you might increment the page and request the next set of results.
  • include_cancellations (0 or 1)
    Normally only active bookings are returned. Use this parameter to extend the results to include cancellations.
  • include_unavailability (0 or 1)
    Extend the results to include periods of unavailability (member field is returned blank)

 

Output

  • total (integer)
    Total number of records available (not affected by the page parameter).
  • has_more (boolean)
    True if there are more records available by incrementing the page parameter. When false you have read the whole list. Before reading the whole list, consider whether this is necessary or do you only need to read to the end of the current day?
  • change_id (string)
    A string value which indicates whether any bookings have been added or updated. If you have read all data previously and the next read returns the same change_id, nothing has changed. However, if the value changes you might discard your current result set and read again from the first page.
  • rows  (array)
    Each row contains information about a booking.

 

Each row contains the following fields

  • id (integer)
  • url (string)
  • start_time (integer)
  • stop_time (integer)
  • booked_at (integer)
  • originator_id (integer)
  • originator_name (string)
  • customer_id (integer)
  • customer_name (string)
  • aircraft_id (integer)
  • aircraft (string)
  • instructor_id (integer)
  • instructor_name (string)
  • notes (string)

 

If the booking was cancelled, the following additional fields are present:

  • cancelled (boolean)
  • cancelled_at (integer)
  • cancelled_by (string)
  • cancelled_notes (string)

 

The customer, aircraft and instructor fields are optional. If a booking is a period of unavailability (for aircraft or instructor) there will be no customer fields. Similarly, if the booking does not include an aircraft there will be no aircraft fields.

Notes

Start reading at page zero. There could be a change in bookings in between you asking for page 0 and page 1, so check the change_id is the same and re-start from page=0 if it changes.

Then keep asking for more pages until you reach a date that you don’t need (records are ordered in ascending date order) or has_more returns false.

Example

curl -H "Accept: application/json" -H "Authorization: Bearer fb1f233e08aeef0a213dc87cea70cedbd7dbcd0a2229cac4f64e14e3c462cc8e" "https://acme.flightschoolbooking.com/club/bookings?page=0&include_cancellations=1&include_unavailability=1"

(Use your own site's URL, replacing acme with the name of your subdomain and use your own token)

The output looks like this:

{
  "total": "378",
  "has_more": true,
  "change_id": "15a981ba73513efc",
  "rows": [
    {
      "url": "https://acme.flightschoolbooking.com/user/21682/bookings/booking/5",
      "startTime": "1590998400",
      "stopTime": "1591005600",
      "bookedAt": "1590951551",
      "member": "John Smith",
      "aircraft": "G-AABC",
      "instructor": "",
      "notes": ""
    },
    . . . 
  ]
}

Mathew Waters Mon, 05/10/2020 - 10:10

Booked out

Booked out

This API is used to read the list of aircraft booked out. For information about how to get started using the APIs available, see API Access.

Parameters

  • page (integer)
    Zero-based page number. The query returns up to 50 rows per page. Based on has_more you might increment the page and request the next set of results.

 

Output

  • total (integer)
    Total number of records available (not affected by the page parameter).
  • has_more (boolean)
    True if there are more records available by incrementing the page parameter. When false you have read the whole list.
  • change_id (string)
    A string value which indicates whether any records have changed. If you have read all data previously and the next read returns the same change_id, nothing has changed. However, if the value changes you might discard your current result set and read again from the first page.
  • rows  (array)
    Each row contains information about a booked out aircraft.

 

Each row contains the following fields.

  • id (integer)
  • url (string)
  • created_at (integer)
  • out_time (integer)
  • eta_time (integer)
  • booking (object)
    If the booking out record is linked to a booking, see Bookings.
  • originator_id (integer)
  • originator_name (string)
  • aircraft_id (integer)
  • aircraft (string)
  • pilot_id (integer)
  • pilot_name (string)
  • pilot_role (string)
    The role of the pilot at the time of the flight. One of instructor, member, student.
  • student_id (integer)
  • student_name (string)
  • student_role (string)
    The role of the student at the time of the flight. One of air_experience, instructor, member, student.
  • passengers (string)
  • departed (string)
  • destination (string)
  • pob (integer)
  • fuel_added (decimal)
  • p1_in (integer)
    Present if the flight was booked in (either flight or aborted flight)
  • notes (string)

 

Notes

Because schools typically have less than ten aircraft you will not normally need to read more than the first page!

Example

curl -H "Accept: application/json" -H "Authorization: Bearer fb1f233e08aeef0a213dc87cea70cedbd7dbcd0a2229cac4f64e14e3c462cc8e" "https://acme.flightschoolbooking.com/club/booked-out"

(Use your own site's URL, replacing acme with the name of your subdomain and use your own token)

The output looks like this:

{"total":"1","has_more":false,"change_id":"de2b52af6a442955","rows":[{"url":"https:\/\/acme.flightschoolbooking.com\/club\/bookings\/booking\/137\/movement\/32","outTime":"1602007500","etaTime":"1602011100","aircraft":"G-LOLZ","pilot":"Sarah Smith","student":"","departed":"Kemble","destination":"Local","pob":1,"notes":""}]}

Mathew Waters Wed, 07/10/2020 - 13:40

Training records

Training records

This API is used to read the list of training notes. For information about how to get started using the APIs available, see API Access.

Parameters

  • page (integer)
    Zero-based page number. The query returns up to 50 rows per page. Based on has_more you might increment the page and request the next set of results.
  • student_id (integer)
    List training notes from a specific student.
  • instructor_id (integer)
    List training notes from a specific instructor.
  • incomplete_only (0/1)
    Filters the list to show only incomplete training records (where the instructor still needs to add their notes).

 

Output

  • total (integer)
    Total number of records available (not affected by the page parameter).
  • has_more (boolean)
    True if there are more records available by incrementing the page parameter. When false you have read the whole list.
  • change_id (string)
    A string value which indicates whether any records have changed. If you have read all data previously and the next read returns the same change_id, nothing has changed. However, if the value changes you might discard your current result set and read again from the first page.
  • rows  (array)
    Each row contains information about a training record.

 

Each row contains the following fields.

  • id (integer)
  • url (string)
  • start_time (integer)
    Training start time recorded as unix epoch.
  • stop_time (integer)
    Training finish time.
  • instructor_id (integer)
  • instructor_name (string)
  • student_id (integer)
  • student_name (string)
  • operating_capacity (string)
  • exercises (string)
  • notes (string)
  • flight (object)
    If the training refers to a flight, the flight information is included.
  • voucher (object)
    If the training was for a ground school voucher, the voucher is included.
  • invoice_reference (string)
  • accounts_code (string)
    If an accounts code is used during billing it is stored against the training record to allow for analysis.

 

Notes

Not all fields are present for every training record. For example, the flight object is not included for ground school.

Example

curl -H "Accept: application/json" -H "Authorization: Bearer fb1f233e08aeef0a213dc87cea70cedbd7dbcd0a2229cac4f64e14e3c462cc8e" "https://acme.flightschoolbooking.com/club/training"

(Use your own site's URL, replacing acme with the name of your subdomain and use your own token)

Mathew Waters Thu, 19/11/2020 - 16:10

Billing transactions

Billing transactions

This API is used to read the list of financial transactions from the billing system. For information about how to get started using the APIs available, see API Access.

Parameters (optional)

  • page (integer)
    Zero-based page number. The query returns up to 50 rows per page. Based on has_more you might increment the page and request the next set of results.
  • customer_id (integer)
    Returns all transactions for a specific customer.
  • reference (string)
    Return a specific transaction (matching the reference as text, eg 00001).
  • instructor_id (integer)
  • aircraft_id (integer)
  • accounts_code (string)
  • tax_code (string)

 

Output

  • total (integer)
    Total number of records available (not affected by the page parameter).
  • has_more (boolean)
    True if there are more records available by incrementing the page parameter. When false you have read the whole list.
  • change_id (string)
    A string value which indicates whether any records have changed. If you have read all data previously and the next read returns the same change_id, nothing has changed. However, if the value changes you might discard your current result set and read again from the first page.
  • rows  (array)
    Each row contains a billing transaction.

 

Each row contains the following fields.

  • id (integer)
  • url (string)
  • timestamp (integer)
  • date (string/Y-m-d)
    Timestamp and date are the document date
  • type_id (integer)
    Invoice (0), Credit (1), Payment (2), Refund (3), Opening balance (4), Adjustment (5).
  • type_text (string)
  • drcr (string)
    Debit (dr) or credit (cr) the Accounts Receivables.
  • due_date (string/Y-m-d)
    For invoices only.
  • reference (string)
  • customer_id (integer)
  • customer_name (string)
  • total (decimal)
  • tax_content (decimal)
  • processor_fee (decimal)
  • platform_fee (decimal)
    Processor and platform fee appear only for payments (receipts via Stripe).
  • lines (array)
    Line items, see later.

 

If the transaction is voided, the following fields exist:

  • deleted (0/1)
  • deleted_at (integer)
  • deleted_by (string)
  • deleted_notes (string)

 

Line items

Each line in the lines array represents a line item on an invoice / credit etc. Each contains the following fields.

  • line_number (integer)
  • timestamp (integer)
  • description (string)
  • quantity (integer)
  • each (decimal)
  • total (decimal)
  • tax_code (string)
  • tax_content (decimal)
    Tax fields only for invoices and credits.
  • plan_reference (string)
  • plan_version (integer)
    Plan fields are included if the invoice or credit was created by the system.
  • accounts_code (string)
  • item_start (integer)
  • item_stop (integer)
  • url (string)
    A url for the item sold, e.g. the flight, ground school record etc.
  • voucher (string)
  • aircraft (string)
  • instructor (string)

Notes

Amounts are in the local currency.

Example

curl -H "Accept: application/json" -H "Authorization: Bearer fb1f233e08aeef0a213dc87cea70cedbd7dbcd0a2229cac4f64e14e3c462cc8e" "https://acme.flightschoolbooking.com/club/billing/all"

(Use your own site's URL, replacing acme with the name of your subdomain and use your own token)

Mathew Waters Thu, 12/11/2020 - 09:10

Vouchers

Vouchers

This API is used to read the list of vouchers. For information about how to get started using the APIs available, see API Access.

Parameters

  • page (integer)
    Zero-based page number. The query returns up to 50 rows per page. Based on has_more you might increment the page and request the next set of results.

Note you can retrieve a specific voucher by its ID. See later.

Output

  • total (integer)
    Total number of records available (not affected by the page parameter).
  • has_more (boolean)
    True if there are more records available by incrementing the page parameter. When false you have read the whole list.
  • change_id (string)
    A string value which indicates whether any records have changed. If you have read all data previously and the next read returns the same change_id, nothing has changed. However, if the value changes you might discard your current result set and read again from the first page.
  • rows  (array)
    Each row contains information about a voucher.

 

Each row contains the following fields.

  • id (integer)
  • url (string)
  • code (string)
  • originator_id (integer)
  • originator_name (string)
  • type (integer)
    Flight (0), Ground school (1)
  • recipient_user_id (integer)
  • recipient_user_name (string)
  • recipient_name (string)
  • issued_at (integer)
  • duration_mins (integer)
  • purchase_price (decimal)
  • purchaser_name (string)
  • purchaser_email (string)
  • purchaser_address (string)
  • billing (object)
    An object containing two fields, invoice and payment. Both are of the billing transactions type.
  • greeting (string)
  • message (string)
  • edits_completed (integer)
    Timestamp when edits were completed and finalised by the purchaser.
  • expire_at (integer)
  • unsubscribed (true)
  • unsubscribed_at (integer)
    If the purchaser receives an email follow-up because the voucher has not been used, they can unsubscribe from future emails about the voucher.
  • sku (string)

 

If the voucher is deleted, the following fields exist:

  • deleted (0/1)
  • deleted_at (integer)
  • deleted_by (string)
  • deleted_notes (string)

 

Notes

Not all fields are present for every voucher. For example, if the voucher was manually added to the system the billing and purchaser_address fields are not present.

Example

curl -H "Accept: application/json" -H "Authorization: Bearer fb1f233e08aeef0a213dc87cea70cedbd7dbcd0a2229cac4f64e14e3c462cc8e" "https://acme.flightschoolbooking.com/club/voucher"

To retrieve a specific voucher by its ID, use the endpoint ending /club/voucher/<VOUCHER-CODE>. 

(Use your own site's URL, replacing acme with the name of your subdomain and use your own token)

Mathew Waters Thu, 19/11/2020 - 16:36