API Access

TutorCruncher's API allows you to perform actions available in the standard user interface programmatically.

If you wish to have access to the API, you can sign up for a free trial account.

Once you have completed your signup, or if you are already registered, simply go to your System > Settings > Browse the API to look at the API.

If you have some specific questions on performing functionalities with our API, then get in touch with support@tutorcruncher.com.

Have you tried TutorCruncher Socket Frontend?

Socket Frontend is a quick and easy way of displaying tutor's profiles, as well as allowing clients to select tutors and make enquiries, all through your website. If you feel like you want to do more with Socket, then read on, otherwise you can go to our docs on Socket to set it up.

Getting Started

There are two ways of accessing TutorCruncher's API, either straight to the API, or using TutorCruncher Socket Server.

At the moment there is nothing that can be accessed through the API that can't be accessed with TutorCruncher Socket Server, so we recommend using that.

TutorCruncher Socket Server

How do I get access to TutorCruncher socket?

Try this link.

Getting a list of tutors

If you make a request in the format below, you can get the list of the tutors you have made publically accessible.

https://socket.tutorcruncher.com/{{ YOUR_PUBLIC_API_KEY }}/contractors

If we take our demo branch as an example:

https://socket.tutorcruncher.com/9c79f14df986a1ec693c/contractors

What fields do I get on the list of tutors?

Fields Description Example
distance Used to filter your users by distance to an address/postcode
id The tutor's ID within TutorCruncher 214699
link The link that will be generated for their profile 214699-martha-s
name The tutor's name Martha S
photo A link to the tutor's profile picture https://socket.tutorcruncher.com/media/9c79f14df986a1ec693c/214699.thumb.jpg
primary_description The Custom Field with the name 'Primary Description', or the first custom Field that is of type Text Long, arranged in order of priority I have been a Maths teacher (13+) since I graduated from university and tutor students outside of work. I also have experience in working with students with learning disorders.
tag_line The Custom Field with the name 'Tag Line', or the first custom Field that is of type Short Text, arranged in order of priority Fantastic Maths Tutor available throughout London
town The town the tutor has listed in their address Putney
url A link to more details about that contractor (see below) https://socket.tutorcruncher.com/9c79f14df986a1ec693c/contractors/214699
country The country the tutor has entered in their address United Kingdom

How do I get more details about a tutor (like their teaching skills, other custom Fields etc)?

Going to the url link above will give you more details about the tutor.

For instance https://socket.tutorcruncher.com/9c79f14df986a1ec693c/contractors/214699

Fields Description Example
country The country the tutor has entered in their address United Kingdom
extra_attributes All of the details about custom Fields associated with the contractor that are publicly viewable. [
  {
    "machine_name": "tag-line"
    "name": "Tag Line"
    "sort_index": 0.0
    "type": "text_short"
    "value": "Fantastic Maths Tutor available throughout London"
  }
]
id The tutor's ID within TutorCruncher 214699
name The tutor's name Martha S
photo A link to the tutor's profile picture https://socket.tutorcruncher.com/media/9c79f14df986a1ec693c/214699.jpg
primary_description The Custom Field with the name 'Primary Description', or the first custom Field that is of type Text Long, arranged in order of priority I have been a Maths teacher (13+) since I graduated from university and tutor students outside of work. I also have experience in working with students with learning disorders.
tag_line The Custom Field with the name 'Tag Line', or the first custom Field that is of type Short Text, arranged in order of priority Fantastic Maths Tutor available throughout London
town The town the tutor has listed in their address Putney
skills The skills a tutor has listed on their profiles. [
  {
    "category": "Maths"
    "qual_levels": [
      "11+",
      "13+"
    ],
    "subject": "Mathematics"
  }
]

As you can see above, Custom Fields and Skills are listed with other details relevant to them.

Making an enquiry

You have to use a POST request to submit the form, so we've created an example for you to browse. If you have any questions, let us know.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
  </head>
  <body>
    <form action="#" method="POST">
      <input type="text" id="client_name" name="client_name" placeholder="Name (Required)" required="required" maxlength="255">
      <br><br>
      <input type="email" id="client_email" name="client_email" placeholder="Email" maxlength="255">
      <br><br>
      <input type="text" id="client_phone" name="client_phone" placeholder="Phone number" maxlength="255">
      <br><br>
      <textarea id="attributes-tell-us-about-yourself" attrtype="true" name="attributes-tell-us-about-yourself" placeholder="Tell us about yourself" maxlength="2047" rows="5"></textarea>
      <div class="g-recaptcha" data-sitekey="6LdyXRgUAAAAADUNhMVKJDXiRr6DUN8TGOgllqbt"></div>
      <button type="submit">Submit</button>
    </form>
  </body>
  <script src="https://www.google.com/recaptcha/api.js" async defer></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
  <script>
    $('form').submit(function(e) {
      e.preventDefault()
      var v = grecaptcha.getResponse()
      if (v.length === 0) {
        $('#captcha').html("You can't leave Captcha Code empty")
        return false
      }
      var data = {
        client_name: $('#client_name').val(),
        client_email: $('#client_email').val(),
        client_phone: $('#client_phone').val(),
        grecaptcha_response : v,
        // Make sure any custom Field fields are in a separate object.
        attributes: {
          'attributes-tell-us-about-yourself': $('#attributes-tell-us-about-yourself').val()
        }
      }
      $.ajax({
        type: 'POST',
        url: 'https://socket.tutorcruncher.com/9c79f14df986a1ec693c/enquiry',
        data: JSON.stringify(data),
        dataType: 'json'
      }).done(function() {
        $('form').html('form successfully submitted. Sticky badge for you!')
      })
    })
  </script>
</html>

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.

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