Fieldtriq API API Reference

Welcome to the Fieldtriq API! The purpose of this API is to allow you to access and manage caregiver accounts on Fieldtriq, which contain their students and upcoming events.

The live API is located at https://fieldtriq.com/api/v1/{Endpoint}.

Registering your App

In order to get started, you'll need to register your app by creating a caregiver account. From your account settings, you can view your connected apps, and create a new app.

Some information is required about your app, such as information about your company and a redirect URI for the authentication flow. You'll then be given your access token and secret.

Terms of Service

Generally speaking this API is freely avaiable without limitations, but some terms on top of our Terms of Service:

  • You MUST NOT ask the end user for their email address or password to sign in. All authentication should be performed in a web view or the client's browser.
  • Your app must not use the Fieldtriq logo without our approval beforehand.
  • While we don't impose a rate limit, we may contact you if your client is making excessive API calls. Caching should be utilized as much as possible.

Need a hand?

If you need a hand with something or think there's something we could add to the API, get in touch by emailing [email protected] with API in the subject line.

Contact: [email protected]
Response Content-Types: application/json
Schemes: https
Version: 1.0.0

Authentication

OAuth2

flow
accessCode
authorizationUrl
https://fieldtriq.com/api/oauth2/authorize
tokenUrl
https://fieldtriq.com/api/oauth2/token

Authentication

Authorize your app

GET /oauth2/authorize

Starts the process of authorizing your app for the user. Loading this endpoint will prompt the user to sign in, enter their two-factor code if necessary, and allow your app to access their account.

This endpoint should be called from a Web View, and your app must not reset the Web View if the user leaves your app, as they may need to open their authenticator app for their two-factor authentication code.

Once the user allows access, this endpoint will redirect to your specified redirect_uri, with a code URL parameter. You'll need this code in order to obtain an access token using the /api/oauth2/token endpoint.

If the user cancels the authentication request, they'll be redirected to your specified redirect_uri WITHOUT the code parameter, but additional parameters indicating the user has cancelled the authorization request.

The code provided when redirecting back to your redirect URI expires after 10 minutes. If you do not submit an access code request in this time, you'll need to complete the authorization step again.

client_id

Your app client ID

type
integer
in
query
redirect_uri

A valid redirect URI for your app. Once the user authorizes your app, they'll be redirected to this URI

type
string
in
query
response_type

Should be set to code, as this is the only OAuth grant supported

type
string code
in
query
scope

Should be set to user, to manage the user account

type
string user
in
query
302 Found

Redirected to the login page for the user to authorize the app

401 Unauthorized

Request is not authenticated correctly

405 Method Not Allowed

Request is using the incorrect request type

Response Example (401 Unauthorized)
{
  "error": "string",
  "message": "string"
}
Response Example (405 Method Not Allowed)
{
  "success": "boolean",
  "message": "string"
}

Get an access token

POST /oauth2/token

Endpoint to swap your authorization token for an access token.

Using the code URL parameter sent to your service by using your redirect URI, you can retrieve the access token and the refresh token.

Once you complete this request and you have an access token, you'll need to provide this access token for every request that requires authentication using an Authentication: Bearer [access token] header. This token expires after one day.

The refresh token lasts for a month, and should be stored to "refresh" your access token. Just call this endpoint when your access token expires, placing your refresh token in the code field, and you'll be provided with an updated access and refresh token.

Each of these fields, apart from code MUST match the fields provided in the initial authorization request.

code

The URL parameter provided by Fieldtriq when redirected back to your redirect URI from the authorization step

type
string
in
formData
client_id

Your app client ID

type
integer
in
formData
grant_type

Either authorization_code if your code is from an authorization request, or refresh_token if your code is a refresh token provided by a previous token request

type
integer
in
formData
client_secret

Your app client secret

type
string
in
formData
redirect_uri

A valid redirect URI for your app.

type
string
in
formData
scope

Should be set to user, to manage the user account. This needs to be the same as the one defined in your authorization request

type
string user
in
formData
200 OK

The fields needed for future authentication

400 Bad Request

Request is missing a parameter

405 Method Not Allowed

Request is using the incorrect request type

Response Example (200 OK)
{
  "token_type": "string",
  "expires_in": "integer",
  "access_token": "string",
  "refresh_token": "string"
}
Response Example (400 Bad Request)
{
  "error": "string",
  "message": "string",
  "hint": "string"
}
Response Example (405 Method Not Allowed)
{
  "success": "boolean",
  "message": "string"
}

Events

Get all events

GET /events

Events in Fieldtriq are created by a school staff. Caregivers can see these events when at least one of their students has been added an an attendee.

Events can either be in draft mode or live mode, but this API will only return live events as caregivers don't see draft events.

Events can have multiple students of the caregiver associated with them.

200 OK

An array of events

401 Unauthorized

Request is not authenticated

Response Example (200 OK)
[
  {
    "id": "string",
    "organization_id": "integer",
    "name": "string",
    "description": "string",
    "location": "string",
    "start_date": "string",
    "end_date": "string",
    "created": "string",
    "venue": {
      "name": "string",
      "address": "string",
      "latitude": "string",
      "longitude": "string",
      "notes": "string"
    },
    "payments": {
      "use_hosted_payments": "boolean",
      "use_manual_payments": "boolean",
      "manual_payment_instructions": "string",
      "student_cost": "string"
    }
  }
]
Response Example (401 Unauthorized)
{
  "success": "boolean",
  "message": "string"
}
OAuth2 user

Get a single event

GET /events/{code}
code

Event unique ID

type
string
in
path
200 OK

The event was found

401 Unauthorized

Request is not authenticated

404 Not Found

No event found with the code entered

Response Example (200 OK)
{
  "event": {
    "id": "string",
    "organization_id": "integer",
    "name": "string",
    "description": "string",
    "location": "string",
    "start_date": "string",
    "end_date": "string",
    "created": "string",
    "venue": {
      "name": "string",
      "address": "string",
      "latitude": "string",
      "longitude": "string",
      "notes": "string"
    },
    "payments": {
      "use_hosted_payments": "boolean",
      "use_manual_payments": "boolean",
      "manual_payment_instructions": "string",
      "student_cost": "string"
    }
  },
  "students": {
    "id": "integer",
    "organization_id": "integer",
    "first_name": "string",
    "last_name": "string",
    "preferred_first_name": "string",
    "preferred_last_name": "string",
    "created": "string",
    "consent": {
      "consent_given": "boolean",
      "user_id": "integer",
      "user_name": "string",
      "submitted_by_staff": "boolean",
      "created": "string"
    },
    "transactions": {
      "id": "integer",
      "amount": "string",
      "created": "string"
    }
  },
  "staff": {
    "id": "integer",
    "name": "string",
    "email": "string",
    "trip_attendee": "boolean",
    "trip_contact": "boolean"
  }
}
Response Example (401 Unauthorized)
{
  "success": "boolean",
  "message": "string"
}
Response Example (404 Not Found)
{
  "success": "boolean",
  "message": "string"
}
OAuth2 user

Students

Get all students

GET /students

Students represent the children of caregivers. Students are assigned to a caregiver, either by the caregiver a unique student code (provided by their school) or by requesting access from the school, who'll approve or deny the request and assign them their children on their behalf.

Students can be assigned to multiple caregivers, who'll see their events and have the opportunity to provide consent for a field trip.

200 OK

An array of students

401 Unauthorized

Request is not authenticated

Response Example (200 OK)
[
  {
    "id": "integer",
    "organization_id": "integer",
    "first_name": "string",
    "last_name": "string",
    "preferred_first_name": "string",
    "preferred_last_name": "string",
    "created": "string"
  }
]
Response Example (401 Unauthorized)
{
  "success": "boolean",
  "message": "string"
}
OAuth2 user

Users

Get the logged-in user

GET /user
200 OK

Object containing the caregiver, their students, and their organizations

401 Unauthorized

Request is not authenticated

Response Example (200 OK)
{
  "id": "integer",
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "home_phone": "string",
  "mobile_phone": "string",
  "created": "string",
  "students": [
    {
      "id": "integer",
      "organization_id": "integer",
      "first_name": "string",
      "last_name": "string",
      "preferred_first_name": "string",
      "preferred_last_name": "string",
      "created": "string"
    }
  ],
  "organizations": [
    {
      "id": "integer",
      "name": "string",
      "country": "string",
      "street": "string",
      "suburb": "string",
      "city": "string",
      "phone": "string",
      "created": "string"
    }
  ]
}
Response Example (401 Unauthorized)
{
  "success": "boolean",
  "message": "string"
}
OAuth2 user

Update the logged-in user

PUT /user

Updates the current user with the specified fields. All fields are optional; supplying a non-empty field will update that field

first_name

New first name

type
string
in
formData
last_name

New last name

type
string
in
formData
phone

New phone number

type
string
in
formData
200 OK

Object containing the caregiver, their students, and their organizations

401 Unauthorized

Request is not authenticated

500 Internal Server Error

Request contains invalid parameters

Response Example (200 OK)
{
  "id": "integer",
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "home_phone": "string",
  "mobile_phone": "string",
  "created": "string",
  "students": [
    {
      "id": "integer",
      "organization_id": "integer",
      "first_name": "string",
      "last_name": "string",
      "preferred_first_name": "string",
      "preferred_last_name": "string",
      "created": "string"
    }
  ],
  "organizations": [
    {
      "id": "integer",
      "name": "string",
      "country": "string",
      "street": "string",
      "suburb": "string",
      "city": "string",
      "phone": "string",
      "created": "string"
    }
  ]
}
Response Example (401 Unauthorized)
{
  "success": "boolean",
  "message": "string"
}
Response Example (500 Internal Server Error)
{
  "success": "boolean",
  "message": "string"
}
OAuth2 user

Meta

Information about this API

GET /meta
200 OK

Version of the API

401 Unauthorized

Request is not authenticated

Response Example (200 OK)
{
  "version": "integer"
}
Response Example (401 Unauthorized)
{
  "success": "boolean",
  "message": "string"
}
OAuth2 user

Schema Definitions

Error: object

success: boolean false
message: string
Example
{
  "success": "boolean",
  "message": "string"
}

Event: object

An outing or field trip.

An event is created for each activity the school needs caregiver permission or payment before the event can take place.

Example events include a school activity day, going to the mueseum, or an overseas trip.

id: string

Event ID.

organization_id: integer

Organization ID.

name: string

Event name.

description: string

Event information.

location: string

Event location

start_date: string

Date/time the event starts

end_date: string

Date/time the event ends

created: string

Date/time the event was created

venue: Venue

Information about where the event is being held

payments: EventPaymentSettings

Information about how caregivers pay for the event

Example
{
  "id": "string",
  "organization_id": "integer",
  "name": "string",
  "description": "string",
  "location": "string",
  "start_date": "string",
  "end_date": "string",
  "created": "string",
  "venue": {
    "name": "string",
    "address": "string",
    "latitude": "string",
    "longitude": "string",
    "notes": "string"
  },
  "payments": {
    "use_hosted_payments": "boolean",
    "use_manual_payments": "boolean",
    "manual_payment_instructions": "string",
    "student_cost": "string"
  }
}

Venue: object

Where an event is held.

When a school creates an event, they can choose to set a venue for the event. Fieldtriq uses the Google Places Autocomplete API to let the school search for a particular location or address.

The school can tweak the address or name of the location, while Fieldtriq will store the latitude and longitude as returned by Google of the venue so a map can be displayed of the location.

name: string

What the venue is called

address: string

Street address for the venue

latitude: string

Address latitude. May be set to 0/null if the venue address couldn't be geocoded

longitude: string

Address longitude. May be set to 0/null if the venue address couldn't be geocoded

notes: string

Additional notes for the caregiver about the venue

Example
{
  "name": "string",
  "address": "string",
  "latitude": "string",
  "longitude": "string",
  "notes": "string"
}

Organization: object

Information about the organization the caregiver is a member of.

id: integer

Unique ID.

name: string

Name.

country: string

ISO country code.

street: string

Street number and name.

suburb: string

Suburb.

city: string

City.

phone: string

Phone number.

created: string

Date/time the organization was created.

Example
{
  "id": "integer",
  "name": "string",
  "country": "string",
  "street": "string",
  "suburb": "string",
  "city": "string",
  "phone": "string",
  "created": "string"
}

Student: object

Student assigned to the current caregiver by their school.

Schools upload a list of students to Fieldtriq so they can be added to events. From there, they can be assigned to one or multiple caregivers so they can manage their events, either through the web app or this API.

Students can be assigned to multiple caregivers by school staff, for instances where caregivers want their own Fieldtriq account. This is not made visible to the caregiver. A caregiver cannot see the other caregivers that have access to their students.

id: integer

Student ID.

organization_id: integer

Organization ID.

first_name: string

Student first name.

last_name: string

Student last name.

preferred_first_name: string

Student's preferred first name. If present, this name should be used for addressing the student.

preferred_last_name: string

Student's preferred last name. If present, this name should be used for addressing the student.

created: string

Date and time the student was created

Example
{
  "id": "integer",
  "organization_id": "integer",
  "first_name": "string",
  "last_name": "string",
  "preferred_first_name": "string",
  "preferred_last_name": "string",
  "created": "string"
}

EventStudent: object

Student for an event with their consent status shown

id: integer

Student ID.

organization_id: integer

Organization ID.

first_name: string

Student first name.

last_name: string

Student last name.

preferred_first_name: string

Student's preferred first name. If present, this name should be used for addressing the student.

preferred_last_name: string

Student's preferred last name. If present, this name should be used for addressing the student.

created: string

Date and time the student was created

consent: Consent
transactions: Transaction
Example
{
  "id": "integer",
  "organization_id": "integer",
  "first_name": "string",
  "last_name": "string",
  "preferred_first_name": "string",
  "preferred_last_name": "string",
  "created": "string",
  "consent": {
    "consent_given": "boolean",
    "user_id": "integer",
    "user_name": "string",
    "submitted_by_staff": "boolean",
    "created": "string"
  },
  "transactions": {
    "id": "integer",
    "amount": "string",
    "created": "string"
  }
}

User: object

A caregiver that has signed up to Fieldtriq in order to manage their child's events.

Caregivers can be associated to multiple organizations, such as if they have children at primary and high school who both use Fieldtriq.

id: integer

Caregiver ID.

first_name: string

Caregiver first name.

last_name: string

Caregiver last name.

email: string

Caregiver email.

home_phone: string

Caregiver phone number.

mobile_phone: string

Caregiver mobile phone number.

created: string

Date and time the caregiver was created.

students: Student

Students belonging to the caregiver.

organizations: Organization

Organizations the caregiver is a member of.

Example
{
  "id": "integer",
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "home_phone": "string",
  "mobile_phone": "string",
  "created": "string",
  "students": [
    {
      "id": "integer",
      "organization_id": "integer",
      "first_name": "string",
      "last_name": "string",
      "preferred_first_name": "string",
      "preferred_last_name": "string",
      "created": "string"
    }
  ],
  "organizations": [
    {
      "id": "integer",
      "name": "string",
      "country": "string",
      "street": "string",
      "suburb": "string",
      "city": "string",
      "phone": "string",
      "created": "string"
    }
  ]
}

Staff: object

A school staff member that is assigned to the event.

All school staff have access to the event in Fieldtriq, however certain staff members can be associated with the event, either as an trip attendee or a trip contact, who'll appear here.

id: integer

Staff ID.

name: string

Staff full name.

email: string

Staff email.

trip_attendee: boolean

True if this staff member is attending the field trip.

trip_contact: boolean

True if this staff member is a designated caregiver contact.

Example
{
  "id": "integer",
  "name": "string",
  "email": "string",
  "trip_attendee": "boolean",
  "trip_contact": "boolean"
}

EventPaymentSettings: object

Information about how caregivers can pay for their child's event.

Caregivers can either pay by:

  • using their credit card.
  • manually paying their school outside of Fieldtriq.

Credit Card

Fieldtriq allows schools to connect a Stripe account to their Fieldtriq account. This allows Fieldtriq to create charges for caregivers under the school's Stripe account, meaning they'll get paid directly into their own bank account.

Manual Payments

Manual payments is where the caregiver will pay the school outside of the Fieldtriq workflow, such as dropping money off into the school office.

Manual payments require a staff member to enter the received amount into Fieldtriq for the caregiver's account to be updated, which can take a few days. Fieldtriq makes this clear to the caregiver, just in case they aren't sure whether their manual payment as been processed.

use_hosted_payments: boolean

Whether the caregiver can pay through Fieldtriq using their credit card.

use_manual_payments: boolean

Whether the parent can manually pay their school outside of Fieldtriq, such as dropping money off into the school office.

manual_payment_instructions: string

The instructions for manually paying for the event.

student_cost: string

The cost of each student to attend this field trip

Example
{
  "use_hosted_payments": "boolean",
  "use_manual_payments": "boolean",
  "manual_payment_instructions": "string",
  "student_cost": "string"
}

Transaction: object

A transaction is the record of money in or money out against a particular student for an event.

The amount will be negative if the transaction represents a refund.

id: integer

Transaction ID

amount: string

The amount the transaction was for. Can be a negative amount if there was a refund.

created: string

Date/time the transaction was created.

Example
{
  "id": "integer",
  "amount": "string",
  "created": "string"
}