TutorCruncher's API

Using TutorCruncher's API

Our API is currently in development and endpoints are being added all the time. If there is a particular piece of information you would like access to, then let us know.

To help you get started with the API we provide a browsable version of the API which can be accessed via your browser.

To view it go to https://secure.tutorcruncher.com/api/. This root page will provide a list of all API endpoints. By clicking on an endpoint, you can view the available filters.

You may also find it helpful to use Google Chrome's postman extension to make some trial requests to the API.

Where do I find my API key?

You'll need a Private API key for that. Simply go to System > Integrations and add an integration if one does not exist. Please note you need a different one to a Socket integration. Once you've created that, click on it, and copy the Private API Key.

Curl Example

API authentication on TutorCruncher is performed using an HTTP request header including your API token. For example to get a list of appointments for your company you could make a curl request thus:

Request:

$ curl -H "Authorization: token <your API token>" \
 -H "Accept: application/json; indent=2" \
  https://secure.tutorcruncher.com/api/appointments/

(Here the accept header is not required as application/json is default, obviously indent is only added to format the response in this example.)

Response:

{
  "count": 555,
  "next": "https://secure.dinotutors.com/api/appointments/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1482049,
      "start": "2020-12-25T18:30:00Z",
      "finish": "2020-12-25T20:30:00Z",
      "units": "2.00000",
      "topic": "Friday Homework Help",
      "location": {
        "id": 7008,
        "name": "Latimer Room [Downstairs]",
        "description": "",
        "can_conflict": true,
        "role": null,
        "latitude": null,
        "longitude": null,
        "address": null
      },
      "rcras": [
        {
          "recipient": 530989,
          "recipient_name": "Bridget Jones",
          "paying_client": 511336,
          "paying_client_name": "Fionn Finegan",
          "charge_rate": "80.00"
        },
        {
          "recipient": 528437,
          "recipient_name": "Olivia",
          "paying_client": 528436,
          "paying_client_name": "Olivia Odendaal",
          "charge_rate": "80.00"
        },
        {
          "recipient": 511349,
          "recipient_name": "Frodo Junior",
          "paying_client": 511337,
          "paying_client_name": "Baggins",
          "charge_rate": "80.00"
        },
        {
          "recipient": 213373,
          "recipient_name": "Isabelle Clay",
          "paying_client": 213372,
          "paying_client_name": "Anthony Clay",
          "charge_rate": "80.00"
        },
        {
          "recipient": 401483,
          "recipient_name": "franky boyle",
          "paying_client": 401478,
          "paying_client_name": "Samuel Colvin",
          "charge_rate": "80.00"
        }
      ],
      "cjas": [
        {
          "contractor": 213390,
          "contractor_name": "Diana Lafayette",
          "pay_rate": "45.00"
        }
      ],
      "status": "Planned",
      "repeater": {
        "repeat": "Weekly",
        "every": 1,
        "repeat_on": "",
        "stops_on": "2020-12-31",
        "stops_after": 1,
        "source_apt": 1481941
      },
      "service_id": 95569,
      "service_name": "Maths SAT",
      "charge_type": "Hourly"
    },
    {
      "id": 1482048,
      "start": "2020-12-18T18:30:00Z",
      "finish": "2020-12-18T20:30:00Z",
      "units": "2.00000",
      "topic": "Friday Homework Help",
      "location": {
        "id": 7008,
        "name": "Latimer Room [Downstairs]",
        "description": "",
        "can_conflict": true,
        "role": null,
        "latitude": null,
        "longitude": null,
        "address": null
      },
      "rcras": [
        {
          "recipient": 530989,
          "recipient_name": "Bridget Jones",
          "paying_client": 511336,
          "paying_client_name": "Fionn Finegan",
          "charge_rate": "80.00"
        },
        {
          "recipient": 528437,
          "recipient_name": "Olivia (TEST)",
          "paying_client": 528436,
          "paying_client_name": "Olivia Odendaal",
          "charge_rate": "80.00"
        },
        {
          "recipient": 511349,
          "recipient_name": "Frodo Junior",
          "paying_client": 511337,
          "paying_client_name": "Baggins",
          "charge_rate": "80.00"
        },
        {
          "recipient": 213373,
          "recipient_name": "Isabelle Clay",
          "paying_client": 213372,
          "paying_client_name": "Anthony Clay",
          "charge_rate": "80.00"
        },
        {
          "recipient": 401483,
          "recipient_name": "franky boyle",
          "paying_client": 401478,
          "paying_client_name": "Samuel Colvin",
          "charge_rate": "80.00"
        }
      ],
      "cjas": [
        {
          "contractor": 213390,
          "contractor_name": "Diana Lafayette",
          "pay_rate": "45.00"
        }
      ],
      "status": "Planned",
      "repeater": {
        "repeat": "Weekly",
        "every": 1,
        "repeat_on": "",
        "stops_on": "2020-12-31",
        "stops_after": 1,
        "source_apt": 1481941
      },
      "service_id": 95569,
      "service_name": "Maths SAT",
      "charge_type": "Hourly"
    },...

Python Example

You could also make the request in Python:

import json
import requests

api_token = 'xyz123abc'
headers = {
    'Authorization': 'token %s' % api_token
}
r = requests.get('https://secure.dinotutors.com/api/appointments/', headers=headers)
assert r.status_code == 200, r.status_code

print(r.json())
"""
{
  "count": 555,
  "next": "https://secure.dinotutors.com/api/appointments/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1482049,
      ...
"""

Creating roles through the API

Creating roles is done slightly differently - by posting a list of roles to the endpoint of the type of role you wish to create.

Because we record who created a user in TutorCruncher, you need to supply the ID of the admin you wish to record as having created the roles. An admin's ID can be found in the URL of their page in TutorCruncher (People > Administrators > the admin). For instance, if you go to an admin's page and the URL is https://secure.tutorcruncher.com/admins/216289/, the ID would be 216289.

To see the fields that are available to post data for, you can do an OPTIONS request to the role creation endpoint. In this case, https://secure.tutorcruncher.com/api/contractors/.

Below is an example of creating contractors (tutors) in Python:

import json
import requests

data = {
    'user': {
        'first_name': 'Liam',
        'last_name': 'Gallagher',
        'email': 'liamgallagher@oasis.co.uk',
        'mobile': 123456789,
        'phone': 987654321,
        'street': 'Fake street',
        'town': 'Fake town',
    },
    'status': 'approved',
}

api_token = 'xyz123abc'
headers = {
    'Authorization': 'token %s' % api_token
}

r = requests.post('https://secure.tutorcruncher.com/api/contractors/', data=data, headers=headers)
assert r.status_code == 202, r.status_code

print(r.json())
# {'status': 'success', 'id': '12345'}

Statuses for Roles

Below is a list for the statuses used for creating Clients and Tutors.

Role Type Status Description
Client 'live' Clients that are ready to be put onto Jobs.
Client 'prospect' This status is for Clients who are new and signed up recently.
Client 'dormant' This status is for Clients who are no longer in need of your service.
Contractor 'approve' For Contractors who you have approved.
Contractor 'pending' This status is for Contractors who are new and signed up recently.
Contractor 'rejected' Contractors who you have rejected.
Contractor 'dormant' This is for Contractors who have inactive.

The status field is not required for Affiliates and Students.