The TutorCruncher API allows you to access all the information available in your TutorCruncher account. This section of TutorCruncher can be useful if you are looking to get an overview of a large amount of information or are looking to edit/update certain parts of the system quickly.
If you want to find out more about how the TutorCruncher API works and what you can do with it, you can access our detailed API Documentation.
You will also be using this page if you are integrating TutorCruncher with your website via the TutorCruncher Socket.
The TutorCruncher API page can be found via System > Settings > TutorCruncher API > API. Here you can view all of the integrations you have linked up with TutorCruncher, and add a new integration.
An example of an API integrations page.
What are webhooks?
Webhooks are a way for TutorCruncher to push information about events to another app, Zapier for example. A webhook will contain information about the user or Job it relates to.
Webhooks are fired from TutorCruncher every time an action takes place involving a user or a Job. For instance, a webhook would fire when a Tutor is created, or a Client submits an enquiry.
To set up a webhook, use the Add Integration button to open the ‘Add Integration’ panel, where you can add the webhook URL that you wish your webhooks to be fired to.
Where do I view a webhook's logs?
Simply click on an integration’s name from the list to view its webhook logs.
Viewing an integration’s webhook logs.
This page contains the integration’s settings and information alongside a record of every time the webhook fired alongside when it fired and whether or not it was successful. You can use the arrows on a log’s item in the list to expand that log and view its API request and response data.
Here you can also use the Edit button to edit the integration’s settings. If the integration is for TutorCruncher Socket Bookable Lessons, then you can use the Refresh Socket Appointments to refresh all of the Lessons within the socket and regenerate them for your company. This can take some time and can only be done once per day.
How do I verify a webhook’s signature?
We include a signature in the Webhooks header which can be used to verify if the webhook came from TutorCruncher.
Below is an example of how to verify your webhook:
import hashlib
import hmacprivate_key = 'YOUR_PRIVATE_API_KEY'# payload example data
b"""{
"events": [
{
"action": "CHANGED_CONTRACTOR_STATUS",
"verb": "Changed a Tutor\'s status",
"timestamp": "2020-03-10T12:41:52.819342Z",
"actor": {"name": "Billy Holiday", "id": 59, "user_id": 58, "url": ""},
"subject": {
"model": "Tutor",
"url": "http://localhost:8000/api/contractors/54/",
"id": 54,
"user": {
"title": null,
"first_name": "Walter",
"last_name": "Moore",
"email": "walter_moore@testagency.example.com",
"mobile": "07806 402 497",
"phone": null,
"street": "26 Varna Rd",
"state": null,
"town": "Fulham",
"country": "United Kingdom (GB)",
"postcode": "SW6 7LD",
"latitude": "51.4796469999999999",
"longitude": "-0.2082010000000000",
"date_created": "2020-02-19T09:29:19.148949Z",
"timezone": null,
},
"status": "approved",
"charge_via_branch": false,
"default_rate": null,
"qualifications": [],
"skills": [
{"id": 22, "subject": "History", "qual_level": "Key Stage 4"},
{"id": 23, "subject": "Portuguese", "qual_level": "Key Stage 4"},
],
"institutions": [],
"receive_service_notifications": true,
"review_rating": null,
"review_duration": "00:00:00",
"last_updated": "2020-03-10T12:41:52.799386Z",
"calendar_colour": "MediumOrchid",
"labels": [],
"extra_attrs": [
{
"id": 33,
"value": "I have over 20 years of experience teaching physics at City of London University and can help undergraduates prepare for all kinds of exams in physics and mathematics.",
"type": "Long Textbox",
"machine_name": "contractor-exp",
"name": "Teaching Experience",
},
{
"id": 34,
"value": "I am a retired academic teacher and want to keep contact with the job I love albeit in a more limited amounts. In free time I love to go angling with my friends.",
"type": "Long Textbox",
"machine_name": "contractor-bio",
"name": "Bio",
},
],
"work_done_details": {"amount_owed": 97.5, "amount_paid": 1854.9, "total_paid_hours": "2 09:00:00"},
},
}
],
"_request_time": 1583844113,
}"""def webhook_view(request):
payload = request.body
header_signature = request.META['Webhook-Signature'] # Webhook-Signature can be found in the webhooks header
assert hmac.new(private_key.encode(), payload, hashlib.sha256).hexdigest() == header_signature
...
What is Single Sign On?
Single sign on allows our users to log in to other systems using TutorCruncher. An example of this would be signing into other applications using your Google or Facebook credentials.
In our case, you can set a link from TutorCruncher to another system accessible from the menu, which passes arguments to the other system containing the user's information. A working example of this is available at the link below.
What is the API Rate Limit and can I increase it?
The API permits 100 requests per minute to prevent server overload. This limit is fixed and cannot be increased. To avoid exceeding this limit, consider storing API request results locally or implementing retry logic to pause before retrying requests.