Use TutorCruncher's API to access or create information on your TutorCruncher account. To get started with TutorCruncher's API, go to Integrations and add a new integration. This new integration will have a private key, which you will need to access the API.
If you would like to view your data without writing any code, you can go to the Browsable API which can be viewed on your browser.
Currently users are rate limited to 100 API requests per minute so please take this into account when completing bulk operations.
We are continuously adding and improving the API by adding new endpoints and more information for existing endpoints. If there is a particular piece of information you would like access to then let us know.
1
'https://secure.tutorcruncher.com/api/'
To access your TutorCruncher's account information, you'll need to add your private key,
found at Integrations. The private key
must go into your requests header under Authorization
like in the example shown.
1
2
3
4
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
requests.get('...', headers=headers)
Webhooks are a way for TutorCruncher to push information about events to another app, for example, Zapier or your custom-built app.
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 makes an enquiry.
Click here to view a list of all actions in TutorCruncher and what they mean
The webhook contains basic information about the actions such as action (type)
, branch
, verb
, timestamp
, actor
and subject
.The branch
is the id of the associated branch. The actor
is the person who performed the action within TutorCruncher. The subject
is the
item which the action was performed on. For example, creating/editing a Lesson will send a webhook with the
details about that Lesson.
Click here to view an example of the webhook response
Simply add an integration to your TutorCruncher account, System > Settings > Integrations, and add the webhook URL that you wish your webhooks to be fired to.
We have webhook logs so that you can monitor any issues with them. Simply go to your integration to view them.
This is an example of the webhook TutorCruncher sends to the specified URL on your integration.
{
"events": [
{
"action": "CHANGED_CONTRACTOR_STATUS",
"verb": "Changed a Tutor's status",
"timestamp": "2023-04-21T09:43:09.065099Z",
"branch": 17597,
"actor": {
"name": "Sebastian Prentice",
"id": 1865753,
"user_id": 1781627,
"url": ""
},
"subject": {
"model": "Tutor",
"url": "https://secure.tutorcruncher.com/api/contractors/1865751/",
"id": 1865751,
"user": {
"title": null,
"first_name": "Bettie",
"last_name": "Canales",
"email": "bettie_canales@online-olive.example.com",
"mobile": "07037 773 614",
"phone": null,
"street": "104 Robert Street",
"state": null,
"town": "Kings Cross",
"country": "United Kingdom (GB)",
"postcode": "NW1 3QP",
"latitude": "51.5285679999999999",
"longitude": "-0.1405610000000000",
"date_created": "2022-08-31T14:14:20.678562Z",
"timezone": null
},
"status": "pending",
"charge_via_branch": false,
"default_rate": null,
"qualifications": [],
"skills": [
{
"id": 1851,
"subject": "Textiles and Fashion Design",
"qual_level": "International Baccalaureate"
},
{
"id": 345,
"subject": "Theatre Studies",
"qual_level": "International Baccalaureate"
}
],
"institutions": [],
"received_notifications": [
"service_notifications",
"broadcasts",
"apt_reminders",
"apt_marked_complete_reminder"
],
"review_rating": null,
"review_duration": "00:00:00",
"calendar_colour": "Teal",
"labels": [],
"extra_attrs": [
{
"id": 12757955,
"value": "After work I enjoy playing spanish classical and flamenco guitar. I also perform at weddings occasionally.",
"type": "Long Textbox",
"machine_name": "contractor_bio",
"name": "Bio"
},
{
"id": 12757954,
"value": "I was responsible for managing a class of 16 students, ages 7-12, and planning activities that stimulate growth in language, social, and motor skills. Bachelor of Arts in English in 2004",
"type": "Long Textbox",
"machine_name": "contractor_exp",
"name": "Teaching Experience"
}
],
"work_done_details": {
"amount_owed": 804.4,
"amount_paid": 2230,
"total_paid_hours": "2 02:30:00"
}
}
}
],
"_request_time": 1682070189
}
We include a signature in the webhooks header which you can use to verify if the webhook came from TutorCruncher.
1
2
3
4
5
6
7
8
import hashlib, hmac
HMAC_PRIVATE_KEY = 'YOUR_PRIVATE_API_KEY'
def webhook_view(request):
payload = request.body
header_signature = request.META['Webhook-Signature']
assert hmac.new(HMAC_PRIVATE_KEY.encode(), payload, hashlib.sha256).hexdigest() == header_signature
Agents, Clients, Contractors, Recipients all use the user's email address as a unique identifier when creating/updating using the API. If you use the email address when creating/updating, we will check for an email address in the user data and check if this user already exists.
You can create a user without an email address, however, you will not be able to update the user. You must also include the users last name when creating/updating as this field is required. Any other role specific required fields are specified on the endpoint description.
1
2
3
4
5
6
7
8
9
10
11
12
import requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'email': 'billy_bob@example.com',
'last_name': 'Bob'
# ...
},
# ...
}
requests.post('...', json=data, headers=headers)
Many objects in TutorCruncher can be customised with custom fields.
These custom fields are stored in array called extra_attrs
, you can see the shape of a custom field in an
extra_attrs
array in the response on the right.
However, to update a custom field you must not post this whole array. Instead, you should assign
extra_attrs
with an object with keys equal to custom field machine names and values equal to the new values. For
example a valid payload would be:
'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'},
You can find the machine name of a custom field by clicking on it in your custom field settings. See creating a client for an example which sets a custom field for the Client's date of birth.
If you are using dropdown custom fields, you must post the slugified value of the dropdown option.
For example, a value Doesn't suit student
would be posted as doesnt-suit-student
.
What is slugification?
When you convert spaces or repeated dashes to single dashes. Remove characters that aren't alphanumerics, underscores, or hyphens. Convert to lowercase. Also strip leading and trailing whitespace, dashes, and underscores.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'email': 'billy_bob@example.com',
'last_name': 'Bob2',
'extra_attrs': {'client_dob': '1993-06-23'},
# ...
},
# ...
}
r = requests.post('https://secure.tutorcruncher.com/api/clients/', json=data, headers=headers)
pprint.pprint(r.json())
{
"status": "success",
"role": {
"id": 3,
"user": {
"title": "Mr",
"first_name": "Jamie",
"last_name": "Bob2",
"email": "billy_bob@example.com",
// ...
},
// ...
"extra_attrs": [
{
"id": 1,
"value": "1993-06-23",
"type": "Date",
"machine_name": "client-dob",
"name": "Date of birth"
}
],
// ...
}
}
Returns a list of all the different Actions we store when a user or our system performs an act on your account.
When a User logs in.
We do not currently send webhooks for this Action
When a User has requested that they want their data to be deleted.
We do not currently send webhooks for this Action
When a User logs out.
We do not currently send webhooks for this Action
When a User gets sent a password reset email.
We do not currently send webhooks for this Action
When a User resets their password.
We do not currently send webhooks for this Action
When a User switches to a different Role.
We do not currently send webhooks for this Action
When a User opts out from receiving emails.
We do not currently send webhooks for this Action
When an Administrator generates Invoices and Payment Orders.
We do not currently send webhooks for this Action
When an Administrator generates Invoices.
We do not currently send webhooks for this Action
When an Administrator generates Payment Orders.
We do not currently send webhooks for this Action
When an Administrator generates Credit Requests.
We do not currently send webhooks for this Action
Occurs every time an Administrator sends Invoices.
We do not currently send webhooks for this Action
Occurs once for each Invoice when an Administrator sends Invoices.
Webhooks are sent for this Action for the following Subject Types:
Invoice
When an Administrator sends an Invoice Reminder.
Webhooks are sent for this Action for the following Subject Types:
Invoice
When an Administrator sets up a Deferred Payment.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
Invoice
When an Administrator voids an Invoice.
Webhooks are sent for this Action for the following Subject Types:
Invoice
When an Administrator voids a Payment Order.
Webhooks are sent for this Action for the following Subject Types:
Payment Order
When an Invoice gets marked as paid.
Webhooks are sent for this Action for the following Subject Types:
Invoice
When a Client pays their Invoice.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
Invoice
When an Administrator pays an Invoice.
Webhooks are sent for this Action for the following Subject Types:
Invoice
When an Administrator quick pays for an Invoice.
Webhooks are sent for this Action for the following Subject Types:
Invoice
Occurs once for each Credit Request or Invoice when they are charged via Autocharge.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
Invoice
Occurs when an Administrator sends Payment Orders.
We do not currently send webhooks for this Action
Occurs once for each Payment Order when an Administrator sends Payment Orders.
Webhooks are sent for this Action for the following Subject Types:
Payment Order
When an Administrator resends a Payment Order.
Webhooks are sent for this Action for the following Subject Types:
Payment Order
When an Administrator marks a Payment Order as paid.
Webhooks are sent for this Action for the following Subject Types:
Payment Order
Occurs when a Payment Order is sent and creates a payout in Telleroo.
Webhooks are sent for this Action for the following Subject Types:
Payment Order
Occurs when a Payment Order added to a Pay Run.
We do not currently send webhooks for this Action
When an Administrator creates a Credit Request.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
When an Administrator creates a Credit Request Item.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
When an Administrator edits a Credit Request.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
When an Administrator deletes a Credit Request.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
When an Administrator marks a Credit Request as paid.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
Occurs when an Administrator sends Credit Requests.
We do not currently send webhooks for this Action
Occurs once for each Credit Request when an Administrator sends Credit Requests.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
When an Administrator sends a Credit Request Reminder.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
When a Client pays their Credit Request.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
When an Administrator pays a Client's Credit Request.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
When an Administrator creates a Quick Payment Credit Request.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
When an Administrator creates an Ad Hoc Charge.
Webhooks are sent for this Action for the following Subject Types:
Ad Hoc Charge
When an Administrator creates an Ad Hoc Charge.
Webhooks are sent for this Action for the following Subject Types:
Ad Hoc Charge
When an Administrator creates an Ad Hoc Charge.
We do not currently send webhooks for this Action
When an Administrator adjusts a Client's Balance.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Client tops up their Balance.
Webhooks are sent for this Action for the following Subject Types:
Client
When an Administrator exports a Branch's accounting information.
We do not currently send webhooks for this Action
When an Administrator is created.
We do not currently send webhooks for this Action
When an Administrator is edited.
We do not currently send webhooks for this Action
When an Administrator is deleted.
We do not currently send webhooks for this Action
When an Affiliate is created.
Webhooks are sent for this Action for the following Subject Types:
Affiliate
When an Affiliate is edited.
Webhooks are sent for this Action for the following Subject Types:
Affiliate
When an Affiliate is deleted.
Webhooks are sent for this Action for the following Subject Types:
Affiliate
When an Client is created.
Webhooks are sent for this Action for the following Subject Types:
Client
When an Client is edited.
Webhooks are sent for this Action for the following Subject Types:
Client
When an Client is deleted.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Client's status gets updated.
Webhooks are sent for this Action for the following Subject Types:
Client
When an Tutor is created.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When an Tutor is edited.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When an Tutor is deleted.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When a Tutor's status gets updated.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When an Administrator sends a Tutor an invitation for an interview.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When a Student is created.
Webhooks are sent for this Action for the following Subject Types:
Student
When a Student is edited.
Webhooks are sent for this Action for the following Subject Types:
Student
When a Student is deleted.
Webhooks are sent for this Action for the following Subject Types:
Student
When an Administrator imports Users.
We do not currently send webhooks for this Action
When a User's skills are edited.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When a User edits their own skills.
We do not currently send webhooks for this Action
When a User's qualifications are edited.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When a User edits their own qualifications.
We do not currently send webhooks for this Action
When a Job is created.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Job is edited.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Job is deleted.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Job's status is updated.
Webhooks are sent for this Action for the following Subject Types:
Job
When an Administrator sends Job Notifications to Tutors on the Job.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Tutor is added to a Job.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Tutor is removed from a Job.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When a Tutor on a Job is updated.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Tutor is added to a Lesson.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Tutor is removed from a Lesson.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Tutor on a Lesson is updated.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Student is added to a Job.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Student is removed from a Job.
Webhooks are sent for this Action for the following Subject Types:
Student
When a Student on a Job is updated.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Student is added to a Lesson.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Student is removed from a Lesson.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Student on a Lesson is updated.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Tutor applies for a Job.
Webhooks are sent for this Action for the following Subject Types:
Job
Application
When a tutor edits their application for a job
Webhooks are sent for this Action for the following Subject Types:
Application
When a tutor withdraws their application for a job
Webhooks are sent for this Action for the following Subject Types:
Application
When a tutor's application for a job has been declined
Webhooks are sent for this Action for the following Subject Types:
Application
When a tutor's application for a job has been accepted
Webhooks are sent for this Action for the following Subject Types:
Application
When a tutor is requested for a Job by a Client Enquiry
Webhooks are sent for this Action for the following Subject Types:
Application
When a Lesson is created.
Webhooks are sent for this Action for the following Subject Types:
Lesson
Occurs for each Lesson which is created via repeated Lessons.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Lesson is updated.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When repeated Lessons are updated.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Lesson is deleted.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Lesson is marked as complete.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Lesson is cancelled.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When an Administrator exports data about Lessons.
We do not currently send webhooks for this Action
When an Administrator exports data about Jobs.
We do not currently send webhooks for this Action
When an Administrator exports data about Reports.
We do not currently send webhooks for this Action
When an Administrator exports data about Users.
We do not currently send webhooks for this Action
When an Administrator exports data about Clients.
We do not currently send webhooks for this Action
When an Administrator makes changes to a Branch's or Company's settings.
We do not currently send webhooks for this Action
When an Administrator updates the Terms and Conditions.
We do not currently send webhooks for this Action
When a User sets up an Company on TutorCruncher.
We do not currently send webhooks for this Action
When a Company's status is marked as Terminated.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Tutor's availability is updated.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When an Administrator is recovered from the Trash.
We do not currently send webhooks for this Action
When an Affiliate is recovered from the Trash.
Webhooks are sent for this Action for the following Subject Types:
Affiliate
When a Client is recovered from the Trash.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Tutor is recovered from the Trash.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When a Student is recovered from the Trash.
Webhooks are sent for this Action for the following Subject Types:
Student
When a Job is recovered from the Trash.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Lesson is recovered from the Trash.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Custom Field is recovered from the Trash.
We do not currently send webhooks for this Action
When a Location is created.
We do not currently send webhooks for this Action
When a Location is edited.
We do not currently send webhooks for this Action
When a Location is deleted.
We do not currently send webhooks for this Action
When a Label is created.
We do not currently send webhooks for this Action
When a Label is edited.
We do not currently send webhooks for this Action
When a Label is deleted.
We do not currently send webhooks for this Action
When a Label is removed from a Role/User.
We do not currently send webhooks for this Action
When a Custom Field is created.
We do not currently send webhooks for this Action
When a Custom Field is edited.
We do not currently send webhooks for this Action
When a Custom Field is deleted.
We do not currently send webhooks for this Action
When a Custom Field is imported.
We do not currently send webhooks for this Action
When the Custom Field order is changed.
We do not currently send webhooks for this Action
When an Administrator sends a Broadcast.
We do not currently send webhooks for this Action
When an Administrator sends a Broadcast Preview.
We do not currently send webhooks for this Action
When an Administrator creates a Broadcast.
We do not currently send webhooks for this Action
When an Administrator edits a Broadcast.
We do not currently send webhooks for this Action
When an Administrator deletes a Broadcast.
We do not currently send webhooks for this Action
When an Administrator or Tutor uploads a Résumé.
We do not currently send webhooks for this Action
When a Tutor edits their Institutions.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When an Administrator or Tutor adds a Custom Institution.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When an Administrator adds a Note.
Webhooks are sent for this Action for the following Subject Types:
Note
When an Administrator edits a Note.
Webhooks are sent for this Action for the following Subject Types:
Note
When a User uploads a Document.
We do not currently send webhooks for this Action
When a User edits a Document.
We do not currently send webhooks for this Action
When an Administrator uploads a Public Document.
We do not currently send webhooks for this Action
When an Administrator creates a Task.
Webhooks are sent for this Action for the following Subject Types:
Task
When a Client's Affiliate is changed.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Client's Client Manager is changed.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Client is added to an Affiliate.
Webhooks are sent for this Action for the following Subject Types:
Affiliate
When an Administrator edits a Task.
Webhooks are sent for this Action for the following Subject Types:
Task
When a Label is added to a Job.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Label is removed from a Job.
Webhooks are sent for this Action for the following Subject Types:
Job
When a desired Skill is added to a Job.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Report is edited.
Webhooks are sent for this Action for the following Subject Types:
Report
When an Administrator approves a Report.
Webhooks are sent for this Action for the following Subject Types:
Report
When an Administrator approved multiple Reports.
We do not currently send webhooks for this Action
When a Report is created.
Webhooks are sent for this Action for the following Subject Types:
Report
When a Subscription is created.
We do not currently send webhooks for this Action
When a Subscription is edited.
We do not currently send webhooks for this Action
When a Subscription is deleted.
We do not currently send webhooks for this Action
When a Client is added to Subscription.
We do not currently send webhooks for this Action
When a Client is removed from a Subscription.
We do not currently send webhooks for this Action
When a Client makes an Enquiry.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Client requests a Tutor in their enquiry.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When a Client requests a Job in their enquiry.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Tutor signs up to the Branch.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When a Client signs up to the Branch.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Lesson Reminder is added.
We do not currently send webhooks for this Action
When a User clicks a Single Sign On (SSO) link.
We do not currently send webhooks for this Action
When a Card is set as the Default Payment Card.
Webhooks are sent for this Action for the following Subject Types:
Client
When Card Details are removed from a User.
Webhooks are sent for this Action for the following Subject Types:
Client
When Card Details are added to a User.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Client edits their Bank Account Details.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When a Job review is requested automatically.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Client creates a Review.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When an Administrator deletes a Client's Reivew.
We do not currently send webhooks for this Action
When an Administrator moves a Client in the Client Pipeline.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Job Confirmation Email is sent to a Client.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Job Confirmation Email is sent to a Tutor.
Webhooks are sent for this Action for the following Subject Types:
Job
When a Client books a Lesson.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a client cancels a booked Lesson.
Webhooks are sent for this Action for the following Subject Types:
Lesson
When a Deferred Payment is cancelled.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
Invoice
When a Deferred Payment Fails.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
Invoice
When a Payment Fails.
Webhooks are sent for this Action for the following Subject Types:
Credit Request
Invoice
When a Company updates their Billing Plan.
We do not currently send webhooks for this Action
When a Company updates their Support Plan.
We do not currently send webhooks for this Action
When a User switches to a different Branch.
We do not currently send webhooks for this Action
When an Administrator sends his JavaScript to be reviewed.
We do not currently send webhooks for this Action
When a Client is sent their Lesson Schedule.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Company's status is set to In Arrears.
We do not currently send webhooks for this Action
When a Company's Trial expires they will receive an email.
We do not currently send webhooks for this Action
When a Tutor is created through the API.
Webhooks are sent for this Action for the following Subject Types:
Tutor
When a Client is created through the API.
Webhooks are sent for this Action for the following Subject Types:
Client
When a Student is created through the API.
Webhooks are sent for this Action for the following Subject Types:
Student
When a Affiliate is created through the API.
Webhooks are sent for this Action for the following Subject Types:
Affiliate
When an Admin generates a Pay Run export
We do not currently send webhooks for this Action
When someone attempts to login into an account with the wrong password.
We do not currently send webhooks for this Action
When an agency's details have been edited
Webhooks are sent for this Action for the following Subject Types:
Client
When an agency's price plan has been edited
Webhooks are sent for this Action for the following Subject Types:
Client
When someone exports a list of Ad Hoc Charges
We do not currently send webhooks for this Action
When a tutor/branch receives money into their Stripe account
We do not currently send webhooks for this Action
When someone confirms their OTP code over the phone
We do not currently send webhooks for this Action
When someone exports their Stripe bank feed
We do not currently send webhooks for this Action
When a lesson recording has been created.
We do not currently send webhooks for this Action
When a lesson recording has been deleted.
We do not currently send webhooks for this Action
When a package has been created.
Webhooks are sent for this Action for the following Subject Types:
Package
When a package has been edited.
Webhooks are sent for this Action for the following Subject Types:
Package
When a package has been deleted.
Webhooks are sent for this Action for the following Subject Types:
Package
When a client has purchased a package.
Webhooks are sent for this Action for the following Subject Types:
Package
When a client adds new GoCardless details
Webhooks are sent for this Action for the following Subject Types:
Client
When a client or admin removes GoCardless details
Webhooks are sent for this Action for the following Subject Types:
Client
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/action-types/', headers=headers)
pprint.pprint(r.json())
[
{
"key": "AGREE_TERMS",
"value": "AGREE_TERMS",
"msg": "Agreed to Terms and Conditions",
"help_text": "When a User agrees to the Terms and Conditions.",
"subject_types": [
"Tutor",
"Affiliate",
"Client",
"Student"
]
},
...
]
Ad Hoc Charge objects have details of your Ad Hoc Charges including some details about
invoices
and payment_orders
they are linked to in TutorCruncher. Details are also shown
about the category
and appointment
or service
if the Ad Hoc Charge is related to it.
Unique identifier for the object.
Object of the Agent.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Agent's object.
Object of the Appointment.
Unique identifier for the object.
Start date and time for the Appointment.
Finish date and time for the Appointment.
Topic for the Appointment.
The status for the Appointment, the choices are:
10
for Planned15
for Awaiting Report20
for Complete30
for Cancelled40
for Cancelled but ChargeableObject that contains information about the Service. Attributes in the object are id
, name
,
dft_charge_type
, created
, dft_charge_rate
, dft_conractor_rate
, last_updated
, status
, url
.
URL to the Appointment object.
Object of the Ad Hoc Charge Category.
Unique identifier for the object.
Name of the Ad Hoc Charge Category.
Tax setup for the Branch when invoicing.
Force Invoices associated with this Tutor to be charged via branch.
Tax setup for the Contractors when invoicing.
If Contractors can use the category for expenses.
Default charge_client amount for the Ad Hoc Charge Category.
Default description for the Ad Hoc Charge Category.
Default pay_contractor amount for the Ad Hoc Charge Category.
Default net/gross value for the Ad Hoc Charge Category.
Unique identifier for the Ad Hoc Charge Category.
Name for the Ad Hoc Charge Category.
Amount of money in other currency.
Amount of money in the Branch's currency.
Object of the Client.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Client's object.
Object to the Contractor.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Contractor's object.
User who created the Ad Hoc Charge.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
The currency used.
Currency conversion at the time the Ad Hoc Charge was created.
Date and time the Ad Hoc Charge was created.
An array of Invoices the Ad Hoc Charge appears on.
Unique identifier for the object.
The Invoice's display ID.
Date and time the Invoice was sent.
Gross amount for the Invoice.
Net amount for the Invoice.
Tax amount for the Invoice.
Object of the Client on the Invoice. Contains their id
, first_name
, last_name
, email
, and url
.
The status of the Invoice. Check out Invoice Object for the types of statuses.
The URL to the Invoice object.
An array of Payment Orders the Ad Hoc Charge appears on.
Unique identifier for the object.
The Payment Order's display ID.
Gross amount for the Payment Order.
Net amount for the Payment Order.
Tax amount for the Invoice.
Object of the Payee on the Payment Order. Contains their id
, first_name
, last_name
, email
, and url
.
The status of the Payment Order. Check out Payment Order Object for the types of statuses.
Whether the Ad Hoc Charge is net
or gross
.
Amount the Contractor will be paid.
Object of the Service related to the Ad Hoc Charge.
Unique identifier for the object.
Service's name.
Service's default charge type. Check out Service Object for the types of choices.
Date and time the Service was created.
Service's default amount Clients will be charged.
Service's default amount Contractors will be paided.
Status of the Service. Check out Service Object for the types of statuses.
URL to the Service object.
Amount of tax on the Ad Hoc Charge.
{
"id": 32,
"agent": null,
"appointment": null,
"category": {
"branch_tax_setup": "Default Company Tax (20%)",
"charge_via_branch": true,
"contractor_tax_setup": "Default Company Tax (20%)",
"contractor_usable": true,
"default_charge_amount": "10.00",
"default_description": "Fee for registering on the course",
"default_pay_amount": "10.00",
"dft_net_gross": "net",
"id": 7,
"name": "Registration fee"
},
"category_id": 7,
"category_name": "Registration fee",
"charge_client_forex": null,
"client_cost": "25.00",
"client": {
"id": 37,
"first_name": "Nicole",
"last_name": "Beggs",
"email": "nicole_beggs@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/37/"
},
"contractor": null,
"creator": null,
"currency": "GBP",
"currency_conversion": null,
"date_occurred": "2019-12-23T16:11:48.312507Z",
"invoices": [
{
"id": 49,
"display_id": "INV-49",
"date_sent": "2020-01-03T16:11:48.312507Z",
"gross": "1059.95",
"net": 883.29,
"tax": "176.66",
"client": {
"id": 37,
"first_name": "Nicole",
"last_name": "Beggs",
"email": "nicole_beggs@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/37/"
},
"status": "paid",
"url": "https://secure.tutorcruncher.com/api/invoices/49/"
}
],
"payment_orders": [],
"net_gross": "gross",
"pay_contractor": null,
"service": {
"id": 26,
"name": "UK tax law",
"dft_charge_type": "hourly",
"created": "2019-12-19T16:11:48.312507Z",
"dft_charge_rate": "95.00",
"dft_contractor_rate": "30.00",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/26/"
},
"tax_amount": 4.166666666666667
}
Returns a list of your ad hoc charges. The ad hoc charges are sorted by id
, with
the largest id first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/adhoccharges/', headers=headers)
pprint.pprint(r.json())
{
"count": 32,
"next": null,
"previous": null,
"results": [
{
"id": 32,
"description": "Registration fee.",
"date_occurred": "2020-01-01T12:00:00.000000Z",
"category_id": 7,
"category_name": "Registration fee",
"client_cost": "25.00",
"pay_contractor": "20.00",
"agent_percentage": null,
"url": "https://secure.tutorcruncher.com/api/adhoccharges/32/"
},
...
]
}
Returns the details of an existing ah hoc charge. You only need to specify the unique
id
of the ad hoc charge to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/adhoccharges/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 32,
"agent": null,
"appointment": null,
"category": {
"branch_tax_setup": "Default Company Tax (20%)",
"charge_via_branch": true,
"contractor_tax_setup": "Default Company Tax (20%)",
"contractor_usable": true,
"default_charge_amount": "10.00",
"default_description": "Fee for registering on the course",
"default_pay_amount": "10.00",
"dft_net_gross": "net",
"id": 7,
"name": "Registration fee"
},
"category_id": 7,
"category_name": "Registration fee",
"charge_client_forex": null,
"client_cost": "25.00",
"client": {
"id": 37,
"first_name": "Nicole",
"last_name": "Beggs",
"email": "nicole_beggs@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/37/"
},
"contractor": null,
"creator": null,
"currency": "GBP",
"currency_conversion": null,
"date_occurred": "2019-12-23T16:11:48.312507Z",
"invoices": [
{
"id": 49,
"display_id": "INV-49",
"date_sent": "2020-01-03T16:11:48.312507Z",
"gross": "1059.95",
"net": 883.29,
"tax": "176.66",
"client": {
"id": 37,
"first_name": "Nicole",
"last_name": "Beggs",
"email": "nicole_beggs@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/37/"
},
"status": "paid",
"url": "https://secure.tutorcruncher.com/api/invoices/49/"
}
],
"payment_orders": [],
"net_gross": "gross",
"pay_contractor": null,
"service": {
"id": 26,
"name": "UK tax law",
"dft_charge_type": "hourly",
"created": "2019-12-19T16:11:48.312507Z",
"dft_charge_rate": "95.00",
"dft_contractor_rate": "30.00",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/26/"
},
"tax_amount": 4.166666666666667
}
Creating an Ad Hoc Charge can be completed by simply supplying the date_occurred
, category
, description
and either both
charge_client
and client
or pay_contractor
and contractor
.
1
2
3
4
5
6
7
8
9
10
11
12
13
import pprint, requests, datetime
headers = {'Authorization': 'token <API KEY>'}
data = {
'service': 26,
'client': 37,
'charge_client': 25,
'category': 7,
'date_occurred': datetime.datetime(2021, 1, 1),
'description': 'Registration fee'
}
r = requests.post('https://secure.tutorcruncher.com/api/adhoccharges/', data=data, headers=headers)
pprint.pprint(r.json())
{
"id": 32,
"agent": null,
"appointment": null,
"category": {
"branch_tax_setup": "Default Company Tax (20%)",
"charge_via_branch": true,
"contractor_tax_setup": "Default Company Tax (20%)",
"contractor_usable": true,
"default_charge_amount": "10.00",
"default_description": "Fee for registering on the course",
"default_pay_amount": "10.00",
"dft_net_gross": "net",
"id": 7,
"name": "Registration fee"
},
"category_id": 7,
"category_name": "Registration fee",
"charge_client_forex": null,
"client_cost": "25.00",
"client": {
"id": 37,
"first_name": "Nicole",
"last_name": "Beggs",
"email": "nicole_beggs@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/37/"
},
"contractor": null,
"creator": {
"email": "billy_holiday@example.com",
"first_name": "Billy",
"id": 59,
"last_name": "Holiday"
},
"currency": "GBP",
"currency_conversion": null,
"date_occurred": "2021-01-01T00:00:00Z",
"invoices": [],
"payment_orders": [],
"net_gross": "gross",
"pay_contractor": null,
"service": {
"id": 26,
"name": "UK tax law",
"dft_charge_type": "hourly",
"created": "2021-01-01 T16:11:48.312507Z",
"dft_charge_rate": "95.00",
"dft_contractor_rate": "30.00",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/26/"
},
"tax_amount": 4.166666666666667
}
Updating an Ad Hoc Charge can be completed by simply supplying the date_occurred
, category
, description
, any fields to
update and include the id in the url.
1
2
3
4
5
6
7
8
9
10
11
12
13
import pprint, requests, datetime
headers = {'Authorization': 'token <API KEY>'}
data = {
'service': 26,
'client': 37,
'charge_client': 25,
'category': 7,
'date_occurred': datetime.datetime(2021, 1, 1),
'description': 'Registration fee'
}
r = requests.put('https://secure.tutorcruncher.com/api/adhoccharges/<id>/', data=data, headers=headers)
pprint.pprint(r.json())
{
"id": 32,
"agent": null,
"appointment": null,
"category": {
"branch_tax_setup": "Default Company Tax (20%)",
"charge_via_branch": true,
"contractor_tax_setup": "Default Company Tax (20%)",
"contractor_usable": true,
"default_charge_amount": "10.00",
"default_description": "Fee for registering on the course",
"default_pay_amount": "10.00",
"dft_net_gross": "net",
"id": 7,
"name": "Registration fee"
},
"category_id": 7,
"category_name": "Registration fee",
"charge_client_forex": null,
"client_cost": "25.00",
"client": {
"id": 37,
"first_name": "Nicole",
"last_name": "Beggs",
"email": "nicole_beggs@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/37/"
},
"contractor": null,
"creator": {
"email": "billy_holiday@example.com",
"first_name": "Billy",
"id": 59,
"last_name": "Holiday"
},
"currency": "GBP",
"currency_conversion": null,
"date_occurred": "2021-01-01T00:00:00Z",
"invoices": [],
"payment_orders": [],
"net_gross": "gross",
"pay_contractor": null,
"service": {
"id": 26,
"name": "UK tax law",
"dft_charge_type": "hourly",
"created": "2021-01-01 T16:11:48.312507Z",
"dft_charge_rate": "95.00",
"dft_contractor_rate": "30.00",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/26/"
},
"tax_amount": 4.166666666666667
}
Deletes an Ad Hoc Charge and returns the details of an existing ah hoc charge. You only need to specify the unique
id
of the ad hoc charge in the url to achieve this.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.delete('https://secure.tutorcruncher.com/api/adhoccharges/<id>/', headers=headers)
pprint.pprint(r.json())
{
"message": "Successfully deleted Ad Hoc Charge 37: Registration fee"
}
Returns the details of an existing Ah Hoc Charge Category. You only need to send a get request to the Ad Hoc Charge Categories url to get a list of available Categories.
Unique identifier for the object.
Name of the Ad Hoc Charge Category.
Tax setup for the Branch when invoicing.
Force Invoices associated with this Tutor to be charged via branch.
Tax setup for the Contractors when invoicing.
If Contractors can use the category for expenses.
Default charge_client amount for the Ad Hoc Charge Category.
Default description for the Ad Hoc Charge Category.
Default pay_contractor amount for the Ad Hoc Charge Category.
Default net/gross value for the Ad Hoc Charge Category.
{
"branch_tax_setup": "Default Company Tax (20%)",
"charge_via_branch": true,
"contractor_tax_setup": "Default Company Tax (20%)",
"contractor_usable": true,
"default_charge_amount": "10.00",
"default_description": "Fee for registering on the course",
"default_pay_amount": "10.00",
"dft_net_gross": "net",
"id": 7,
"name": "Registration fee"
}
Returns a list of your Ad Hoc Charges Categories. The Ad Hoc Charges Categories are sorted by id
, with
the smallest id first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/ahc-categories/', headers=headers)
pprint.pprint(r.json())
{
"count": 32,
"next": null,
"previous": null,
"results": [
{
"branch_tax_setup": "Default Company Tax (20%)",
"charge_via_branch": true,
"contractor_tax_setup": "Default Company Tax (20%)",
"contractor_usable": true,
"default_charge_amount": "10.00",
"default_description": "Fee for registering on the course",
"default_pay_amount": "10.00",
"dft_net_gross": "net",
"id": 7,
"name": "Registration fee"
},
...
]
}
Agent objects, Affiliates in TutorCruncher, includes basic user information including fields that are only linked to the Agent Role.
It includes details about affiliated Clients, clients
, and their commission_rate
.
Unique identifier for the object.
User object containing basic information.
The user's first name.
The user's last name.
The user's email address.
The user's mobile number.
The user's phone number.
The user's street address.
This field is only needed for US users. This value will use the state's 2-letter code.
The user's town on address.
User's country, value is an id
of the country stored in TutorCruncher. These country ids can be found
by doing an options request at this endpoints base URL.
The user's postcode on address.
The user's addresses latitude.
The user's addresses longitude.
The date and time the user was created.
The user's timezone, accepted values are timezone database values.
Percentage of the Agent's commission rate.
An array of Clients which the Agent is related to.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Agent's object.
The date and time the Agent was last updated.
Use hex values, like #fff000
, or use CSS Named colours.
An array of the Agent's labels.
Unique identifier for the object.
Name of the label.
Unique slugified name of the label.
Custom fields for this object.
Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}
{
"id": 65,
"user": {
"title": null,
"first_name": "Billy",
"last_name": "Holiday",
"email": "billy_holiday@example.com",
"mobile": "07123 456 789",
"phone": "0208 123 4567",
"street": "8 Albert Road",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "E80 1FA",
"latitude": "51.5373258999999990",
"longitude": "-0.1496343000000000",
"date_created": "2020-02-18T16:13:04.193340Z",
"timezone": "Europe/London"
},
"commission_rate": null,
"clients": [],
"last_updated": "2020-03-16T12:23:39.056867Z",
"calendar_colour": "Brown",
"labels": [],
"extra_attrs": []
}
Returns a list of your agents. The agents are sorted by id
, with
the largest id first.
Filter by the date and time the Agent was created.
Filter by the date and time the Agent was created.
Filter by the Agent's first name.
Filter by the Agent's last name.
Filter by the Agent's email address.
Filter by the Agent's status.
Filter by the address.
Filter by the radius of the address. This is used in conjunction with the address
filter.
Filter by the Agent's labels.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/agents/', headers=headers)
pprint.pprint(r.json())
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 65,
"first_name": "Billy",
"last_name": "Holiday",
"email": "billy_holiday@example.com",
"url": "https://secure.tutorcruncher.com/api/agents/65/"
}
]
}
Returns the details of an existing agent. You only need to specify the unique
id
of the Agent to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/agents/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 65,
"user": {
"title": null,
"first_name": "Billy",
"last_name": "Holiday",
"email": "billy_holiday@example.com",
"mobile": "07123 456 789",
"phone": "0208 123 4567",
"street": "8 Albert Road",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "E80 1FA",
"latitude": "51.5373258999999990",
"longitude": "-0.1496343000000000",
"date_created": "2020-02-18T16:13:04.193340Z",
"timezone": "Europe/London"
},
"commission_rate": null,
"clients": [],
"last_updated": "2020-03-16T12:23:39.056867Z",
"calendar_colour": "Brown",
"labels": [],
"extra_attrs": []
}
Creating an Agent can be done by supplying the users information including Agent specific information
like their commission_rate
.
To send a welcome email to the Agent once they have been created, add 'send_emails': True
in the data like in the
example.
Check out Creating/Updating Users for more information on linking to a specific user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'first_name': 'Billy',
'last_name': 'Bob',
'email': 'billy_bob@example.com',
'mobile': '07123456789',
'phone': '02081234567',
'street': '177 South Lambeth Road',
'state': None,
'town': 'London',
'country': 183,
'postcode': 'SW8 1XP',
'latitude': '51.5549',
'longitude': '-0.1084',
'timezone': 'Europe/London',
},
'commission_rate': 10.1,
'calendar_colour': 'LimeGreen',
'extra_attrs': {'user_dob': '1993-06-23'},
'send_emails': True,
}
r = requests.post('https://secure.tutorcruncher.com/api/agents/', json=data, headers=headers)
pprint.pprint(r.json())
{
"status": "success",
"role": {
"id": 65,
"user": {
"title": null,
"first_name": "Billy",
"last_name": "Holiday",
"email": "billy_holiday@example.com",
"mobile": "07123 456 789",
"phone": "0208 123 4567",
"street": "8 Albert Road",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "E80 1FA",
"latitude": "51.5373258999999990",
"longitude": "-0.1496343000000000",
"date_created": "2020-02-18T16:13:04.193340Z",
"timezone": "Europe/London"
},
"commission_rate": null,
"clients": [],
"last_updated": "2020-03-16T12:23:39.056867Z",
"calendar_colour": "Brown",
"labels": [],
"extra_attrs": [
{
"id": 1,
"value": "1993-06-23",
"type": "Date",
"machine_name": "user-dob",
"name": "Date of birth"
}
]
}
}
Update an Agent object by supplying the email address as the unique identifier. You must also supply required fields
like last_name
even if they are not being updated. You only need to post information that you want to change and
not the whole Agent object.
Check out Creating/Updating Users for more information on linking to a specific user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'email': 'billy_bob@example.com',
'last_name': 'Bob2',
# ...
},
'extra_attrs': {'user_dob': '1993-06-23'},
# ...
}
r = requests.post('https://secure.tutorcruncher.com/api/agents/', json=data, headers=headers)
pprint.pprint(r.json())
{
"status": "success",
"role": {
"id": 65,
"user": {
"title": null,
"first_name": "Billy",
"last_name": "Bob2",
"email": "billy_bob@example.com",
"mobile": "07123 456 789",
"phone": "0208 123 4567",
"street": "8 Albert Road",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "E80 1FA",
"latitude": "51.5373258999999990",
"longitude": "-0.1496343000000000",
"date_created": "2020-02-18T16:13:04.193340Z",
"timezone": "Europe/London"
},
"commission_rate": null,
"clients": [],
"last_updated": "2020-03-16T12:23:39.056867Z",
"calendar_colour": "Brown",
"labels": [],
"extra_attrs": [
{
"id": 1,
"value": "1993-06-23",
"type": "Date",
"machine_name": "user-dob",
"name": "Date of birth"
}
]
}
}
Appointment objects, Lessons in TutorCruncher, are the children of the Service object. The API allows you to GET a single Appointment or a list of Appointments.
Unique identifier for the object.
Appointment's start date and time.
Appointment's finish date and time.
If charge type hourly
, units will be the length of the Appointment divided by an hour.
Appointment's topic.
Object of the Appointment's Location.
Unique identifier for the object.
Location's name.
Location's description.
Whether the location can conflict with other Appointment's at similar time.
Unique identifier of the related User to the location.
Location's latitude.
Location's longitude.
Location's full address.
An array of Recipients that are on the Appointment.
Unique identifier of the Recipient.
Name of the recipient.
Unique identifier of the Paying Client for the Recipient.
Name of the Paying Client.
Amount the Client will be charged.
The status of the student for that Appointment. Normally is attended, but can be different for group lessons
where one or more students might have cancelled/not turned up but the Appointment still went ahead. This field
is currently read_only
, and cannot be changed through the API. If you would like this to change, please email
devteam@tutorcruncher.com.
An array of Contractors that are on the Appointment.
Unique identifier of the Contractor.
Name of the Contractor.
Amount the Contractor will be charged.
The status for the Appointment, the status types are planned
, awaiting-report
, complete
, cancelled
,
and cancelled-chargeable
.
Object about the Appointment's repeating appointments.
Type of repeater, types are Daily
or Weekly
.
How often it will repeat lessons, every X days/weeks.
List of days the repeater will add Appointments on.
Date the repeater will stop adding Appointments.
Max amount of Appointments that will be created.
Unique identifier of the Appointment which the repeater is repeating from.
Object that contains information about the Service. Attributes in the object are id
, name
,
dft_charge_type
, created
, dft_charge_rate
, dft_conractor_rate
, last_updated
, status
, url
.
How the Appointment will be charged. Types are Hourly
or One off
.
{
"id": 10,
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T13:00:00Z",
"units": "1.00000",
"topic": "Lesson 1",
"location": null,
"rcras": [
{
"recipient": 23,
"recipient_name": "Archie Hoskins",
"paying_client": 18,
"paying_client_name": "Jamie Hoskins",
"charge_rate": "100.00",
"status": "attended"
}
],
"cjas": [
{
"contractor": 43,
"contractor_name": "Billy Holiday",
"pay_rate": "80.00"
}
],
"status": "Planned",
"repeater": null,
"service": {
"id": 699444,
"name": "test",
"dft_charge_type": "hourly",
"created": "2023-03-15T17:37:46.829300Z",
"dft_charge_rate": "12.00",
"dft_contractor_rate": "21.00",
"last_updated": "2023-03-15T17:38:02.989696Z",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/699444/"
},
"charge_type": "Hourly"
}
Returns a list of your Appointments. The Appointments are sorted by id
, with
the largest id first.
Filter by the date and time the Appointment was started.
Filter by the date and time the Appointment was ended.
Filter by the Appointment's linked Job (id).
Filter by the Appointment's linked Tutor (id).
Filter by the Appointment's recipient email address (id).
Filter by the Appointment's location (id).
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/appointments/', headers=headers)
pprint.pprint(r.json())
{
"count": 34,
"next": "https://secure.tutorcruncher.com/api/appointments/?page=2",
"previous": null,
"results": [
{
"id": 10,
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T13:00:00Z",
"topic": "Lesson 1",
"status": 10,
"service": {
"id": 699444,
"name": "test",
"dft_charge_type": "hourly",
"created": "2023-03-15T17:37:46.829300Z",
"dft_charge_rate": "12.00",
"dft_contractor_rate": "21.00",
"last_updated": "2023-03-15T17:38:02.989696Z",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/699444/"
},
"url": "https://secure.tutorcruncher.com/api/appointments/10/"
},
...
]
}
Returns the details of an existing appointment. You only need to specify the unique
id
of the Appointment to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/appointments/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 10,
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T13:00:00Z",
"units": "1.00000",
"topic": "Lesson 1",
"location": null,
"rcras": [
{
"recipient": 23,
"recipient_name": "Archie Hoskins",
"paying_client": 18,
"paying_client_name": "Jamie Hoskins",
"charge_rate": "100.00",
"status": "attended"
}
],
"cjas": [
{
"contractor": 43,
"contractor_name": "Billy Holiday",
"pay_rate": "80.00"
}
],
"status": "Planned",
"repeater": null,
"service": {
"id": 699444,
"name": "test",
"dft_charge_type": "hourly",
"created": "2023-03-15T17:37:46.829300Z",
"dft_charge_rate": "12.00",
"dft_contractor_rate": "21.00",
"last_updated": "2023-03-15T17:38:02.989696Z",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/699444/"
},
"charge_type": "Hourly"
}
Creating an Appointment can be completed by simply supplying the topic
, start
, finish
, status
and service
.
Currently the status
can only be set to "planned"
. This will then create a basic Appointment on the service with
no Users applied to it. To add users to the Appointment with or without custom charge and pay rates, see example
on how to pass the data.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T14:00:00Z",
"topic": "Lesson 1",
"location": None,
"extra_attrs": {},
"rcras": [
{
"recipient": 23,
"charge_rate": "100.00"
}
],
"cjas": [
{
"contractor": 56,
"pay_rate": "81.00"
}
],
"status": "planned",
"service": 23,
}
r = requests.post('https://secure.tutorcruncher.com/api/appointments/', json=data, headers=headers)
pprint.pprint(r.json())
{
"id": 297,
"topic": "Lesson 1",
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T14:00:00Z",
"cjas": [
{
"contractor": 56,
"name": "Scott Hafley",
"pay_rate": "81.00"
}
],
"location": null,
"rcras": [
{
"recipient": 23,
"recipient_name": "Kelly Linder",
"paying_client": 22,
"paying_client_name": "Carrie Linder",
"charge_rate": "100.00"
}
],
"repeater": null,
"service": 23,
"status": "planned",
"units": "2.00000",
"extra_attrs": {}
}
Updating an Appointment is similar to Creating an Appointment. One major difference is that you cannot add, edit or delete Recipients or Contractors on the Appointment. To do this you must use the endpoints Add/Edit Recipient on Appointment, Remove Recipient from Appointment, Add/Edit Contractor on Appointment or Remove Contractor from Appointment.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T14:00:00Z",
"topic": "Lesson 1",
"location": None,
"extra_attrs": {},
"status": "planned",
"service": 23,
}
r = requests.put('https://secure.tutorcruncher.com/api/appointments/<id>/', json=data, headers=headers)
pprint.pprint(r.json())
{
"id": 297,
"topic": "Lesson 1",
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T14:00:00Z",
"cjas": [
{
"contractor": 56,
"name": "Scott Hafley",
"pay_rate": "81.00"
}
],
"location": null,
"rcras": [
{
"recipient": 23,
"recipient_name": "Kelly Linder",
"paying_client": 22,
"paying_client_name": "Carrie Linder",
"charge_rate": "100.00",
"status": "attended"
}
],
"repeater": null,
"service": 23,
"status": "planned",
"units": "2.00000",
"extra_attrs": {}
}
This endpoint is for existing Planned
Appointments. To add a new Recipient or edit an existing
Recipient's charge_rate
, simply supply the Recipient's ID and the charge_rate
. The charge_rate
is not required and if no value is passed we will use the Service's dft_charge_rate
.
1
2
3
4
5
6
7
8
9
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
"recipient": 23,
"charge_rate": "100.00",
}
r = requests.post('https://secure.tutorcruncher.com/api/appointments/<id>/recipient/add/', json=data, headers=headers)
pprint.pprint(r.json())
{
"id": 10,
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T13:00:00Z",
"units": "1.00000",
"topic": "Lesson 1",
"location": null,
"rcras": [
{
"recipient": 23,
"recipient_name": "Archie Hoskins",
"paying_client": 18,
"paying_client_name": "Jamie Hoskins",
"charge_rate": "100.00",
"status": "attended"
}
],
"cjas": [
{
"contractor": 43,
"contractor_name": "Billy Holiday",
"pay_rate": "80.00"
}
],
"status": "Planned",
"repeater": null,
"service": {
"id": 699444,
"name": "test",
"dft_charge_type": "hourly",
"created": "2023-03-15T17:37:46.829300Z",
"dft_charge_rate": "12.00",
"dft_contractor_rate": "21.00",
"last_updated": "2023-03-15T17:38:02.989696Z",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/699444/"
},
"charge_type": "Hourly"
}
To remove a Recipient from an Appointment simply pass the Recipient's ID in the field recipient
.
1
2
3
4
5
6
7
8
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
"recipient": 23,
}
r = requests.post('https://secure.tutorcruncher.com/api/appointments/<id>/recipient/remove/', json=data, headers=headers)
pprint.pprint(r.json())
{
"id": 10,
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T13:00:00Z",
"units": "1.00000",
"topic": "Lesson 1",
"location": null,
"rcras": [],
"cjas": [
{
"contractor": 43,
"contractor_name": "Billy Holiday",
"pay_rate": "80.00"
}
],
"status": "Planned",
"repeater": null,
"service": {
"id": 699444,
"name": "test",
"dft_charge_type": "hourly",
"created": "2023-03-15T17:37:46.829300Z",
"dft_charge_rate": "12.00",
"dft_contractor_rate": "21.00",
"last_updated": "2023-03-15T17:38:02.989696Z",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/699444/"
},
"charge_type": "Hourly"
}
This endpoint is for existing Planned
Appointments. To add a new Contractor or edit an existing
Contractor's pay_rate
, simply supply the Contractor's ID and the pay_rate
. The pay_rate
is not required and if no value is passed we will use the Service's dft_pay_rate
.
1
2
3
4
5
6
7
8
9
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
"contractor": 43,
"pay_rate": "80.00"
}
r = requests.post('https://secure.tutorcruncher.com/api/appointments/<id>/contractor/add/', json=data, headers=headers)
pprint.pprint(r.json())
{
"id": 10,
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T13:00:00Z",
"units": "1.00000",
"topic": "Lesson 1",
"location": null,
"rcras": [
{
"recipient": 23,
"recipient_name": "Archie Hoskins",
"paying_client": 18,
"paying_client_name": "Jamie Hoskins",
"charge_rate": "100.00"
}
],
"cjas": [
{
"contractor": 43,
"contractor_name": "Billy Holiday",
"pay_rate": "80.00"
}
],
"status": "Planned",
"repeater": null,
"service": {
"id": 699444,
"name": "test",
"dft_charge_type": "hourly",
"created": "2023-03-15T17:37:46.829300Z",
"dft_charge_rate": "12.00",
"dft_contractor_rate": "21.00",
"last_updated": "2023-03-15T17:38:02.989696Z",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/699444/"
},
"charge_type": "Hourly"
}
To remove a Contractor from an Appointment simply pass the Contractor's ID in the field contractor
.
1
2
3
4
5
6
7
8
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
"contractor": 43,
}
r = requests.post('https://secure.tutorcruncher.com/api/appointments/<id>/contractor/remove/', json=data, headers=headers)
pprint.pprint(r.json())
{
"id": 10,
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T13:00:00Z",
"units": "1.00000",
"topic": "Lesson 1",
"location": null,
"rcras": [
{
"recipient": 23,
"recipient_name": "Archie Hoskins",
"paying_client": 18,
"paying_client_name": "Jamie Hoskins",
"charge_rate": "100.00"
}
],
"cjas": [],
"status": "Planned",
"repeater": null,
"service": {
"id": 699444,
"name": "test",
"dft_charge_type": "hourly",
"created": "2023-03-15T17:37:46.829300Z",
"dft_charge_rate": "12.00",
"dft_contractor_rate": "21.00",
"last_updated": "2023-03-15T17:38:02.989696Z",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/699444/"
},
"charge_type": "Hourly"
}
The Branch Object contains information related to a physical location. It includes details such as the id
of the branch, name
of the branch, its agency
information which includes the id
, name
, blurb
, status
, created
, and url_slug
of the agency associated with the branch. The created
field represents the date and time the branch was created. Other fields of the Branch object include country
, currency
, demo
, longitude
, latitude
, page_logo
, phone
, postcode
, street
, timezone
, town
, and website
. These fields provide additional information about the branch location, such as the country, currency used in the branch, whether it's a demo branch or not, its location coordinates, logo, phone number, postcode, street, timezone, town, and website URL.
Unique identifier for the Branch object.
Object of the agency associated with the branch.
Unique identifier for the agency object.
Brief description of the agency.
Date and time when the agency was created.
URL to the agency's login page.
The name of the agency.
Status of the agency, choices are active-paying
, active-not-paying
, archived
, or deleted
.
The URL slug for the agency.
The country where the branch is located.
Date and time when the branch was created.
The currency used in the branch.
Object containing the datetime output formats for the branch.
The date format for display.
Array of Django date formats.
Moment.js date format.
The date format for templates.
The time format for display.
Array of Django time formats.
Moment.js time format.
The time format for templates.
The datetime format for templates.
The short datetime format for templates.
If True
, the day comes before the month in date formats.
The date format for the calendar.
The datetime format for display.
Array of Django datetime formats.
Moment.js datetime format.
The datetime format for display.
If True
, the branch is a demo branch.
The longitude of the branch location.
The latitude of the branch location.
The name of the branch.
The URL of the branch's logo.
The phone number of the branch.
The postcode of the branch.
The street address of the branch.
The timezone of the branch.
The town of the branch.
The website of the branch.
{
"id": 17597,
"agency": {
"id": 9214,
"blurb": "",
"created": "2022-10-19T10:14:20.034536-04:00",
"login_url": "/online-olive/login/",
"name": "online olive",
"status": "active-not-paying",
"url_slug": "online-olive"
},
"country": "United Kingdom",
"created": "2022-10-19T10:14:20.687490-04:00",
"currency": "GBP",
"datetime_output_formats": {
"date_name": "dd/mm/yyyy",
"dj_date": [
"%d/%m/%Y",
"%d/%m/%y",
"%Y-%m-%d"
],
"mt_date": "DD/MM/YYYY",
"tpl_date": "%d/%m/%Y",
"time_name": "HH:MM",
"dj_time": [
"%H:%M",
"%H:%M:%S"
],
"mt_time": "HH:mm",
"tpl_time": "%H:%M",
"tpl_datetime": "%d/%m/%Y %H:%M",
"tpl_datetime_short": "%d/%m %H:%M",
"day_first": true,
"cal_date_display": "ddd DD/MM",
"display_input": "25/7/2014 14:30",
"dj_datetime": [
"%d/%m/%Y %H:%M",
"%d/%m/%Y %H:%M:%S",
"%d/%m/%y %H:%M",
"%d/%m/%y %H:%M:%S",
"%Y-%m-%d %H:%M",
"%Y-%m-%d %H:%M:%S"
],
"mt_datetime": "DD/MM/YYYY HH:mm",
"datetime_name": "dd/mm/yyyy HH:MM"
},
"demo": true,
"longitude": null,
"latitude": null,
"name": "Demo Branch",
"page_logo": null,
"phone": null,
"postcode": "SW1W 0EN",
"street": "Testing House, Demo street",
"timezone": "Europe/London",
"town": "London",
"website": "http://test.test.com"
}
Client objects includes basic user information including fields that are only linked to the
Client Role. For example, students
where the Client is the paying_client
of the student.
Unique identifier for the object.
User object containing basic information.
The user's first name.
The user's last name.
The user's email address.
The user's mobile number.
The user's phone number.
The user's street address.
This field is only needed for US users. This value will use the state's 2-letter code.
The user's town on address.
User's country, value is an id
of the country stored in TutorCruncher. These country ids can be found
by doing an options request at this endpoints base URL.
The user's postcode on address.
The user's addresses latitude.
The user's addresses longitude.
The date and time the user was created.
The user's timezone, accepted values are timezone database values.
The Client's status, choices are prospect
, live
and dormant
.
Whether or not tax should be paid on payments from this Client.
An array of the Client's received notifications. choices are broadcasts
, apt_reminders
, low_balance_reminders
, invoice_reminders
, pfi_reminders
, invoices
, credit_requests
Force Invoices associated with this Tutor to be charged via branch.
The number of invoice related to the Client.
Total amount of pending payments related to the Client.
Whether the Client will be auto charged or not. Choices are 0
to follow the Branch setting, 10
for the Client
to be auto charged and 20
for the Client not to be auto charged.
Object of the Client Manager.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
Object of the set agent.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Agent's object.
PipelineStage of the client if they are a Prosect client.
Unique identifier for the object.
The name of the PipelineStage
The sort index of the PipelineStage (describes the order of the PipelineStages).
An array of recipients related to the Client.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Recipient's object.
Use hex values, like #fff000
, or use CSS Named colours.
An array of the Client's labels.
Unique identifier for the object.
Name of the label.
Unique slugified name of the label.
Custom fields for this object.
Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}
The Client's invoice balance.
The Client's available balance.
{
"id": 3,
"user": {
"title": "Mr",
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@example.com",
"mobile": "0207 1128 953",
"phone": null,
"street": "12 Helmet Row",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "EC1V 3QJ",
"latitude": "51.5249280000000027",
"longitude": "-0.0944689940000000",
"date_created": "2020-01-01T12:00:00.000000Z",
"timezone": null
},
"status": "live",
"is_taxable": true,
"received_notifications": [
"invoice_reminders",
"invoices",
"apt_reminders",
"pfi_reminders",
"credit-requests",
"low_balance_reminders",
"broadcasts"
],
"charge_via_branch": false,
"invoices_count": 4,
"payment_pending": "100.50",
"auto_charge": true,
"associated_admin": {
"id": 2,
"first_name": "Diana",
"last_name": "Lafayette",
"email": "diana_lafayette@example.com"
},
"associated_agent": null,
"pipeline_stage": null,
"paid_recipients": [
{
"id": 4,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "arthur_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/4/"
},
{
"id": 6,
"first_name": "Harry",
"last_name": "Hoskins",
"email": "harry_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/6/"
},
{
"id": 5,
"first_name": "Archie",
"last_name": "Hoskins",
"email": "archie_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/5/"
}
],
"calendar_colour": "ForestGreen",
"labels": [],
"extra_attrs": [
{
"id": 1,
"value": "",
"type": "Date",
"machine_name": "client-dob",
"name": "Date of birth"
}
],
"invoice_balance": "-120.00",
"available_balance": "-220.50"
}
Returns a list of your Clients. The Clients are sorted by id
, with
the largest id first.
Filter by the date and time the Client was created.
Filter by the date and time the Client was created.
Filter by the Client's first name.
Filter by the Client's last name.
Filter by the Client's email address.
Filter by the Client's status.
Filter by the address.
Filter by the radius of the address. This is used in conjunction with the address
filter.
Filter by the Client's labels (id).
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/clients/', headers=headers)
pprint.pprint(r.json())
{
"count": 20,
"next": null,
"previous": null,
"results": [
{
"id": 3,
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/3/"
},
...
]
}
Returns the details of an existing client. You only need to specify the unique
id
of the Client to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/clients/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 3,
"user": {
"title": "Mr",
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@example.com",
"mobile": "0207 1128 953",
"phone": null,
"street": "12 Helmet Row",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "EC1V 3QJ",
"latitude": "51.5249280000000027",
"longitude": "-0.0944689940000000",
"date_created": "2020-01-01T12:00:00.000000Z",
"timezone": null
},
"status": "live",
"is_taxable": true,
"received_notifications": [
"invoice_reminders",
"invoices",
"apt_reminders",
"pfi_reminders",
"credit-requests",
"low_balance_reminders",
"broadcasts"
],
"charge_via_branch": false,
"invoices_count": 4,
"payment_pending": "100.50",
"auto_charge": true,
"associated_admin": {
"id": 2,
"first_name": "Diana",
"last_name": "Lafayette",
"email": "diana_lafayette@example.com"
},
"associated_agent": null,
"pipeline_stage": null,
"paid_recipients": [
{
"id": 4,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "arthur_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/4/"
},
{
"id": 6,
"first_name": "Harry",
"last_name": "Hoskins",
"email": "harry_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/6/"
},
{
"id": 5,
"first_name": "Archie",
"last_name": "Hoskins",
"email": "archie_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/5/"
}
],
"calendar_colour": "ForestGreen",
"labels": [],
"extra_attrs": [
{
"id": 1,
"value": "",
"type": "Date",
"machine_name": "client-dob",
"name": "Date of birth"
}
],
"invoice_balance": "-120.00",
"available_balance": "-220.50"
}
Creating a Client can be done by supplying the users information including Client specific
information like status
, associated_admin
, associated_agent
and branch accounting defaults which can
be overridden.
To send a welcome email to the Client once they have been created, add 'send_emails': True
in the data like in the
example.
Check out Creating/Updating Users for more information on linking to a specific user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'first_name': 'Billy',
'last_name': 'Bob',
'email': 'billy_bob@example.com',
'mobile': '07123456789',
'phone': '02081234567',
'street': '177 South Lambeth Road',
'state': None,
'town': 'London',
'country': 183,
'postcode': 'SW8 1XP',
'latitude': '51.5549',
'longitude': '-0.1084',
'timezone': 'Europe/London',
},
'status': 'live',
'is_taxable': False,
'received_notifications': [
'invoice_reminders',
'invoices',
'apt_reminders',
'pfi_reminders',
'credit-requests',
'low_balance_reminders',
'broadcasts'
],
'change_via_branch': True,
'auto_charge': 0,
'associated_admin': 12,
'associated_agent': 34,
'calendar_colour': 'LimeGreen',
'extra_attrs': {'client_dob': '1993-06-23'},
'send_emails': True,
}
r = requests.post('https://secure.tutorcruncher.com/api/clients/', json=data, headers=headers)
pprint.pprint(r.json())
{
"status": "success",
"role": {
"id": 3,
"user": {
"title": "Mr",
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@example.com",
"mobile": "0207 1128 953",
"phone": null,
"street": "12 Helmet Row",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "EC1V 3QJ",
"latitude": "51.5249280000000027",
"longitude": "-0.0944689940000000",
"date_created": "2020-01-01T12:00:00.000000Z",
"timezone": null
},
"status": "live",
"is_taxable": true,
"received_notifications": [
"invoice_reminders",
"invoices",
"apt_reminders",
"pfi_reminders",
"credit-requests",
"low_balance_reminders",
"broadcasts"
],
"charge_via_branch": false,
"invoices_count": 4,
"payment_pending": "100.50",
"auto_charge": true,
"associated_admin": {
"id": 2,
"first_name": "Diana",
"last_name": "Lafayette",
"email": "diana_lafayette@example.com"
},
"associated_agent": null,
"pipeline_stage": null,
"paid_recipients": [
{
"id": 4,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "arthur_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/4/"
},
{
"id": 6,
"first_name": "Harry",
"last_name": "Hoskins",
"email": "harry_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/6/"
},
{
"id": 5,
"first_name": "Archie",
"last_name": "Hoskins",
"email": "archie_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/5/"
}
],
"last_updated": "2020-01-01T13:00:00.000000Z",
"calendar_colour": "ForestGreen",
"labels": [],
"extra_attrs": [
{
"id": 1,
"value": "1993-06-23",
"type": "Date",
"machine_name": "client-dob",
"name": "Date of birth"
}
],
"invoice_balance": "-120.00",
"available_balance": "-220.50"
}
}
Update a Client object by supplying the email address as the unique identifier. You must also supply required fields
like last_name
even if they are not being updated. You only need to post information that you want to change and
not the whole Client object.
Check out Creating/Updating Users for more information on linking to a specific user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'email': 'billy_bob@example.com',
'last_name': 'Bob2',
# ...
},
'extra_attrs': {'client_dob': '1993-06-23'},
# ...
}
r = requests.post('https://secure.tutorcruncher.com/api/clients/', json=data, headers=headers)
pprint.pprint(r.json())
{
"status": "success",
"role": {
"id": 3,
"user": {
"title": "Mr",
"first_name": "Jamie",
"last_name": "Bob2",
"email": "billy_bob@example.com",
"mobile": "0207 1128 953",
"phone": null,
"street": "12 Helmet Row",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "EC1V 3QJ",
"latitude": "51.5249280000000027",
"longitude": "-0.0944689940000000",
"date_created": "2020-01-01T12:00:00.000000Z",
"timezone": null
},
"status": "live",
"is_taxable": true,
"received_notifications": [
"invoice_reminders",
"invoices",
"apt_reminders",
"pfi_reminders",
"credit-requests",
"low_balance_reminders",
"broadcasts"
],
"charge_via_branch": false,
"invoices_count": 4,
"payment_pending": "100.50",
"auto_charge": true,
"associated_admin": {
"id": 2,
"first_name": "Diana",
"last_name": "Lafayette",
"email": "diana_lafayette@example.com"
},
"associated_agent": null,
"pipeline_stage": null,
"paid_recipients": [
{
"id": 4,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "arthur_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/4/"
},
{
"id": 6,
"first_name": "Harry",
"last_name": "Hoskins",
"email": "harry_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/6/"
},
{
"id": 5,
"first_name": "Archie",
"last_name": "Hoskins",
"email": "archie_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/5/"
}
],
"calendar_colour": "ForestGreen",
"labels": [],
"extra_attrs": [
{
"id": 1,
"value": "1993-06-23",
"type": "Date",
"machine_name": "client-dob",
"name": "Date of birth"
}
],
"invoice_balance": "-120.00",
"available_balance": "-220.50"
}
}
Contractor objects, Tutors in TutorCruncher, includes basic user information including fields that are only linked
to the Contractor Role. For example, subjects and qualifications, under skills
, they have earned.
Unique identifier for the object.
User object containing basic information.
The user's first name.
The user's last name.
The user's email address.
The user's mobile number.
The user's phone number.
The user's street address.
This field is only needed for US users. This value will use the state's 2-letter code.
The user's town on address.
User's country, value is an id
of the country stored in TutorCruncher. These country ids can be found
by doing an options request at this endpoints base URL.
The user's postcode on address.
The user's addresses latitude.
The user's addresses longitude.
The date and time the user was created.
The user's timezone, accepted values are timezone database values.
The Contractor's status, choices are pending
, approved
, rejected
and dormant
.
Force Invoices associated with this Tutor to be charged via branch.
The Contractor's rate which will be used to override service default rates.
An array of the Contractor's qualifications.
Unique identifier for the object.
Name of the institution.
Name of the subject.
Name of the qualification.
The grade for the qualification.
The year for the qualification.
Name of the governing body for the qualification.
An array of the Contractor's skills.
Unique identifier for the object.
Name of the subject.
Name of the qualification.
An array of the Contractor's institutions.
Unique identifier for the object.
Name of the institution.
When checked the Tutor will receive email notifications of Jobs available for application.
Contractor's review rating.
Total amount of time that has been reviewed.
The date and time the Contractor was last updated.
Use hex values, like #fff000
, or use CSS Named colours.
An array of the Contractor's labels.
Unique identifier for the object.
Name of the label.
Unique slugified name of the label.
Custom fields for this object.
Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}
Details about the work the Contractor has done.
The amount of money the Contractor is owed.
The amount of money the Contractor has been paid.
Total amount of time the Contractor has been paid for.
{
"id": 568433,
"user": {
"title": null,
"first_name": "James",
"last_name": "Higgins",
"email": "james_higgins@example.com",
"mobile": "07842 485 204",
"phone": null,
"street": "Royal Lane",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "W1T 4AY",
"latitude": "51.5210000000000008",
"longitude": "-0.1370000000000005",
"date_created": "2018-11-22T09:23:55.297608Z",
"timezone": null
},
"status": "approved",
"charge_via_branch": false,
"default_rate": null,
"qualifications": [],
"skills": [
{
"id": 1436,
"subject": "American Studies",
"qual_level": "Key Stage 5"
},
{
"id": 4082,
"subject": "American Studies",
"qual_level": "A Level"
}
],
"institutions": [],
"receive_service_notifications": true,
"review_rating": null,
"review_duration": "00:00:00",
"last_updated": "2020-04-06T15:36:16.924625+01:00",
"calendar_colour": "#757575",
"labels": [],
"extra_attrs": [],
"work_done_details": {
"amount_owed": 264.49,
"amount_paid": 175.0,
"total_paid_hours": "05:00:00"
}
}
Returns a list of your contractors. The contractors are sorted by id
, with
the largest id first.
Filter by the date and time the Contractor was created.
Filter by the date and time the Contractor was created.
Filter by the Contractor's first name.
Filter by the Contractor's last name.
Filter by the Contractor's email address.
Filter by the Contractor's status.
Filter by the address.
Filter by the radius of the address. This is used in conjunction with the address
filter.
Filter by the Contractor's labels (id).
Filter by the Contractor's skills (id).
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/contractors/', headers=headers)
pprint.pprint(r.json())
{
"count": 20,
"next": null,
"previous": null,
"results": [
{
"id": 47,
"first_name": "James",
"last_name": "Higgins",
"email": "james_higgins@example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/47/"
},
...
]
}
Returns the details of an existing contractor. You only need to specify the unique
id
of the contractor to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/contractors/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 568433,
"user": {
"title": null,
"first_name": "James",
"last_name": "Higgins",
"email": "james_higgins@example.com",
"mobile": "07842 485 204",
"phone": null,
"street": "Royal Lane",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "W1T 4AY",
"latitude": "51.5210000000000008",
"longitude": "-0.1370000000000005",
"date_created": "2018-11-22T09:23:55.297608Z",
"timezone": null
},
"status": "approved",
"charge_via_branch": false,
"default_rate": null,
"qualifications": [],
"skills": [
{
"id": 1436,
"subject": "American Studies",
"qual_level": "Key Stage 5"
},
{
"id": 4082,
"subject": "American Studies",
"qual_level": "A Level"
}
],
"institutions": [],
"receive_service_notifications": true,
"review_rating": null,
"review_duration": "00:00:00",
"last_updated": "2020-04-06T15:36:16.924625+01:00",
"calendar_colour": "#757575",
"labels": [],
"extra_attrs": [],
"work_done_details": {
"amount_owed": 264.49,
"amount_paid": 175.0,
"total_paid_hours": "05:00:00"
}
}
Return a list of times where the contractor is available and when they have an Appointment in a
continuous stream. You need to pass the contractor's unique id
in the URL to get their information.
If the contractor availability object is an appointment
type, that is the times the
contractor has an appointment. If no available
type objects are visible this means the
contractor has said they are not available for those times, or in some cases, they have not
set up their availability on TutorCruncher.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/contractor_availability/<id>/', headers=headers)
pprint.pprint(r.json())
[
{
"type": "available",
"start": "2020-04-07T09:00:00.000000Z",
"finish": "2020-04-07T12:00:00.000000Z",
"apt_id": null
},
{
"type": "appointment",
"start": "2020-04-07T12:00:00.000000Z",
"finish": "2020-04-07T13:30:00.000000Z",
"apt_id": 84
},
{
"type": "appointment",
"start": "2020-04-07T13:30:00.000000Z",
"finish": "2020-04-07T14:30:00.000000Z",
"apt_id": 89
},
{
"type": "available",
"start": "2020-04-07T14:30:00.000000Z",
"finish": "2020-04-07T18:00:00.000000Z",
"apt_id": null
},
{
"type": "available",
"start": "2020-04-08T09:00:00.000000Z",
"finish": "2020-04-08T18:00:00.000000Z",
"apt_id": null
},
...
]
Creating a Contractor can be done by supplying the users information including Contractor specific
information like status
, default_rate
, receive_service_notifications
.
To send a welcome email to the Contractor once they have been created, add 'send_emails': True
in the data like in the
example.
Check out Creating/Updating Users for more information on linking to a specific user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'first_name': 'Billy',
'last_name': 'Bob',
'email': 'billy_bob@example.com',
'mobile': '07123456789',
'phone': '02081234567',
'street': '177 South Lambeth Road',
'state': None,
'town': 'London',
'country': 183,
'postcode': 'SW8 1XP',
'latitude': '51.5549',
'longitude': '-0.1084',
'timezone': 'Europe/London',
},
'status': 'live',
'change_via_branch': True,
'default_rate': 80.0,
'receive_service_notifications': True,
'calendar_colour': 'LimeGreen',
'extra_attrs': {'user_dob': '1993-06-23'},
'send_emails': True,
}
r = requests.post('https://secure.tutorcruncher.com/api/contractors/', json=data, headers=headers)
pprint.pprint(r.json())
{
"status": "success",
"role": {
"id": 568433,
"user": {
"title": null,
"first_name": "James",
"last_name": "Higgins",
"email": "james_higgins@example.com",
"mobile": "07842 485 204",
"phone": null,
"street": "Royal Lane",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "W1T 4AY",
"latitude": "51.5210000000000008",
"longitude": "-0.1370000000000005",
"date_created": "2018-11-22T09:23:55.297608Z",
"timezone": null
},
"status": "approved",
"charge_via_branch": false,
"default_rate": null,
"qualifications": [],
"skills": [
{
"id": 1436,
"subject": "American Studies",
"qual_level": "Key Stage 5"
},
{
"id": 4082,
"subject": "American Studies",
"qual_level": "A Level"
}
],
"institutions": [],
"receive_service_notifications": true,
"review_rating": null,
"review_duration": "00:00:00",
"last_updated": "2020-04-06T15:36:16.924625+01:00",
"calendar_colour": "#757575",
"labels": [],
"extra_attrs": [
{
"id": 1,
"value": "1993-06-23",
"type": "Date",
"machine_name": "user-dob",
"name": "Date of birth"
}
],
"work_done_details": {
"amount_owed": 264.49,
"amount_paid": 175.0,
"total_paid_hours": "05:00:00"
}
}
}
Update a Contractor object by supplying the email address as the unique identifier. You must also supply required fields
like last_name
even if they are not being updated. You only need to post information that you want to change and
not the whole Contractor object.
Check out Creating/Updating Users for more information on linking to a specific user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'email': 'billy_bob@example.com',
'last_name': 'Bob2',
# ...
},
'extra_attrs': {'user_dob': '1993-06-23'}
# ...
}
r = requests.post('https://secure.tutorcruncher.com/api/contractors/', json=data, headers=headers)
pprint.pprint(r.json())
{
"status": "success",
"role": {
"id": 568433,
"user": {
"title": null,
"first_name": "James",
"last_name": "Bob2",
"email": "billy_bob@example.com",
"mobile": "07842 485 204",
"phone": null,
"street": "Royal Lane",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "W1T 4AY",
"latitude": "51.5210000000000008",
"longitude": "-0.1370000000000005",
"date_created": "2018-11-22T09:23:55.297608Z",
"timezone": null
},
"status": "approved",
"charge_via_branch": false,
"default_rate": null,
"qualifications": [],
"skills": [
{
"id": 1436,
"subject": "American Studies",
"qual_level": "Key Stage 5"
},
{
"id": 4082,
"subject": "American Studies",
"qual_level": "A Level"
}
],
"institutions": [],
"receive_service_notifications": true,
"review_rating": null,
"review_duration": "00:00:00",
"last_updated": "2020-04-06T15:36:16.924625+01:00",
"calendar_colour": "#757575",
"labels": [],
"extra_attrs": [
{
"id": 1,
"value": "1993-06-23",
"type": "Date",
"machine_name": "user-dob",
"name": "Date of birth"
}
],
"work_done_details": {
"amount_owed": 264.49,
"amount_paid": 175.0,
"total_paid_hours": "05:00:00"
}
}
}
The country object id is used, when creating and updating the user model. The country object is used to define the country of the user.
Unique identifier for the object.
The name of the country.
The abbreviation of the country.
The three-letter ISO code for the country.
The currency used in the country; e.g Pounds Sterling (£).
The URL of the country's object.
{
"id": 183,
"name": "United Kingdom",
"abbreviation": "GB",
"three_letter_iso": "GBR",
"currency": "Pounds Sterling (£)"
}
Returns a list of your countries. The countries are sorted by name, alphabetically.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/countries/', headers=headers)
pprint.pprint(r.json())
{
"count": 4,
"next": null,
"previous": null,
"results": [
{
"id": 3,
"name": "Afghanistan",
"url": "http://localhost:8000/api/countries/3/"
},
{
"id": 5,
"name": "Albania",
"url": "http://localhost:8000/api/countries/5/"
},
{
"id": 48,
"name": "Algeria",
"url": "http://localhost:8000/api/countries/48/"
},
{
"id": 1,
"name": "Andorra",
"url": "http://localhost:8000/api/countries/1/"
},
{
"id": 7,
"name": "Angola",
"url": "http://localhost:8000/api/countries/7/"
}
]
}
Returns the details of an existing country. You only need to specify the unique id
of the Country to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/countries/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 183,
"name": "United Kingdom",
"abbreviation": "GB",
"three_letter_iso": "GBR",
"currency": "Pounds Sterling (£)"
}
Creating an Enquiry can be useful if you want to use a custom enquiry form on your
website. Creating an Enquiry also creates a Client and Student like the Socket Enquiry Form,
where the Client has the Enquiry label attached to them. The returned response is the id
of
the Enquiry you have just created.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'client_name': 'Joe Blog',
'client_email': 'joe_blog@example.com',
'client_phone': '07123456789',
'service_recipient_name': 'Billy Blog',
'attributes': {
'custom-field-1': 'Some text can go here',
},
'contractor': 568503,
'subject': 16384,
'qual_level': 109721,
'terms_and_conditions': True,
}
r = requests.post('https://secure.tutorcruncher.com/api/enquiry/', json=data, headers=headers)
pprint.pprint(r.json())
{
"id": 21132
}
Invoice objects provide all the details of a TutorCruncher Invoice including the related
appointments
, adhoc_charges
and the paying_client
for the Invoice.
Unique identifier for the object.
An array of different charges related to the invoice.
Object that contains information about the Ad Hoc Charge. Attributes in the object are id
, description
,
date_occurred
, category_id
, category_name
, client_cost
, pay_contractor
, agent_percentage
, and
url
.
Amount of the charge.
Object that contains information about the Appointment. Attributes in the object are id
, start
, finish
,
topic
, status
, url
, it also contains a service
object.
Date and time the charge occured.
Name of who will recieve the charge amount.
Object of the Client who will pay invoice. Attributes in the object are id
, first_name
, last_name
,
email
, and url
.
The rate used to calculate the charge amount.
The sales code used for this charge.
The amount of tax for this charge.
Amount of units used to calculate the charge amount.
Object of the Client on the Invoice.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Client's object.
Date and time the Invoice was sent to the Client.
Date and time the Invoice was marked as void.
Date and time the Invoice was marked as paid.
Invoice's unique display name.
Invoice's gross amount.
Invoice's net amount.
Invoice's status. Choice's are draft
, confirmed
, unpaid
, payment-pending
, paid
, failed
, and void
.
Amount of the Invoice that still needs to be payed.
Invoice's tax amount.
{
"id": 48,
"charges": [
{
"adhoc_charge": {
"id": 30,
"description": "Book and practical exercises (electronics), tests and components for lab experiments.",
"date_occurred": "2019-12-25T16:11:48.312507Z",
"category_id": 7,
"category_name": "Registration fee",
"client_cost": "55.90",
"pay_contractor": null,
"agent_percentage": null,
"url": "https://secure.tutorcruncher.com/api/adhoccharges/30/"
},
"amount": "55.90000",
"appointment": null,
"date": "2019-12-25T16:11:48.312507Z",
"payee": "Demo Branch",
"payer": {
"id": 35,
"first_name": "Melissa",
"last_name": "Spencer",
"email": "melissa_spencer@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/35/"
},
"rate": "55.90000",
"sales_code": "200",
"tax_amount": "9.31667",
"units": "1.00000"
},
{
"adhoc_charge": null,
"amount": "142.50000",
"appointment": {
"id": 251,
"start": "2019-12-31T12:00:33.173982Z",
"finish": "2019-12-31T13:30:33.173982Z",
"topic": "Microelectronics and application of semiconductors 2",
"status": 20,
"service": {
"id": 699444,
"name": "test",
"dft_charge_type": "hourly",
"created": "2023-03-15T17:37:46.829300Z",
"dft_charge_rate": "12.00",
"dft_contractor_rate": "21.00",
"last_updated": "2023-03-15T17:38:02.989696Z",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/699444/"
},
"url": "https://secure.tutorcruncher.com/api/appointments/251/"
},
"date": "2019-12-31T13:30:33.173982Z",
"payee": "Demo Branch",
"payer": {
"id": 35,
"first_name": "Melissa",
"last_name": "Spencer",
"email": "melissa_spencer@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/35/"
},
"rate": "95.00000",
"sales_code": "200",
"tax_amount": "23.75000",
"units": "1.50000"
},
{
"adhoc_charge": null,
"amount": "142.50000",
"appointment": {
"id": 250,
"start": "2019-12-24T12:00:33.173982Z",
"finish": "2019-12-24T13:30:33.173982Z",
"topic": "Microelectronics and application of semiconductors 1",
"status": 20,
"service": {
"id": 699444,
"name": "test",
"dft_charge_type": "hourly",
"created": "2023-03-15T17:37:46.829300Z",
"dft_charge_rate": "12.00",
"dft_contractor_rate": "21.00",
"last_updated": "2023-03-15T17:38:02.989696Z",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/699444/"
},
"url": "https://secure.tutorcruncher.com/api/appointments/250/"
},
"date": "2019-12-24T13:30:33.173982Z",
"payee": "Demo Branch",
"payer": {
"id": 35,
"first_name": "Melissa",
"last_name": "Spencer",
"email": "melissa_spencer@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/35/"
},
"rate": "95.00000",
"sales_code": "200",
"tax_amount": "23.75000",
"units": "1.50000"
}
],
"client": {
"id": 35,
"first_name": "Melissa",
"last_name": "Spencer",
"email": "melissa_spencer@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/35/"
},
"date_sent": "2020-01-03T16:11:48.312507Z",
"date_void": null,
"date_paid": "2020-02-03T16:11:48.312507Z",
"display_id": "INV-48",
"gross": "340.90",
"net": 284.08,
"status": "paid",
"still_to_pay": 0.0,
"tax": "56.82"
}
Returns a list of your Invoices. The Invoices are sorted by date_sent
,
with the most recently sent first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/invoices/', headers=headers)
pprint.pprint(r.json())
{
"count": 34,
"next": "https://secure.tutorcruncher.com/api/invoices/?page=2",
"previous": null,
"results": [
{
"id": 22,
"display_id": "INV-2",
"gross": "100.00",
"net": 92.5,
"tax": "7.50",
"date_sent": "2020-01-01T00:00:00Z",
"client": {
"id": 52,
"first_name": "Jane",
"last_name": "cli_a",
"email": "testing+cli_a@tutorcruncher.com",
"url": "https://secure.tutorcruncher.com/api/clients/52/"
},
"status": "unpaid",
"url": "https://secure.tutorcruncher.com/api/invoices/22/"
},
...
]
}
Returns the details of an existing Invoice. You only need to specify the unique
id
of the Invoice to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/invoices/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 48,
"charges": [
{
"adhoc_charge": {
"id": 30,
"description": "Book and practical exercises (electronics), tests and components for lab experiments.",
"date_occurred": "2019-12-25T16:11:48.312507Z",
"category_id": 7,
"category_name": "Registration fee",
"client_cost": "55.90",
"pay_contractor": null,
"agent_percentage": null,
"url": "https://secure.tutorcruncher.com/api/adhoccharges/30/"
},
"amount": "55.90000",
"appointment": null,
"date": "2019-12-25T16:11:48.312507Z",
"payee": "Demo Branch",
"payer": {
"id": 35,
"first_name": "Melissa",
"last_name": "Spencer",
"email": "melissa_spencer@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/35/"
},
"rate": "55.90000",
"sales_code": "200",
"tax_amount": "9.31667",
"units": "1.00000"
},
{
"adhoc_charge": null,
"amount": "142.50000",
"appointment": {
"id": 251,
"start": "2019-12-31T12:00:33.173982Z",
"finish": "2019-12-31T13:30:33.173982Z",
"topic": "Microelectronics and application of semiconductors 2",
"status": 20,
"service": {
"id": 699444,
"name": "test",
"dft_charge_type": "hourly",
"created": "2023-03-15T17:37:46.829300Z",
"dft_charge_rate": "12.00",
"dft_contractor_rate": "21.00",
"last_updated": "2023-03-15T17:38:02.989696Z",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/699444/"
},
"url": "https://secure.tutorcruncher.com/api/appointments/251/"
},
"date": "2019-12-31T13:30:33.173982Z",
"payee": "Demo Branch",
"payer": {
"id": 35,
"first_name": "Melissa",
"last_name": "Spencer",
"email": "melissa_spencer@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/35/"
},
"rate": "95.00000",
"sales_code": "200",
"tax_amount": "23.75000",
"units": "1.50000"
},
{
"adhoc_charge": null,
"amount": "142.50000",
"appointment": {
"id": 250,
"start": "2019-12-24T12:00:33.173982Z",
"finish": "2019-12-24T13:30:33.173982Z",
"topic": "Microelectronics and application of semiconductors 1",
"status": 20,
"service": {
"id": 699444,
"name": "test",
"dft_charge_type": "hourly",
"created": "2023-03-15T17:37:46.829300Z",
"dft_charge_rate": "12.00",
"dft_contractor_rate": "21.00",
"last_updated": "2023-03-15T17:38:02.989696Z",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/699444/"
},
"url": "https://secure.tutorcruncher.com/api/appointments/250/"
},
"date": "2019-12-24T13:30:33.173982Z",
"payee": "Demo Branch",
"payer": {
"id": 35,
"first_name": "Melissa",
"last_name": "Spencer",
"email": "melissa_spencer@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/35/"
},
"rate": "95.00000",
"sales_code": "200",
"tax_amount": "23.75000",
"units": "1.50000"
}
],
"client": {
"id": 35,
"first_name": "Melissa",
"last_name": "Spencer",
"email": "melissa_spencer@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/35/"
},
"date_sent": "2020-01-03T16:11:48.312507Z",
"date_void": null,
"date_paid": "2020-02-03T16:11:48.312507Z",
"display_id": "INV-48",
"gross": "340.90",
"net": 284.08,
"status": "paid",
"still_to_pay": 0.0,
"tax": "56.82"
}
Pay partially or pay in full, post how much the Client paid towards the Invoice and we'll return how much there is
still_to_pay
. If fully paid off, paid
will return a value of true
. Any excess will be set in the Client's
Available Balance on their TutorCruncher profile.
1
2
3
4
5
6
7
8
9
10
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'amount': 100.0,
'method': 'cash',
'send_receipt': True,
}
r = requests.post('https://secure.tutorcruncher.com/api/invoices/<id>/take_payment/', json=data, headers=headers)
pprint.pprint(r.json())
{
"receipt_sent": true,
"amount_paid": "100.00",
"still_to_pay": "185.00",
"message": "Payment successfully created",
"paid": false
}
Label objects are used to categorise and group objects in TutorCruncher. They are used to group Administrators, Tutors, Affiliates, Clients, Students and Jobs.
Unique identifier for the object.
The name of the label.
Unique slugified name of the label.
The colour of the label.
The role types the label is applicable to.
The email recipients for the label.
Whether the label is editable by contractors.
URL to the label's object.
{
"id": 42,
"name": "External",
"machine_name": "external",
"colour": "MediumBlue",
"applicable_role_types": [
"client",
"service"
],
"email_recipients": [
{
"id": 2,
"first_name": "Diana",
"last_name": "Lafayette",
"email": "diana_lafayette@testagency.example.com"
},
{
"id": 59,
"first_name": "Billy",
"last_name": "Holiday",
"email": "testing+owner@tutorcruncher.com"
}
],
"contractor_editable": true,
"url": "http://localhost:8000/api/labels/42/"
}
Returns a list of your labels. The labels are sorted by id, with the largest id
first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/labels/', headers=headers)
pprint.pprint(r.json())
{
"count": 4,
"next": null,
"previous": null,
"results": [
{
"id": 26,
"name": "Public Job",
"machine_name": "public-job",
"url": "https://secure.tutorcruncher.com/api/labels/26/"
},
{
"id": 25,
"name": "Public Profile",
"machine_name": "public-profile",
"url": "https://secure.tutorcruncher.com/api/labels/25/"
},
{
"id": 24,
"name": "Invited for Interview",
"machine_name": "invited-for-interview",
"url": "https://secure.tutorcruncher.com/api/labels/24/"
},
{
"id": 23,
"name": "Job Finished",
"machine_name": "service-finished",
"url": "https://secure.tutorcruncher.com/api/labels/23/"
}
]
}
Returns the details of an existing label. You only need to specify the unique id
of the Label to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/labels/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 42,
"name": "External",
"machine_name": "external",
"colour": "MediumBlue",
"applicable_role_types": [
"client",
"service"
],
"email_recipients": [
{
"id": 2,
"first_name": "Diana",
"last_name": "Lafayette",
"email": "diana_lafayette@testagency.example.com"
},
{
"id": 59,
"first_name": "Billy",
"last_name": "Holiday",
"email": "testing+owner@tutorcruncher.com"
}
],
"contractor_editable": true,
"url": "http://localhost:8000/api/labels/42/"
}
Notes can be attached to Clients, Tutors, Agents (Affiliates), Students, Services and Appointments.
Unique identifier for the object.
The date the Note was created.
The date the Note was last updated.
The creator of the Note.
The ID of the note creator.
The first name of the note creator.
The last name of the note creator.
The email address of the note creator.
The text of the Note.
Details about the object the Note was added to.
{
"id": 1,
"dt_created": "2023-08-16T15:40:18.922862Z",
"dt_updated": "2023-08-16T15:40:18.922874Z",
"creator": {
"id": 2,
"first_name": "Diana",
"last_name": "Lafayette",
"email": "diana_lafayette@testagency.example.com"
},
"text": "This is a test note.",
"focus": {
"id": 62,
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@testagency.example.com",
"url": "http://localhost:8000/api/clients/62/"
}
}
Returns a list of all your Notes. The notes are sorted by id, with the largest id
first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/notes/', headers=headers)
pprint.pprint(r.json())
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": 3,
"dt_created": "2023-08-16T16:05:54.465325Z",
"dt_updated": "2023-08-16T16:05:54.465348Z",
"creator": 2,
"text": "This note is on an appointment.",
"url": "http://localhost:8000/api/notes/3/"
},
{
"id": 2,
"dt_created": "2023-08-16T16:05:37.596813Z",
"dt_updated": "2023-08-16T16:05:37.596842Z",
"creator": 2,
"text": "This is a note on a job.",
"url": "http://localhost:8000/api/notes/2/"
},
{
"id": 1,
"dt_created": "2023-08-16T15:40:18.922862Z",
"dt_updated": "2023-08-16T15:40:18.922874Z",
"creator": 2,
"text": "* test",
"url": "http://localhost:8000/api/notes/1/"
}
]
}
Returns the details of an existing Note. You only need to specify the unique id
of the Note to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/notes/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 1,
"dt_created": "2023-08-16T15:40:18.922862Z",
"dt_updated": "2023-08-16T15:40:18.922874Z",
"creator": {
"id": 2,
"first_name": "Diana",
"last_name": "Lafayette",
"email": "diana_lafayette@testagency.example.com"
},
"text": "This is a test note.",
"focus": {
"id": 62,
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@testagency.example.com",
"url": "http://localhost:8000/api/clients/62/"
}
}
Payment Order objects provide all the details of a TutorCruncher Payment Order including the related
appointments
, adhoc_charges
and the paying_client
for the Payment Order.
Unique identifier for the object.
An array of different charges related to the payment order.
Object that contains information about the Ad Hoc Charge. Attributes in the object are id
, description
,
date_occurred
, category_id
, category_name
, client_cost
, pay_contractor
, agent_percentage
, and
url
.
Amount of the charge.
Object that contains information about the Appointment. Attributes in the object are id
, start
, finish
,
topic
, status
, url
and service
object.
Date and time the charge occured.
Object of the Contractor/Agent who will get paid. Attributes in the object are id
, first_name
, last_name
,
email
, and url
.
Name of the branch that will be paying the invoice
The rate used to calculate the charge amount.
The sales code used for this charge.
The amount of tax for this charge.
Amount of units used to calculate the charge amount.
Object of the Contractor/Agent on the Payment Order.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Contractor/Agent's object.
Date and time the Payment Order was sent to the Contractor/Agent.
Date and time the Payment Order was marked as void.
Date and time the Payment Order was marked as paid.
Payment Order's unique display name.
Payment Order's amount.
Payment Order's status. Choice's are draft
, confirmed
, unpaid
, payment-pending
, paid
, failed
, and void
.
Amount of the Payment Order that still needs to be payed.
Payment Order's tax amount.
{
"id": 4985119,
"amount": "225.00",
"charges": [
{
"adhoc_charge": null,
"amount": "45.00000",
"appointment": {
"id": 8255569,
"start": "2022-09-17T18:00:47.967724+01:00",
"finish": "2022-09-17T19:30:47.967724+01:00",
"topic": "Programming patterns, algorithms and data structures 4",
"status": "complete",
"service": {
"id": 604713,
"name": "Theory of computer programming",
"dft_charge_type": "hourly",
"created": "2022-08-20T15:14:20.678562+01:00",
"dft_charge_rate": "95.00",
"dft_contractor_rate": "30.00",
"last_updated": "2022-10-19T15:14:43.607845+01:00",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/604713/"
},
"url": "https://secure.tutorcruncher.com/api/appointments/8255569/"
},
"date": "2022-09-17T19:30:47.967724+01:00",
"payee": {
"id": 1865751,
"first_name": "Bettie",
"last_name": "Canales",
"email": "bettie_canales@online-olive.example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/1865751/"
},
"payer": "Demo Branch",
"rate": "30.00000",
"sales_code": "325",
"tax_amount": "0.00000",
"units": "1.50000"
}
],
"date_sent": "2022-10-19T15:15:36.488105+01:00",
"date_void": null,
"date_paid": null,
"display_id": "PO-46",
"status": "unpaid",
"payee": {
"id": 1865751,
"first_name": "Bettie",
"last_name": "Canales",
"email": "bettie_canales@online-olive.example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/1865751/"
},
"still_to_pay": 225.0
}
Returns a list of your Payment Orders. The Payment Orders are sorted by date_sent
,
with the most recently sent first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/payment-orders/', headers=headers)
pprint.pprint(r.json())
{
"count": 34,
"next": "https://secure.tutorcruncher.com/api/payment-orders/?page=2",
"previous": null,
"results": [
{
"id": 22,
"display_id": "PO-2",
"amount": "55.00",
"date_sent": "2020-01-01T00:00:00Z",
"payee": {
"id": 68,
"first_name": "Jane",
"last_name": "con_a",
"email": "jane_con_a@example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/68/"
},
"status": "unpaid",
"url": "https://secure.tutorcruncher.com/api/payment-orders/22/"
},
...
]
}
Returns the details of an existing Payment Order. You only need to specify the unique
id
of the Payment Order to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/payment-orders/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 4985119,
"amount": "225.00",
"charges": [
{
"adhoc_charge": null,
"amount": "45.00000",
"appointment": {
"id": 8255569,
"start": "2022-09-17T18:00:47.967724+01:00",
"finish": "2022-09-17T19:30:47.967724+01:00",
"topic": "Programming patterns, algorithms and data structures 4",
"status": "complete",
"service": {
"id": 604713,
"name": "Theory of computer programming",
"dft_charge_type": "hourly",
"created": "2022-08-20T15:14:20.678562+01:00",
"dft_charge_rate": "95.00",
"dft_contractor_rate": "30.00",
"last_updated": "2022-10-19T15:14:43.607845+01:00",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/604713/"
},
"url": "https://secure.tutorcruncher.com/api/appointments/8255569/"
},
"date": "2022-09-17T19:30:47.967724+01:00",
"payee": {
"id": 1865751,
"first_name": "Bettie",
"last_name": "Canales",
"email": "bettie_canales@online-olive.example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/1865751/"
},
"payer": "Demo Branch",
"rate": "30.00000",
"sales_code": "325",
"tax_amount": "0.00000",
"units": "1.50000"
},
{
"adhoc_charge": null,
"amount": "45.00000",
"appointment": {
"id": 8255568,
"start": "2022-09-10T18:00:47.967724+01:00",
"finish": "2022-09-10T19:30:47.967724+01:00",
"topic": "Programming patterns, algorithms and data structures 3",
"status": "complete",
"service": {
"id": 604713,
"name": "Theory of computer programming",
"dft_charge_type": "hourly",
"created": "2022-08-20T15:14:20.678562+01:00",
"dft_charge_rate": "95.00",
"dft_contractor_rate": "30.00",
"last_updated": "2022-10-19T15:14:43.607845+01:00",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/604713/"
},
"url": "https://secure.tutorcruncher.com/api/appointments/8255568/"
},
"date": "2022-09-10T19:30:47.967724+01:00",
"payee": {
"id": 1865751,
"first_name": "Bettie",
"last_name": "Canales",
"email": "bettie_canales@online-olive.example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/1865751/"
},
"payer": "Demo Branch",
"rate": "30.00000",
"sales_code": "325",
"tax_amount": "0.00000",
"units": "1.50000"
},
{
"adhoc_charge": null,
"amount": "45.00000",
"appointment": {
"id": 8255567,
"start": "2022-09-03T18:00:47.967724+01:00",
"finish": "2022-09-03T19:30:47.967724+01:00",
"topic": "Programming patterns, algorithms and data structures 2",
"status": "complete",
"service": {
"id": 604713,
"name": "Theory of computer programming",
"dft_charge_type": "hourly",
"created": "2022-08-20T15:14:20.678562+01:00",
"dft_charge_rate": "95.00",
"dft_contractor_rate": "30.00",
"last_updated": "2022-10-19T15:14:43.607845+01:00",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/604713/"
},
"url": "https://secure.tutorcruncher.com/api/appointments/8255567/"
},
"date": "2022-09-03T19:30:47.967724+01:00",
"payee": {
"id": 1865751,
"first_name": "Bettie",
"last_name": "Canales",
"email": "bettie_canales@online-olive.example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/1865751/"
},
"payer": "Demo Branch",
"rate": "30.00000",
"sales_code": "325",
"tax_amount": "0.00000",
"units": "1.50000"
},
{
"adhoc_charge": null,
"amount": "45.00000",
"appointment": {
"id": 8255561,
"start": "2022-09-14T12:00:47.967724+01:00",
"finish": "2022-09-14T13:30:47.967724+01:00",
"topic": "Microelectronics and application of semiconductors 4",
"status": "complete",
"service": {
"id": 604712,
"name": "Microelectronics, Semiconductors, Industrial applications",
"dft_charge_type": "hourly",
"created": "2022-08-17T15:14:20.678562+01:00",
"dft_charge_rate": "95.00",
"dft_contractor_rate": "30.00",
"last_updated": "2022-10-19T15:14:43.576396+01:00",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/604712/"
},
"url": "https://secure.tutorcruncher.com/api/appointments/8255561/"
},
"date": "2022-09-14T13:30:47.967724+01:00",
"payee": {
"id": 1865751,
"first_name": "Bettie",
"last_name": "Canales",
"email": "bettie_canales@online-olive.example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/1865751/"
},
"payer": "Demo Branch",
"rate": "30.00000",
"sales_code": "325",
"tax_amount": "0.00000",
"units": "1.50000"
},
{
"adhoc_charge": null,
"amount": "45.00000",
"appointment": {
"id": 8255560,
"start": "2022-09-07T12:00:47.967724+01:00",
"finish": "2022-09-07T13:30:47.967724+01:00",
"topic": "Microelectronics and application of semiconductors 3",
"status": "complete",
"service": {
"id": 604712,
"name": "Microelectronics, Semiconductors, Industrial applications",
"dft_charge_type": "hourly",
"created": "2022-08-17T15:14:20.678562+01:00",
"dft_charge_rate": "95.00",
"dft_contractor_rate": "30.00",
"last_updated": "2022-10-19T15:14:43.576396+01:00",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/604712/"
},
"url": "https://secure.tutorcruncher.com/api/appointments/8255560/"
},
"date": "2022-09-07T13:30:47.967724+01:00",
"payee": {
"id": 1865751,
"first_name": "Bettie",
"last_name": "Canales",
"email": "bettie_canales@online-olive.example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/1865751/"
},
"payer": "Demo Branch",
"rate": "30.00000",
"sales_code": "325",
"tax_amount": "0.00000",
"units": "1.50000"
}
],
"date_sent": "2022-10-19T15:15:36.488105+01:00",
"date_void": null,
"date_paid": null,
"display_id": "PO-46",
"status": "unpaid",
"payee": {
"id": 1865751,
"first_name": "Bettie",
"last_name": "Canales",
"email": "bettie_canales@online-olive.example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/1865751/"
},
"still_to_pay": 225.0
}
Pay partially or pay in full, post how much to be paid towards the Payment Order and we'll return how much there is
still_to_pay
. If fully paid off, paid
will return a value of true
.
1
2
3
4
5
6
7
8
9
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'amount': 100.0,
'method': 'cash',
}
r = requests.post('https://secure.tutorcruncher.com/api/payment-orders/<id>/take_payment/', json=data, headers=headers)
pprint.pprint(r.json())
{
"amount_paid": "100.00",
"still_to_pay": "185.00",
"message": "Payment successfully created",
"paid": false
}
Pipeline Stages are used for your Prospect Clients inside TutorCruncher. They denote at what stage in the Pipeline the client is at. More info.
Unique identifier for the object.
The name of the Pipeline Stage
The sort index of the Pipeline Stage (describes the order of the Pipeline Stages).
{
"id": 7,
"colour": "#B3E5FC",
"name": "Initial Contact",
"sort_index": 1
}
Returns a list of your Pipeline stages.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/pipeline-stages/', headers=headers)
pprint.pprint(r.json())
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": 7,
"colour": "#B3E5FC",
"name": "Initial Contact",
"sort_index": 1
},
{
"id": 8,
"colour": "#B9F6CA",
"name": "Job Agreed",
"sort_index": 2
},
{
"id": 9,
"colour": "#00E676",
"name": "Tutor Matched",
"sort_index": 3
}
]
}
Proforma Invoices objects provide all the details of a TutorCruncher Proforma Invoice including the related
appointments
, adhoc_charges
and the paying_client
for the Proforma Invoice.
Unique identifier for the object.
Amount for the Proforma Invoice.
Object of the Client on the Proforma Invoice.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Client's object.
Proforma Invoice's unique display name.
Date and time the Proforma Invoice was sent to the Client.
Date and time the Proforma Invoice was marked as paid.
An array of items linked to the Proforma Invoice.
Amount for the item.
Description for the item.
Unique identifier for the sales code object used.
Object for a linked Recipient on an Appointment. Object containes attributes recipient
, recipient_name
,
paying_client
, paying_client_name
, and charge_rate
.
An array of Recipient objects on the Proforma Invoice.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Recipient's object.
Proforma Invoice's status. Choice's are draft
, confirmed
, unpaid
, payment-pending
, paid
, failed
,
and void
.
Amount of the Proforma Invoice that still needs to be payed.
{
"id": 2,
"amount": "60.00",
"client": {
"id": 7,
"first_name": "Anthony",
"last_name": "Clay",
"email": "anthony_clay@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/7/"
},
"display_id": "PFI-2",
"date_sent": "2020-01-17T16:11:48.312507Z",
"date_paid": null,
"items": [
{
"amount": "60.00",
"custom_description": "2 Lessons for Izzy",
"sales_codes": null,
"rcra": null
}
],
"service_recipients": [],
"status": "unpaid",
"still_to_pay": 60.0
}
Returns a list of your Proforma Invoices. The Proforma Invoices are sorted by date_sent
,
with the most recently sent first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/proforma-invoices/', headers=headers)
pprint.pprint(r.json())
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"amount": "60.00",
"client": {
"id": 7,
"first_name": "Anthony",
"last_name": "Clay",
"email": "anthony_clay@testagency.example.com",
"url": "https://secure.tutorcruncher.com/api/clients/7/"
},
"display_id": "PFI-2",
"date_sent": "2020-01-17T16:11:48.312507Z",
"date_paid": null,
"status": "unpaid",
"still_to_pay": 60.0,
"url": "https://secure.tutorcruncher.com/api/proforma-invoices/2/"
},
...
]
}
Returns the details of an existing Proforma Invoice, Credit Requests in TutorCruncher. You only need to
specify the unique id
of the Proforma Invoice to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/proforma-invoices/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 2,
"amount": "60.00",
"client": {
"id": 7,
"first_name": "Anthony",
"last_name": "Clay",
"email": "anthony_clay@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/7/"
},
"display_id": "PFI-2",
"date_sent": "2020-01-17T16:11:48.312507Z",
"date_paid": null,
"items": [
{
"amount": "60.00",
"custom_description": "2 Lessons for Izzy",
"sales_codes": null,
"rcra": null
}
],
"service_recipients": [],
"status": "unpaid",
"still_to_pay": 60.0
}
Creating a Proforma Invoice can be done by simply supplying the amount
, the client
who you want to create it for,
and whether you want to send it immediately (send_pfi
). If you have send_pfi
set to True
, the PFI will have the
status 'Unpaid', and an email will be sent to them with the details about the PFI including the PDF.
Note that, if a Proforma Invoice exists that is either Draft or Confirmed, TutorCruncher will simply add a
new item to it and it will NOT be raised, even if send_pfi
is set to true
.
1
2
3
4
5
6
7
8
9
10
11
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'amount': 120,
'client': 312,
'send_pfi': True,
'description': 'Credit Request for Billy Holiday'
}
r = requests.post('https://secure.tutorcruncher.com/api/proforma-invoices/', json=data, headers=headers)
pprint.pprint(r.json())
{
"id": 2,
"amount": "120.00",
"client": {
"id": 321,
"first_name": "Anthony",
"last_name": "Clay",
"email": "anthony_clay@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/321/"
},
"created": true,
"display_id": "PFI-2",
"date_sent": "2020-01-17T16:11:48.312507Z",
"date_paid": null,
"items": [
{
"amount": "60.00",
"custom_description": "Credit Request from terminal",
"sales_codes": null,
"rcra": null
}
],
"service_recipients": [],
"status": "unpaid",
"still_to_pay": 120.0
}
Pay partially or pay in full, post how much the Client paid towards the Proforma Invoice and we'll return how much there is
still_to_pay
. If fully paid off, paid
will return a value of true
. method
is used to define the offline payment method used the choices are cash
, cheque
, credit_card
, bonus_credit
, manual
, voucher
.
1
2
3
4
5
6
7
8
9
10
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'amount': 100.0,
'method': 'cash',
'send_receipt': True,
}
r = requests.post('https://secure.tutorcruncher.com/api/proforma-invoices/<id>/take_payment/', json=data, headers=headers)
pprint.pprint(r.json())
{
"receipt_sent": true,
"amount_paid": "100.00",
"still_to_pay": "185.00",
"message": "Payment successfully created",
"paid": false
}
Public Contractor objects are a simplified Contractor object that are useful if you are building a custom Public Contractor list on your website. Public Contractor objects are only of Contractors who have the Public Profile label on their TutorCruncher account.
Unique identifier for the object.
If the Contractor is deleted or not.
Contractor's first name.
Contractor's last name.
Contractor's town.
Contractor's country.
Contractor's rating.
Amount of hours that the Contractor has been reviewed for.
Object contain the Contractor's location.
Location's latitude.
Location's longitude.
URL to access the Contractor's profile photo.
An array containing custom field values for the Contractor.
An array containing the Contractor's skills.
Name of the Subject.
Name of the Subject Category.
Name of the Qualification Level.
Unique identifier for the Subject.
Unique identifier for the Qualification Level.
Rank for the Qualification Level.
An array of Labels for the Contractor.
Unique identifier for the object.
Name of the label.
Unique slugified name of the label.
Date and time of when the Contractor was last updated.
Date and time of when the Contractor was created.
Date and time of when the Contractor's Profile was released.
{
"id": 56,
"deleted": false,
"first_name": "Scott",
"last_name": "Hafley",
"town": "Clerkenwell",
"country": "United Kingdom",
"review_rating": null,
"review_duration": 0,
"location": {
"latitude": 51.521188,
"longitude": -0.10282
},
"photo": null,
"extra_attributes": [],
"skills": [
{
"subject": "Civil and Structural Engineering",
"category": "Engineering",
"qual_level": "11+",
"subject_id": 21,
"qual_level_id": 2,
"qual_level_ranking": 11.0
},
{
"subject": "Government and Politics",
"category": "Politics",
"qual_level": "11+",
"subject_id": 121,
"qual_level_id": 2,
"qual_level_ranking": 11.0
}
],
"labels": [],
"last_updated": "2020-03-27T13:02:10.012227Z",
"created": "2019-12-18T16:11:48.312507Z",
"release_timestamp": "2020-03-27T13:57:11.124026Z"
}
Returns a list of your Contractors who have the Public Profile label on their profile.
The Contractors are sorted by id
, with the largest id first.
Filter by the date and time the Agent was released.
Filter by the date and time the Agent was released.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/public_contractors/', headers=headers)
pprint.pprint(r.json())
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 56,
"deleted": false,
"first_name": "Scott",
"last_name": "Hafley",
"town": "Clerkenwell",
"country": "United Kingdom",
"review_rating": null,
"review_duration": 0,
"location": {
"latitude": 51.521188,
"longitude": -0.10282
},
"photo": null,
"extra_attributes": [],
"skills": [
{
"subject": "Civil and Structural Engineering",
"category": "Engineering",
"qual_level": "11+",
"subject_id": 21,
"qual_level_id": 2,
"qual_level_ranking": 11.0
},
{
"subject": "Government and Politics",
"category": "Politics",
"qual_level": "11+",
"subject_id": 121,
"qual_level_id": 2,
"qual_level_ranking": 11.0
}
],
"labels": [],
"last_updated": "2020-03-27T13:02:10.012227Z",
"created": "2019-12-18T16:11:48.312507Z",
"release_timestamp": "2020-03-27T13:57:11.124026Z"
},
...
]
}
Returns the basic details of an existing contractor who has the Public Profile label on their profile.
You only need to specify the unique id
of the public profile to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/public_contractors/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 56,
"deleted": false,
"first_name": "Scott",
"last_name": "Hafley",
"town": "Clerkenwell",
"country": "United Kingdom",
"review_rating": null,
"review_duration": 0,
"location": {
"latitude": 51.521188,
"longitude": -0.10282
},
"photo": null,
"extra_attributes": [],
"skills": [
{
"subject": "Civil and Structural Engineering",
"category": "Engineering",
"qual_level": "11+",
"subject_id": 21,
"qual_level_id": 2,
"qual_level_ranking": 11.0
},
{
"subject": "Government and Politics",
"category": "Politics",
"qual_level": "11+",
"subject_id": 121,
"qual_level_id": 2,
"qual_level_ranking": 11.0
}
],
"labels": [],
"last_updated": "2020-03-27T13:02:10.012227Z",
"created": "2019-12-18T16:11:48.312507Z",
"release_timestamp": "2020-03-27T13:57:11.124026Z"
}
Qualification Level object contains the id
, name
and ranking
for qualifications found on your
TutorCruncher account.
Unique identifier for the object.
Name for the Qualification Level.
Rank for the Qualification Level.
{
"id": 6,
"name": "AS Level",
"ranking": 15.0
}
Returns of all the Qualification Levels found on your TutorCruncher account sorted by their ids
with the
largest id first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/qual_levels/', headers=headers)
pprint.pprint(r.json())
{
"count": 21,
"next": null,
"previous": null,
"results": [
{
"id": 5,
"name": "GCSE",
"ranking": 14.0
},
...
]
}
Recipient objects contain the information of your Student including the paying_client
which
is responsible for paying for the Student's Appointments and other charges.
Unique identifier for the object.
User object containing basic information.
The user's first name.
The user's last name.
The user's email address.
The user's mobile number.
The user's phone number.
The user's street address.
This field is only needed for US users. This value will use the state's 2-letter code.
The user's town on address.
User's country, value is an id
of the country stored in TutorCruncher. These country ids can be found
by doing an options request at this endpoints base URL.
The user's postcode on address.
The user's addresses latitude.
The user's addresses longitude.
The date and time the user was created.
The user's timezone, accepted values are timezone database values.
The Recipient's default rate.
An object of the Client who pays invoice on behalf of the Recipient.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Agent's object.
An array of other Clients associated to this Recipient.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Agent's object.
Name of the academic year the Recipient is in.
The date and time the Agent was last updated.
Use hex values, like #fff000
, or use CSS Named colours.
An array of the Agent's labels.
Unique identifier for the object.
Name of the label.
Unique slugified name of the label.
Custom fields for this object.
Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}
{
"id": 4,
"user": {
"title": null,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "arthur_hoskins@example.com",
"mobile": null,
"phone": null,
"street": "12 Helmet Row",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "EC1V 3QJ",
"latitude": "51.5249280000000027",
"longitude": "-0.0944689940000000",
"date_created": "2019-11-24T16:11:48.312507Z",
"timezone": null
},
"default_rate": null,
"paying_client": {
"id": 3,
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/3/"
},
"associated_clients": [],
"academic_year": null,
"last_updated": "2019-11-24T16:11:48.312507Z",
"calendar_colour": "Khaki",
"labels": [],
"extra_attrs": []
}
Returns a list of your recipients. The recipients are sorted by id
, with
the largest id first.
Filter by the date and time the Recipient was created.
Filter by the date and time the Recipient was created.
Filter by the Recipient's first name.
Filter by the Recipient's last name.
Filter by the Recipient's email address.
Filter by the address.
Filter by the radius of the address. This is used in conjunction with the address
filter.
Filter by the Recipient's labels (id).
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/recipients/', headers=headers)
pprint.pprint(r.json())
{
"count": 29,
"next": null,
"previous": null,
"results": [
{
"id": 4,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "arthur_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/recipients/4/"
},
...
]
}
Returns the details of an existing recipient. You only need to specify the unique
id
of the Recipient to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/recipients/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 4,
"user": {
"title": null,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "arthur_hoskins@example.com",
"mobile": null,
"phone": null,
"street": "12 Helmet Row",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "EC1V 3QJ",
"latitude": "51.5249280000000027",
"longitude": "-0.0944689940000000",
"date_created": "2019-11-24T16:11:48.312507Z",
"timezone": null
},
"default_rate": null,
"paying_client": {
"id": 3,
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/3/"
},
"associated_clients": [],
"academic_year": null,
"last_updated": "2019-11-24T16:11:48.312507Z",
"calendar_colour": "Khaki",
"labels": [],
"extra_attrs": []
}
Creating a Recipient can be done by supplying the users information including Recipient specific
information like default_rate
and paying_client
.
To send a welcome email to the Recipient once they have been created, add 'send_emails': True
in the data like in the
example.
Check out Creating/Updating Users for more information on linking to a specific user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'first_name': 'Billy',
'last_name': 'Bob',
'email': 'billy_bob@example.com',
'mobile': '07123456789',
'phone': '02081234567',
'street': '177 South Lambeth Road',
'state': None,
'town': 'London',
'country': 183,
'postcode': 'SW8 1XP',
'latitude': '51.5549',
'longitude': '-0.1084',
'timezone': 'Europe/London',
},
'default_rate': 80.0,
'paying_client': 838,
'calendar_colour': 'LimeGreen',
'extra_attrs': {'user_dob': '1993-06-23'},
'send_emails': True,
}
r = requests.post('https://secure.tutorcruncher.com/api/recipients/', json=data, headers=headers)
pprint.pprint(r.json())
{
"status": "success",
"role": {
"id": 4,
"user": {
"title": null,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "arthur_hoskins@example.com",
"mobile": null,
"phone": null,
"street": "12 Helmet Row",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "EC1V 3QJ",
"latitude": "51.5249280000000027",
"longitude": "-0.0944689940000000",
"date_created": "2019-11-24T16:11:48.312507Z",
"timezone": null
},
"default_rate": null,
"paying_client": {
"id": 3,
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/3/"
},
"associated_clients": [],
"academic_year": 1,
"last_updated": "2019-11-24T16:11:48.312507Z",
"calendar_colour": "Khaki",
"labels": [],
"extra_attrs": [
{
"id": 1,
"value": "1993-06-23",
"type": "Date",
"machine_name": "user-dob",
"name": "Date of birth"
}
]
}
}
Update a Recipient object by supplying the email address as the unique identifier. You must also supply the required
fields like last_name
even if they are not being updated. You only need to post information that you want to change
and not the whole Recipient object.
If the Recipient doesn't have an email address, if you supply a first_name
, last_name
and paying_client
,
we will update a Recipient if the names match an existing Recipient linked to the Client ID you supply
for paying_client
.
Check out Creating/Updating Users for more information on linking to a specific user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'email': 'billy_bob@example.com',
'last_name': 'Bob2',
# ...
},
'extra_attrs': {'user_dob': '1993-06-23'},
# ...
}
r = requests.post('https://secure.tutorcruncher.com/api/recipients/', json=data, headers=headers)
pprint.pprint(r.json())
{
"status": "success",
"role": {
"id": 4,
"user": {
"title": null,
"first_name": "Arthur",
"last_name": "Bob2",
"email": "billy_bob@example.com",
"mobile": null,
"phone": null,
"street": "12 Helmet Row",
"state": null,
"town": "London",
"country": "United Kingdom (GB)",
"postcode": "EC1V 3QJ",
"latitude": "51.5249280000000027",
"longitude": "-0.0944689940000000",
"date_created": "2019-11-24T16:11:48.312507Z",
"timezone": null
},
"default_rate": null,
"paying_client": {
"id": 3,
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/3/"
},
"associated_clients": [],
"academic_year": null,
"last_updated": "2019-11-24T16:11:48.312507Z",
"calendar_colour": "Khaki",
"labels": [],
"extra_attrs": [
{
"id": 1,
"value": "1993-06-23",
"type": "Date",
"machine_name": "user-dob",
"name": "Date of birth"
}
]
}
}
Reports object contains important information like the creator
(the contractor
or administrator
) who wrote the Report, the
service_recipient
who the Review is about, the client
related to the student and the custom fields used to build your Report.
Object of Appointment related to the Report.
Unique identifier for the object.
Appointment's finish date and time.
Appointment's start date and time.
Appointment's topic.
The status for the Appointment, the status types are planned
, awaiting-report
, complete
, cancelled
,
and cancelled-chargeable
.
URL to the Appointment's object.
The Service the Appointment is in.
If the Report has been approved or not.
Object of the Client related to the Report.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Client's object.
Object of the Contractor or Administrator who wrote the Report.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Contractor or Administrator object.
Date and time when the Report was created.
An array of the Report's extra fields.
Unique identifier for the field's object.
Unique slugified name of the field.
The name of the field.
The type of the field.
The value of the field.
Object of the Service recipient related to the Report.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Service recipient's object.
{
"appointment": {
"finish": "2021-06-03T09:30:02.733619Z",
"id": 52,
"service": {
"created": "2021-05-27T14:43:32.572794Z",
"dft_charge_rate": "55.00",
"dft_charge_type": "hourly",
"dft_contractor_rate": "35.00",
"id": 3,
"last_updated": "2021-05-17T14:43:32.572794Z",
"name": "A level Physics",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/3/"
},
"start": "2021-06-03T07:30:02.733619Z",
"status": "Complete",
"topic": "Lesson 1",
"url": "https://secure.tutorcruncher.com/api/appointments/52/"
},
"approved": true,
"client": {
"email": "katherine_brown@example.com",
"first_name": "Katherine",
"id": 17,
"last_name": "Brown",
"url": "https://secure.tutorcruncher.com/api/clients/17/"
},
"creator": {
"email": "brain_johnson@example.com",
"first_name": "brian",
"id": 33,
"last_name": "Johnson",
"url": "https://secure.tutorcruncher.com/api/contractors/33/"
},
"dt_created": "2021-06-22T14:43:52.172855Z",
"extra_attrs": [
{
"id": 43,
"machine_name": "client_report",
"name": "Client Report",
"type": "Long Textbox",
"value": "Great start, 2 more lessons needed"
}
],
"service_recipient": {
"email": "jennifer_brown@testagency.example.com",
"first_name": "Jennifer",
"id": 10,
"last_name": "Brown",
"url": "http://localhost:8000/api/recipients/10/"
}
}
Returns of all the Reports found on your TutorCruncher account, which are sorted by id
in the Reports url
,
with the largest id first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/reports/', headers=headers)
pprint.pprint(r.json())
{
"count": 37,
"next": null,
"previous": null,
"results": [
{
"appointment": {
"finish": "2021-06-03T09:30:02.733619Z",
"id": 52,
"service": {
"created": "2021-05-27T14:43:32.572794Z",
"dft_charge_rate": "55.00",
"dft_charge_type": "hourly",
"dft_contractor_rate": "35.00",
"id": 3,
"last_updated": "2021-05-17T14:43:32.572794Z",
"name": "A level Physics",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/3/"
},
"start": "2021-06-03T07:30:02.733619Z",
"status": "Complete",
"topic": "Lesson 1",
"url": "https://secure.tutorcruncher.com/api/appointments/52/"
},
"approved": true,
"client": {
"email": "katherine_brown@example.com",
"first_name": "Katherine",
"id": 17,
"last_name": "Brown",
"url": "https://secure.tutorcruncher.com/api/clients/17/"
},
"creator": {
"email": "brain_johnson@example.com",
"first_name": "brian",
"id": 33,
"last_name": "Johnson",
"url": "https://secure.tutorcruncher.com/api/contractors/33/"
},
"dt_created": "2021-06-22T14:43:52.172855Z",
"service_recipient": {
"email": "jennifer_brown@testagency.example.com",
"first_name": "Jennifer",
"id": 10,
"last_name": "Brown",
"url": "http://localhost:8000/api/recipients/10/"
},
"url": "http://localhost:8000/api/reports/12/"
},
...
]
}
Returns the details of an existing report. You only need to specify the unique
id
of the Report to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/reports/<id>/', headers=headers)
pprint.pprint(r.json())
{
"appointment": {
"finish": "2021-06-03T09:30:02.733619Z",
"id": 52,
"service": {
"created": "2021-05-27T14:43:32.572794Z",
"dft_charge_rate": "55.00",
"dft_charge_type": "hourly",
"dft_contractor_rate": "35.00",
"id": 3,
"last_updated": "2021-05-17T14:43:32.572794Z",
"name": "A level Physics",
"status": "in-progress",
"url": "https://secure.tutorcruncher.com/api/services/3/"
},
"start": "2021-06-03T07:30:02.733619Z",
"status": "Complete",
"topic": "Lesson 1",
"url": "https://secure.tutorcruncher.com/api/appointments/52/"
},
"approved": true,
"client": {
"email": "katherine_brown@example.com",
"first_name": "Katherine",
"id": 17,
"last_name": "Brown",
"url": "https://secure.tutorcruncher.com/api/clients/17/"
},
"creator": {
"email": "brain_johnson@example.com",
"first_name": "brian",
"id": 33,
"last_name": "Johnson",
"url": "https://secure.tutorcruncher.com/api/contractors/33/"
},
"dt_created": "2021-06-22T14:43:52.172855Z",
"extra_attrs": [
{
"id": 43,
"machine_name": "client_report",
"name": "Client Report",
"type": "Long Textbox",
"value": "Great start, 2 more lessons needed"
}
],
"service_recipient": {
"email": "jennifer_brown@testagency.example.com",
"first_name": "Jennifer",
"id": 10,
"last_name": "Brown",
"url": "http://localhost:8000/api/recipients/10/"
}
}
Reviews object contains important information like the client
who wrote the Review, the
contractor
who the Review is about and the custom fields used to build your Reviews.
Unique identifier for the object.
Object of the Client who wrote the Review.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Client's object.
Object of the Contractor the Review is for.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Contractor's object.
Object of the related Invoice.
Unique identifier for the object.
Invoice number.
Custom fields for this object.
Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}
Total hours added up for related Appointments.
Date and time the Review was created.
{
"id": 3,
"client": {
"id": 17,
"first_name": "Katherine",
"last_name": "Brown",
"email": "katherine_brown@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/17/"
},
"contractor": {
"id": 52,
"first_name": "Brian",
"last_name": "Johnston",
"email": "brian_johnston@example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/52/"
},
"invoice": null,
"extra_attrs": [
{
"id": 61,
"value": "My child had a wonderful experience exploring both english and maths and I was getting asked "When is Brian coming back to teachme more". 100% positive.",
"type": "Long Textbox",
"machine_name": "review-details",
"name": "Review Details"
},
{
"id": 60,
"value": "4.8/5 stars",
"type": "Stars",
"machine_name": "review-stars",
"name": "Review Rating"
}
],
"appointments_duration": "06:00:00",
"date_created": "2020-02-18T16:11:48.312507Z"
}
Returns of all the Reviews found on your TutorCruncher account, which are sorted by id
,
with the largest id first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/reviews/', headers=headers)
pprint.pprint(r.json())
{
"count": 37,
"next": null,
"previous": null,
"results": [
{
"id": 3,
"client": {
"id": 17,
"first_name": "Katherine",
"last_name": "Brown",
"email": "katherine_brown@example.com",
"url": "https://secure.tutorcruncher.com/api/clients/17/"
},
"contractor": {
"id": 52,
"first_name": "Brian",
"last_name": "Johnston",
"email": "brian_johnston@example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/52/"
},
"invoice": null,
"extra_attrs": [
{
"id": 61,
"value": "My child had a wonderful experience exploring both english and maths and I was getting asked "When is Brian coming back to teachme more". 100% positive.",
"type": "Long Textbox",
"machine_name": "review-details",
"name": "Review Details"
},
{
"id": 60,
"value": "4.8/5 stars",
"type": "Stars",
"machine_name": "review-stars",
"name": "Review Rating"
}
],
"appointments_duration": "06:00:00",
"date_created": "2020-02-18T16:11:48.312507Z"
},
...
]
}
Service object, Jobs in TutorCruncher, contains default values for the Appointments related to it. It also returns a list of Clients and Contractors who have been add to the Service.
Unique identifier for the object.
Whether Contractors can propose a rate when applying.
Your unique identifier for your Branch.
Tax setup for the Branch when invoicing.
The maximum number of Appointments that are allowed to occur on the Service.
The Service's calendar colour.
An array of Contractors on the Service.
Contractor's unique identifier.
Contractor's permissions on the Service.
Contractor's full name.
A custom pay rate for the Contractor on this Service only.
Tax setup for the Contractors when invoicing.
Date and time when the Service was created.
Service's description.
How the Service's Appointments will be charged. Types are hourly
or one-off
.
Defaut charge rate for all Appointments on the Service.
Default Contractor permissions to use for all Contractor's on the Service. Choices are add-edit-complete
,
add-edit
, edit
, and complete
.
Default Contractor rate for all Appointments on the Service.
Object of the Service's Default Location.
Unique identifier for the object.
Location's name.
Location's description.
Whether the location can conflict with other Appointment's at similar time.
Unique identifier of the related User to the location.
Location's latitude.
Location's longitude.
Location's full address.
Maximum number of Recipients of allowed on the Service.
Custom fields for this object.
Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}
A fixed amount that will be added for each completed Lesson.
Amount of inactive days before the Service will go cold.
Whether Clients can book Recipients onto the Service.
Whether the Service has been deleted.
Labels on the Service.
Unique identifier for the object.
Name of the label.
Unique slugified name of the label.
Date and time of the latest Appointment or Ad Hoc Charge is added to Service.
Service's name.
Whether the Service Appointments are net
or gross
.
An array of Recipients on the Service.
Unique identifier of the Recipient.
Name of the recipient.
Unique identifier of the Paying Client for the Recipient.
Name of the Paying Client.
Amount the Client will be charged.
Unique identifier for the Agent.
Name of the Agent.
The Agent's percentage on the Service.
Whether the Service must have a Contractor to go ahead.
Whether the Service must have a Recipient to go ahead.
The default amount of hours before an automatic review request is sent.
Unique identifier of the sales code.
An extra amount paid to each Tutor per Student per unit (eg. hour).
Service's status, choices are pending
, available
, in-progress
, finished
, and gone-cold'
.
Total amount of Appointments on the Service, excludes deleted and only cancelled Appointments.
{
"allow_proposed_rates": false,
"branch": 3,
"branch_tax_setup": "Default Company Tax (20%)",
"cap": null,
"colour": "SlateGray",
"conjobs": [
{
"contractor": 54,
"contractor_permissions": "add-edit-complete",
"name": "Walter Moore",
"pay_rate": null
}
],
"contractor_tax_setup": "Default Tutor Tax (no tax)",
"created": "2019-10-31T16:11:48.312507Z",
"description": "Experienced tutor required for a bright student preparing for her A Level Physics exams. General secondary school syllabus needs refreshing as well as specifics preparing for the exams. Mock exams also needed.",
"dft_charge_type": "hourly",
"dft_charge_rate": 75.0,
"dft_contractor_permissions": "add-edit-complete",
"dft_contractor_rate": 35.0,
"dft_location": null,
"dft_max_srs": null,
"extra_attrs": [],
"extra_fee_per_apt": null,
"id": 11,
"inactivity_time": 14,
"is_bookable": false,
"is_deleted": false,
"labels": [],
"latest_apt_ahc": "2020-02-18T16:12:09.888465Z",
"name": "A Level Physics",
"net_gross": "gross",
"rcrs": [
{
"recipient": 20,
"recipient_name": "Caroline Bain",
"paying_client": 19,
"paying_client_name": "Christian Bain",
"charge_rate": null,
"agent": null,
"agent_name": null,
"agent_percentage": null
},
{
"recipient": 21,
"recipient_name": "Mary Bain",
"paying_client": 19,
"paying_client_name": "Christian Bain",
"charge_rate": null,
"agent": null,
"agent_name": null,
"agent_percentage": null
}
],
"require_con_job": true,
"require_rcr": true,
"review_units": null,
"sales_codes": null,
"sr_premium": null,
"status": "finished",
"total_apt_units": 15.0
}
Returns a list of your Services. The Services are sorted by id, with the largest id first.
Filter by the date and time the Service was created.
Filter by the date and time the Service was created.
Filter by the date and time the Service was updated.
Filter by the date and time the Service was updated.
Filter by the Service's labels (id).
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/services/', headers=headers)
pprint.pprint(r.json())
{
"count": 28,
"next": null,
"previous": null,
"results": [
{
"id": 11,
"name": "A Level Physics",
"dft_charge_type": "hourly",
"created": "2019-10-31T16:11:48.312507Z",
"dft_charge_rate": "75.00",
"dft_contractor_rate": "35.00",
"status": "finished",
"url": "https://secure.tutorcruncher.com/api/services/11/"
},
...
]
}
Returns the details of an existing Service. You only need to specify the unique
id
of the Service to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/services/<id>/', headers=headers)
pprint.pprint(r.json())
{
"allow_proposed_rates": true,
"branch": 17597,
"branch_tax_setup": "Default Company Tax (20%)",
"cap": null,
"colour": "Khaki",
"conjobs": [
{
"contractor": 1865741,
"contractor_permissions": "add-edit-complete",
"name": "James Higgins",
"pay_rate": "45.00"
}
],
"contractor_tax_setup": "Default Tutor Tax (no tax)",
"created": "2023-04-18T17:44:08.058135+01:00",
"description": "Example description for the Service which will appear on TutorCruncher",
"dft_charge_type": "hourly",
"dft_charge_rate": 45.0,
"dft_contractor_permissions": "add-edit-complete",
"dft_contractor_rate": 35.0,
"dft_location": null,
"dft_max_srs": 10,
"extra_attrs": [],
"extra_fee_per_apt": null,
"id": 719520,
"inactivity_time": 14,
"is_bookable": false,
"is_deleted": false,
"labels": [],
"last_updated": "2023-04-18T17:44:08.058199+01:00",
"latest_apt_ahc": "2023-04-18T17:44:08.058206+01:00",
"name": "Example Name",
"net_gross": "gross",
"rcrs": [
{
"recipient": 1865698,
"recipient_name": "Arthur Hoskins",
"paying_client": 1865697,
"paying_client_name": "Jamie Hoskins",
"charge_rate": "35.00",
"agent": null,
"agent_name": null,
"agent_percentage": null
}
],
"report_required": false,
"require_con_job": false,
"require_rcr": false,
"review_units": 0,
"sales_codes": null,
"desired_skills": [],
"sr_premium": "0.00",
"status": "pending",
"total_apt_units": 0
}
Creating a Service can be completed simply by giving the name
, dft_charge_rate
, and the dft_contractor_rate
.
This will create a basic Service in TutorCruncher with no Users applied to it. To do this, post a list of user objects
in the conjobs
and rcrs
fields. Other fields can be posted to override the branches default settings.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'allow_proposed_rates': True,
'branch_tax_setup': None,
'cap': None,
'conjobs': [
{
'contractor': 1865741,
'contractor_permissions': 'add-edit-complete',
'pay_rate': 45.0
},
{
'contractor': 1865742,
'contractor_permissions': 'add-edit-complete',
'pay_rate': 35.0
}
],
'rcrs': [
{
'recipient': 1865698,
'charge_rate': 35.0
},
{
'recipient': 1865702,
'charge_rate': 25.0
}
],
'colour': 'Khaki',
'contractor_tax_setup': None,
'description': 'Example description for the Service which will appear on TutorCruncher',
'dft_charge_type': 'hourly',
'dft_charge_rate': 45.0,
'dft_contractor_permissions': 'add-edit-complete',
'dft_contractor_rate': 35.0,
'dft_location': None,
'dft_max_srs': 10,
'extra_attrs': {'study_level': 'GCSE'},
'extra_fee_per_apt': None,
'inactivity_time': None,
'name': 'Example Name',
'net_gross': 'gross',
'report_required': False,
'require_rcr': False,
'require_con_job': False,
'review_units': 0,
'sales_codes': None,
'sr_premium': 0.0,
'status': 'pending'
}
r = requests.post('https://secure.tutorcruncher.com/api/services/', json=data, headers=headers)
pprint.pprint(r.json())
{
"id": 254747,
"allow_proposed_rates": true,
"branch_tax_setup": null,
"cap": null,
"conjobs": [
{
"contractor": 568503,
"contractor_permissions": "add-edit-complete",
"name": "John Smith",
"pay_rate": "45.00"
}
],
"created": "2020-04-01T17:51:05.746889+01:00",
"rcrs": [
{
"recipient": 562725,
"recipient_name": "Billy Bob",
"paying_client": 568504,
"paying_client_name": "Gary Bob",
"charge_rate": "35.00",
"agent": 885425,
"agent_name": "Billy Bob",
"agent_percentage": "30.000"
}
],
"colour": "Khaki",
"contractor_tax_setup": 8361,
"description": "Example description for the Service which will appear on TutorCruncher",
"dft_charge_type": "hourly",
"dft_charge_rate": "45.00",
"dft_contractor_permissions": "add-edit-complete",
"dft_contractor_rate": "35.00",
"dft_location": null,
"dft_max_srs": 10,
"extra_attrs": [
{
"id": 1,
"value": "GCSE",
"type": "Short Textbox",
"machine_name": "study_level",
"name": "Study Level"
}
],
"extra_fee_per_apt": null,
"inactivity_time": null,
"name": "Example Name",
"net_gross": "gross",
"require_rcr": true,
"require_con_job": true,
"review_units": 0,
"sales_codes": null,
"sr_premium": "0.00",
"status": "pending"
}
Updating a Service is similar to Creating a Service using the required fields
name
, dft_charge_rate
, and dft_contractor_rate
. One major difference is
that you cannot add, edit or delete Recipients or Contractors on the Service.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'name': 'SAT Maths with Philip',
'dft_charge_type': 'hourly',
'dft_charge_rate': 55,
'dft_contractor_rate': 40,
'status': 'pending',
'colour': 'blue',
'extra_attrs': {'study_level': 'A Level'}
}
r = requests.put('https://secure.tutorcruncher.com/api/services/<id>/', json=data, headers=headers)
pprint.pprint(r.json())
{
"allow_proposed_rates": false,
"branch": 3,
"branch_tax_setup": "Default Company Tax (20%)",
"cap": null,
"colour": "SlateGray",
"conjobs": [
{
"contractor": 54,
"contractor_permissions": "add-edit-complete",
"name": "Walter Moore",
"pay_rate": null
}
],
"contractor_tax_setup": "Default Tutor Tax (no tax)",
"created": "2019-10-31T16:11:48.312507Z",
"description": "Experienced tutor required for a bright student preparing for her A Level Physics exams. General secondary school syllabus needs refreshing as well as specifics preparing for the exams. Mock exams also needed.",
"dft_charge_type": "hourly",
"dft_charge_rate": 55.0,
"dft_contractor_permissions": "add-edit-complete",
"dft_contractor_rate": 40.0,
"dft_location": null,
"dft_max_srs": null,
"extra_attrs": [
{
"id": 1,
"value": "A Level",
"type": "Short Textbox",
"machine_name": "study_level",
"name": "Study Level"
}
],
"extra_fee_per_apt": null,
"id": 11,
"inactivity_time": 14,
"is_bookable": false,
"is_deleted": false,
"labels": [],
"latest_apt_ahc": "2020-02-18T16:12:09.888465Z",
"name": "SAT Maths with Philip",
"net_gross": "gross",
"rcrs": [
{
"recipient": 20,
"recipient_name": "Caroline Bain",
"paying_client": 19,
"paying_client_name": "Christian Bain",
"charge_rate": null,
"agent": null,
"agent_name": null,
"agent_percentage": null
},
{
"recipient": 21,
"recipient_name": "Mary Bain",
"paying_client": 19,
"paying_client_name": "Christian Bain",
"charge_rate": null,
"agent": null,
"agent_name": null,
"agent_percentage": null
}
],
"require_con_job": true,
"require_rcr": true,
"review_units": null,
"sales_codes": null,
"sr_premium": null,
"status": "finished",
"total_apt_units": 15.0
}
Subject object contains the id
, name
, category_id
and category_name
for Subjects found
on your TutorCruncher account.
Unique identifier for the object.
Name of the Subject.
Unique identifier for the Subject's Category.
Name of the Subject's Category.
{
"id": 22,
"name": "Computer Science",
"category_id": 4,
"category_name": "Engineering"
}
Returns of all the Subjects found on your TutorCruncher account, which are sorted by id
,
with the largest id first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/subjects/', headers=headers)
pprint.pprint(r.json())
{
"count": 22,
"next": null,
"previous": null,
"results": [
{
"id": 22,
"name": "Computer Science",
"category_id": 4,
"category_name": "Engineering"
},
...
]
}
Tasks can be attached to a Client, Student or Tutor to remind you to do something at a certain time.
Unique identifier for the object.
The admin responsible for the Task.
Unique identifier for the object.
The users first name.
The users last name.
The users email address.
Whether or not the Task is completed.
The description of the Task.
The date the Task is due.
Whether or not a reminder is still to be sent.
The date the reminder is to be sent.
How often the Task is to be repeated, the two choices are weekly
or monthly
.
Repeat every x weeks or months.
Object of the Role.
Unique identifier for the object.
The users first name.
The users last name.
The users email address.
URL to the Role's object.
Object of the Service.
Unique identifier for the object.
The name of the Service.
The default charge type of the Service.
The date the Service was created.
The default charge rate of the Service.
The default contractor rate of the Service.
The date the Service was last updated.
The status of the Service.
URL to the Service's object.
The type of Task, the options are phone
, email
, service-cold
or other
.
{
"id": 1,
"admin": {
"id": 59,
"first_name": "Melissa",
"last_name": "Spencer",
"email": "melissa_spencer@example.com"
},
"complete": false,
"description": "This is an example description of a task.",
"due_dt": "2023-07-04T17:40:00+01:00",
"notification_pending": true,
"reminder_dt": "2023-07-04T17:40:00+01:00",
"repeater": "weekly",
"repeat_every": 1,
"role": {
"id": 3,
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@testagency.example.com",
"url": "https://secure.tutorcruncher.com/api/clients/3/"
},
"service": {
"id": 11,
"name": "A Level Physics",
"dft_charge_type": "hourly",
"created": "2023-03-15T15:40:13.104951Z",
"dft_charge_rate": "75.00",
"dft_contractor_rate": "35.00",
"last_updated": "2023-07-03T16:40:24.291003+01:00",
"status": "finished",
"url": "https://secure.tutorcruncher.com/api/services/11/"
},
"task_type": "phone"
}
Returns a list of all your Tasks. The tasks are sorted by id, with the largest id
first.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/tasks/', headers=headers)
pprint.pprint(r.json())
{
"count": 4,
"next": null,
"previous": null,
"results": [
{
"id": 5,
"complete": false,
"description": "This is the fourth tasks description",
"due_dt": "2023-07-08T08:10:00Z",
"task_type": "other",
"url": "https://secure.tutorcruncher.com/api/tasks/5/"
},
{
"id": 4,
"complete": false,
"description": "This is the third tasks description.",
"due_dt": "2023-07-07T08:10:00Z",
"task_type": "service-cold",
"url": "https://secure.tutorcruncher.com/api/tasks/4/"
},
{
"id": 3,
"complete": false,
"description": "This is the second tasks description.",
"due_dt": "2023-07-06T08:09:00Z",
"task_type": "email",
"url": "https://secure.tutorcruncher.com/api/tasks/3/"
},
{
"id": 2,
"complete": false,
"description": "This is the first tasks description.",
"due_dt": "2023-07-05T08:08:00Z",
"task_type": "phone",
"url": "https://secure.tutorcruncher.com/api/tasks/2/"
}
]
}
Returns the details of an existing Task. You only need to specify the unique id
of the Task to get the correct details.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/tasks/<id>/', headers=headers)
pprint.pprint(r.json())
{
"id": 1,
"admin": {
"id": 59,
"first_name": "Melissa",
"last_name": "Spencer",
"email": "melissa_spencer@example.com"
},
"complete": false,
"description": "This is an example description of a task.",
"due_dt": "2023-07-04T17:40:00+01:00",
"notification_pending": true,
"reminder_dt": "2023-07-04T17:40:00+01:00",
"repeater": "weekly",
"repeat_every": 1,
"role": {
"id": 3,
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "jamie_hoskins@testagency.example.com",
"url": "https://secure.tutorcruncher.com/api/clients/3/"
},
"service": {
"id": 11,
"name": "A Level Physics",
"dft_charge_type": "hourly",
"created": "2023-03-15T15:40:13.104951Z",
"dft_charge_rate": "75.00",
"dft_contractor_rate": "35.00",
"last_updated": "2023-07-03T16:40:24.291003+01:00",
"status": "finished",
"url": "https://secure.tutorcruncher.com/api/services/11/"
},
"task_type": "phone"
}
Tender object, Tutor Applications in TutorCruncher, contains the contractor
that has applied,
the service
the Contractor applied for, the Contractors description
and the Tenders status
.
Tender's description from the Contractor.
Object of the Contractor who is applying.
Unique identifier for the object.
User's first name.
User's last name.
User's email address.
URL to the Contractor's object.
Date and time the Tender object was created.
Proposed rate from the Contractor when they applied.
Object of the Service the Contractor applied for.
Unique identifier for the object.
Service's name.
Service's default charge type. Check out Service Object for the types of choices.
Date and time the Service was created.
Service's default amount Clients will be charged.
Service's default amount Contractors will be paided.
Status of the Service. Check out Service Object for the types of statuses.
URL to the Service object.
Tender's status, choices are pending
, requested
, accepted
, rejected
, and withdrawn
.
{
"description": "I'd like to take up this student. I currently teach Economics A level (OCR) at Headington College and so know the syllabus very well, as well as being extremely good with the exam technique at a high level. I am able to start as soon as possible. I'm familiar with both these modules and the OCR board, so would be very happy to take on this student. I've time to take on 1-2 2hr sessions a week, plus marking, or more if required. Thanks.",
"contractor": {
"id": 47,
"first_name": "James",
"last_name": "Higgins",
"email": "james_higgins@example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/47/"
},
"created": "2020-03-30T14:30:58.848581+01:00",
"proposed_rate": null,
"service": {
"id": 5,
"name": "Economics IB tuition",
"dft_charge_type": "hourly",
"created": "2020-03-22T13:30:38.837373Z",
"dft_charge_rate": "110.00",
"dft_contractor_rate": "70.00",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/5/"
},
"status": "pending"
}
Returns of all the Tenders found on your TutorCruncher account, which are sorted by id
,
with the largest id first.
Filter by the Contractor's id.
Filter by the Service's id.
Filter by the date and time the Tender was created.
Filter by the date and time the Tender was created.
1
2
3
4
5
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
r = requests.get('https://secure.tutorcruncher.com/api/tenders/', headers=headers)
pprint.pprint(r.json())
{
"count": 22,
"next": null,
"previous": null,
"results": [
{
"description": "I'd like to take up this student. I currently teach Economics A level (OCR) at Headington College and so know the syllabus very well, as well as being extremely good with the exam technique at a high level. I am able to start as soon as possible. I'm familiar with both these modules and the OCR board, so would be very happy to take on this student. I've time to take on 1-2 2hr sessions a week, plus marking, or more if required. Thanks.",
"contractor": {
"id": 47,
"first_name": "James",
"last_name": "Higgins",
"email": "james_higgins@example.com",
"url": "https://secure.tutorcruncher.com/api/contractors/47/"
},
"created": "2020-03-30T14:30:58.848581+01:00",
"proposed_rate": null,
"service": {
"id": 5,
"name": "Economics IB tuition",
"dft_charge_type": "hourly",
"created": "2020-03-22T13:30:38.837373Z",
"dft_charge_rate": "110.00",
"dft_contractor_rate": "70.00",
"status": "available",
"url": "https://secure.tutorcruncher.com/api/services/5/"
},
"status": "pending"
},
...
]
}