TutorCruncher API
TutorCruncher was last deployed
TutorCruncher API
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.
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)
List all Action Types
Returns a list of all the different Actions we store when a user or our system performs an act on your account.
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": "LOGIN",
"value": "LOGIN",
"msg": "Logged in",
"help_text": "When a User logs in."
},
...
]
Ad Hoc Charge Object
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 appointment or service if the Ad Hoc Charge is related to it.
Attributes
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:
10for Planned15for Awaiting Report20for Complete30for Cancelled40for Cancelled but Chargeable
Unique identifier of the related Service.
Name of the related Service.
URL to the Appointment object.
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_id": 7,
"category_name": "Registration fee",
"charge_client_forex": null,
"client_cost": "25.00",
"client": {
"id": 37,
"first_name": "Nicole",
"last_name": "Beggs",
"email": "[email protected]",
"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": "[email protected]",
"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
}
List all Ad Hoc Charges
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": "Tax law book.",
"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/"
},
...
]
}
Get an Ad Hoc Charge
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_id": 7,
"category_name": "Registration fee",
"charge_client_forex": null,
"client_cost": "25.00",
"client": {
"id": 37,
"first_name": "Nicole",
"last_name": "Beggs",
"email": "[email protected]",
"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": "[email protected]",
"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
}
Agent Object
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.
Attributes
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.
{
"id": 65,
"user": {
"title": null,
"first_name": "Billy",
"last_name": "Holiday",
"email": "[email protected]",
"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": []
}
List all Agents
Returns a list of your agents. The agents 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/agents/', headers=headers)
pprint.pprint(r.json())
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 65,
"first_name": "Billy",
"last_name": "Holiday",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/agents/65/"
}
]
}
Get an Agent
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": "[email protected]",
"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": []
}
Create an Agent
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.
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': '[email protected]',
'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': {},
'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": "[email protected]",
"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": []
}
}
Update an Agent
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'email': '[email protected]',
'last_name': 'Bob2'
# ...
},
# ...
}
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": "[email protected]",
"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": []
}
}
Appointment Object
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.
Attributes
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.
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 but 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.
Unique identifier for the Service which the Appointment is on.
Name of the Service which the Appointment is on.
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"
}
],
"cjas": [
{
"contractor": 43,
"contractor_name": "Billy Holiday",
"pay_rate": "80.00"
}
],
"status": "Planned",
"repeater": null,
"service_id": 2,
"service_name": "Maths GCSE",
"charge_type": "Hourly"
}
List all Appointments
Returns a list of your Appointments. The Appointments 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/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": 2,
"service_name": "Maths GCSE",
"url": "https://secure.tutorcruncher.com/api/appointments/10/"
},
...
]
}
Get an Appointment
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"
}
],
"cjas": [
{
"contractor": 43,
"contractor_name": "Billy Holiday",
"pay_rate": "80.00"
}
],
"status": "Planned",
"repeater": null,
"service_id": 2,
"service_name": "Maths GCSE",
"charge_type": "Hourly"
}
Creating an Appointment
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
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"
}
],
"repeater": null,
"service": 23,
"status": "planned",
"units": "2.00000",
"extra_attrs": {}
}
Add/Edit Recipient on Appointment
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"
}
],
"cjas": [
{
"contractor": 43,
"contractor_name": "Billy Holiday",
"pay_rate": "80.00"
}
],
"status": "Planned",
"repeater": null,
"service_id": 2,
"service_name": "Maths GCSE",
"charge_type": "Hourly"
}
Remove Recipient from Appointment
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": 2,
"service_name": "Maths GCSE",
"charge_type": "Hourly"
}
Add/Edit Contractor on Appointment
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": 2,
"service_name": "Maths GCSE",
"charge_type": "Hourly"
}
Remove Contractor from Appointment
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": 2,
"service_name": "Maths GCSE",
"charge_type": "Hourly"
}
Client Object
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.
Attributes
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.
If false the Client will receive no emails.
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.
The date and time the Client was last updated.
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.
The Client's invoice balance.
The Client's available balance.
{
"id": 3,
"user": {
"title": "Mr",
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "[email protected]",
"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,
"notify_via_email": true,
"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": "[email protected]"
},
"associated_agent": null,
"pipeline-stage": null,
"paid_recipients": [
{
"id": 4,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/recipients/4/"
},
{
"id": 6,
"first_name": "Harry",
"last_name": "Hoskins",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/recipients/6/"
},
{
"id": 5,
"first_name": "Archie",
"last_name": "Hoskins",
"email": "[email protected]",
"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": "",
"type": "Date",
"machine_name": "client-dob",
"name": "Date of birth"
}
],
"invoice_balance": "-120.00",
"available_balance": "-220.50"
}
List all Clients
Returns a list of your Clients. The Clients 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/clients/', headers=headers)
pprint.pprint(r.json())
{
"count": 20,
"next": null,
"previous": null,
"results": [
{
"id": 3,
"first_name": "Jamie",
"last_name": "Hoskins",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/clients/3/"
},
...
]
}
Get a Client
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": "[email protected]",
"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,
"notify_via_email": true,
"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": "[email protected]"
},
"associated_agent": null,
"paid_recipients": [
{
"id": 4,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/recipients/4/"
},
{
"id": 6,
"first_name": "Harry",
"last_name": "Hoskins",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/recipients/6/"
},
{
"id": 5,
"first_name": "Archie",
"last_name": "Hoskins",
"email": "[email protected]",
"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": "",
"type": "Date",
"machine_name": "client-dob",
"name": "Date of birth"
}
],
"invoice_balance": "-120.00",
"available_balance": "-220.50"
}
Create a Client
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.
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
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'first_name': 'Billy',
'last_name': 'Bob',
'email': '[email protected]',
'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,
'notify_via_email': True,
'change_via_branch': True,
'auto_charge': 0,
'associated_admin': 12,
'associated_agent': 34,
'calendar_colour': 'LimeGreen',
'extra_attrs': {},
'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": "[email protected]",
"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,
"notify_via_email": true,
"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": "[email protected]"
},
"associated_agent": null,
"pipeline-stage": null,
"paid_recipients": [
{
"id": 4,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/recipients/4/"
},
{
"id": 6,
"first_name": "Harry",
"last_name": "Hoskins",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/recipients/6/"
},
{
"id": 5,
"first_name": "Archie",
"last_name": "Hoskins",
"email": "[email protected]",
"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": "",
"type": "Date",
"machine_name": "client-dob",
"name": "Date of birth"
}
],
"invoice_balance": "-120.00",
"available_balance": "-220.50"
}
}
Update a Client
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'email': '[email protected]',
'last_name': 'Bob2'
# ...
},
# ...
}
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": "[email protected]",
"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,
"notify_via_email": true,
"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": "[email protected]"
},
"associated_agent": null,
"pipeline-stage": null,
"paid_recipients": [
{
"id": 4,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/recipients/4/"
},
{
"id": 6,
"first_name": "Harry",
"last_name": "Hoskins",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/recipients/6/"
},
{
"id": 5,
"first_name": "Archie",
"last_name": "Hoskins",
"email": "[email protected]",
"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": "",
"type": "Date",
"machine_name": "client-dob",
"name": "Date of birth"
}
],
"invoice_balance": "-120.00",
"available_balance": "-220.50"
}
}
Contractor Object
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.
Attributes
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.
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": "[email protected]",
"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"
}
}
List all Contractors
Returns a list of your contractors. The contractors 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/contractors/', headers=headers)
pprint.pprint(r.json())
{
"count": 20,
"next": null,
"previous": null,
"results": [
{
"id": 47,
"first_name": "James",
"last_name": "Higgins",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/contractors/47/"
},
...
]
}
Get a Contractor
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": "[email protected]",
"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"
}
}
Contractor Availability
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
},
...
]
Create a Contractor
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.
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': '[email protected]',
'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': {},
'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": "[email protected]",
"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"
}
}
}
Update a Contractor
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'email': '[email protected]',
'last_name': 'Bob2'
# ...
},
# ...
}
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": "[email protected]",
"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"
}
}
}
Create an Enquiry
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': '[email protected]',
'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 Object
Invoice objects provide all the details of a TutorCruncher Invoice including the related
appointments, adhoc_charges and the paying_client for the Invoice.
Attributes
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, service_id, service_name, and url.
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": "[email protected]",
"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": 24,
"service_name": "Microelectronics, Semiconductors, Industrial applications",
"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": "[email protected]",
"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": 24,
"service_name": "Microelectronics, Semiconductors, Industrial applications",
"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": "[email protected]",
"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": "[email protected]",
"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"
}
List all Invoices
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": 10,
"start": "2020-01-01T12:00:00Z",
"finish": "2020-01-01T13:00:00Z",
"topic": "Lesson 1",
"status": 10,
"service_id": 2,
"service_name": "Maths GCSE",
"url": "https://secure.tutorcruncher.com/api/invoices/10/"
},
...
]
}
Get an Invoice
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": "[email protected]",
"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": 24,
"service_name": "Microelectronics, Semiconductors, Industrial applications",
"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": "[email protected]",
"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": 24,
"service_name": "Microelectronics, Semiconductors, Industrial applications",
"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": "[email protected]",
"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": "[email protected]",
"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"
}
Take Invoice Payment
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
}
Pipeline Stage Object
Pipeline Stages are used for your Prospect Clients inside TutorCruncher. They denote at what stage in the Pipeline the client is at. More info.
Attributes
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
}
List Pipeline Stages
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 Object
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.
Attributes
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": "[email protected]",
"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
}
List all Proforma Invoicess
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": "[email protected]",
"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/"
},
...
]
}
Get an Proforma Invoices
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": "[email protected]",
"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
}
Create a Proforma Invoice
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.
1
2
3
4
5
6
7
8
9
10
11
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
client_id = 123
data = {
'amount': 120,
'client': client_id,
'send_pfi': True,
}
r = requests.post('https://secure.tutorcruncher.com/api/clients/', json=data, headers=headers)
pprint.pprint(r.json())
{
"client": 312,
"amount": "425.00",
"send_pfi": false
}
Take Proforma Invoice Payment
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.
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 Object
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.
Attributes
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"
}
List all Public Contractors
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.
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"
},
...
]
}
Get a Public Contractor
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
Qualification Level object contains the id, name and ranking for qualifications found on your
TutorCruncher account.
Attributes
Unique identifier for the object.
Name for the Qualification Level.
Rank for the Qualification Level.
{
"id": 6,
"name": "AS Level",
"ranking": 15.0
}
List all Qualification Levels
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 Object
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.
Attributes
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.
{
"id": 4,
"user": {
"title": null,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "[email protected]",
"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": "[email protected]",
"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": []
}
List all Recipients
Returns a list of your recipients. The recipients 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/recipients/', headers=headers)
pprint.pprint(r.json())
{
"count": 29,
"next": null,
"previous": null,
"results": [
{
"id": 4,
"first_name": "Arthur",
"last_name": "Hoskins",
"email": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/recipients/4/"
},
...
]
}
Get a Recipient
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": "[email protected]",
"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": "[email protected]",
"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": []
}
Create a Recipient
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.
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': '[email protected]',
'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': {},
'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": "[email protected]",
"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": "[email protected]",
"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": []
}
}
Update a Recipient
Update a 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 Recipient object.
1
2
3
4
5
6
7
8
9
10
11
12
13
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'user': {
'email': '[email protected]',
'last_name': 'Bob2'
# ...
},
# ...
}
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": "[email protected]",
"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": "[email protected]",
"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": []
}
}
Reviews Object
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.
Attributes
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.
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": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/clients/17/"
},
"contractor": {
"id": 52,
"first_name": "Brian",
"last_name": "Johnston",
"email": "[email protected]",
"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"
}
List all Reviews
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": "[email protected]",
"url": "https://secure.tutorcruncher.com/api/clients/17/"
},
"contractor": {
"id": 52,
"first_name": "Brian",
"last_name": "Johnston",
"email": "[email protected]",
"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
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.
Attributes
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.
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
}
List all Services
Returns a list of your Services. The Services 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/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/"
},
...
]
}
Get a Service
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": 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
}
Create a Service
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
import pprint, requests
headers = {'Authorization': 'token <API KEY>'}
data = {
'allow_proposed_rates': True,
'branch_tax_setup': None,
'cap': None,
'conjobs': [
{
'contractor': 568503,
'contractor_permissions': 'add-edit-complete',
'pay_rate': 45.0,
}
],
'rcrs': [
{
'recipient': 562725,
'charge_rate': 35.0,
'agent': 885425,
'agent_percentage': 30.0,
}
],
'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.0,
'dft_contractor_permissions': 'add-edit-complete',
'dft_contractor_rate': 35.0,
'dft_location': None,
'dft_max_srs': 10,
'extra_attrs': {},
'extra_fee_per_apt': None,
'inactivity_time': None,
'name': 'Example Name',
'net_gross': 'gross',
'require_rcr': True,
'require_con_job': True,
'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": {},
"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"
}
Subject Object
Subject object contains the id, name, category_id and category_name for Subjects found
on your TutorCruncher account.
Attributes
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"
}
List all Subjects
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"
},
...
]
}
Tender Object
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.
Attributes
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": "[email protected]",
"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"
}
List all Tenders
Returns of all the Tenders 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/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": "[email protected]",
"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"
},
...
]
}