TutorCruncher Logo TutorCruncher API

TutorCruncher was last deployed

SHOW MENU
HIDE MENU

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.

BASE URL

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.

AUTHENTICATION

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.

GET /api/action-types/

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())
RESPONSE
[   {     "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

id integer

Unique identifier for the object.

agent object

Object of the Agent.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Agent's object.

appointment object

Object of the Appointment.

Show child attributes
id integer

Unique identifier for the object.

start string

Start date and time for the Appointment.

finish string

Finish date and time for the Appointment.

topic string

Topic for the Appointment.

status integer

The status for the Appointment, the choices are:

  • 10 for Planned
  • 15 for Awaiting Report
  • 20 for Complete
  • 30 for Cancelled
  • 40 for Cancelled but Chargeable
service_id integer

Unique identifier of the related Service.

service_name string

Name of the related Service.

url string

URL to the Appointment object.

category_id integer

Unique identifier for the Ad Hoc Charge Category.

category_name string

Name for the Ad Hoc Charge Category.

charge_client_forex string

Amount of money in other currency.

client_cost string

Amount of money in the Branch's currency.

client object

Object of the Client.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Client's object.

contractor object

Object to the Contractor.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Contractor's object.

creator object

User who created the Ad Hoc Charge.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

currency string

The currency used.

currency_conversion string

Currency conversion at the time the Ad Hoc Charge was created.

date_occurred string

Date and time the Ad Hoc Charge was created.

invoices array

An array of Invoices the Ad Hoc Charge appears on.

Show child attributes
id integer

Unique identifier for the object.

display_id string

The Invoice's display ID.

date_sent string

Date and time the Invoice was sent.

gross string

Gross amount for the Invoice.

net decimal

Net amount for the Invoice.

tax string

Tax amount for the Invoice.

client object

Object of the Client on the Invoice. Contains their id, first_name, last_name, email, and url.

status string

The status of the Invoice. Check out Invoice Object for the types of statuses.

url string

The URL to the Invoice object.

payment_orders array

An array of Payment Orders the Ad Hoc Charge appears on.

Show child attributes
id integer

Unique identifier for the object.

display_id string

The Payment Order's display ID.

gross string

Gross amount for the Payment Order.

net decimal

Net amount for the Payment Order.

tax string

Tax amount for the Invoice.

payee object

Object of the Payee on the Payment Order. Contains their id, first_name, last_name, email, and url.

status string

The status of the Payment Order. Check out Payment Order Object for the types of statuses.

net_gross string

Whether the Ad Hoc Charge is net or gross.

pay_contractor string

Amount the Contractor will be paid.

service object

Object of the Service related to the Ad Hoc Charge.

Show child attributes
id integer

Unique identifier for the object.

name string

Service's name.

dft_charge_type string

Service's default charge type. Check out Service Object for the types of choices.

created string

Date and time the Service was created.

dft_charge_rate string

Service's default amount Clients will be charged.

dft_contractor_rate string

Service's default amount Contractors will be paided.

status string

Status of the Service. Check out Service Object for the types of statuses.

url string

URL to the Service object.

tax_amount decimal

Amount of tax on the Ad Hoc Charge.

OBJECT
{   "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": "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 }

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.

GET /api/adhoccharges/

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())
RESPONSE
{   "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.

GET /api/adhoccharges/<id>/

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())
RESPONSE
{   "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": "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 }

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

id integer

Unique identifier for the object.

user object

User object containing basic information.

Show child attributes
first_name string

The user's first name.

last_name string

The user's last name.

email string

The user's email address.

mobile string

The user's mobile number.

phone string

The user's phone number.

street string

The user's street address.

state string

This field is only needed for US users. This value will use the state's 2-letter code.

town string

The user's town on address.

country integer

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.

postcode string

The user's postcode on address.

latitude decimal

The user's addresses latitude.

longitude decimal

The user's addresses longitude.

date_created string

The date and time the user was created.

timezone string

The user's timezone, accepted values are timezone database values.

commission_rate string

Percentage of the Agent's commission rate.

clients array

An array of Clients which the Agent is related to.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Agent's object.

last_updated string

The date and time the Agent was last updated.

calendar_colour string

Use hex values, like #fff000, or use CSS Named colours.

labels array

An array of the Agent's labels.

Show child attributes
id integer

Unique identifier for the object.

name string

Name of the label.

machine_name string

Unique slugified name of the label.

extra_attrs array

Custom fields for this object.

OBJECT
{   "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": [] }

List all Agents

Returns a list of your agents. The agents are sorted by id, with the largest id first.

GET /api/agents/

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())
RESPONSE
{   "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/"     }   ] }

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.

GET /api/agents/<id>/

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())
RESPONSE
{   "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": [] }

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.

POST /api/agents/

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': {}, 'send_emails': True, } r = requests.post('https://secure.tutorcruncher.com/api/agents/', json=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "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": []   } }

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.

POST /api/agents/

1

2

3

4

5

6

7

8

9

10

11

12

13

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'user': { 'email': 'billy_bob@example.com', 'last_name': 'Bob2' # ... }, # ... } r = requests.post('https://secure.tutorcruncher.com/api/agents/', json=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "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": []   } }

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

id integer

Unique identifier for the object.

start string

Appointment's start date and time.

finish string

Appointment's finish date and time.

units string

If charge type hourly, units will be the length of the Appointment divided by an hour.

topic string

Appointment's topic.

location object

Object of the Appointment's Location.

Show child attributes
id integer

Unique identifier for the object.

name string

Location's name.

description string

Location's description.

can_conflict boolean

Whether the location can conflict with other Appointment's at similar time.

role integer

Unique identifier of the related User to the location.

latitute string

Location's latitude.

longitude string

Location's longitude.

address string

Location's full address.

rcras array

An array of Recipients that are on the Appointment.

Show child attributes
recipient integer

Unique identifier of the Recipient.

recipient_name string

Name of the recipient.

paying_client integer

Unique identifier of the Paying Client for the Recipient.

paying_client_name string

Name of the Paying Client.

charge_rate string

Amount the Client will be charged.

cjas array

An array of Contractors that are on the Appointment.

Show child attributes
contractor integer

Unique identifier of the Contractor.

contractor_name string

Name of the Contractor.

pay_rate string

Amount the Contractor will be charged.

status string

The status for the Appointment, the status types are Planned, Awaiting Report, Complete, Cancelled, and Cancelled but Chargeable.

repeater object

Object about the Appointment's repeating appointments.

Show child attributes
repeat string

Type of repeater, types are Daily or Weekly.

every integer

How often it will repeat lessons, every X days/weeks.

repeat_on string

List of days the repeater will add Appointments on.

stops_on string

Date the repeater will stop adding Appointments.

stops_after integer

Max amount of Appointments that will be created.

source_apt integer

Unique identifier of the Appointment which the repeater is repeating from.

service_id integer

Unique identifier for the Service which the Appointment is on.

service_name string

Name of the Service which the Appointment is on.

charge_type string

How the Appointment will be charged. Types are Hourly or One off.

OBJECT
{   "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.

GET /api/appointments/

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())
RESPONSE
{   "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.

GET /api/appointments/<id>/

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())
RESPONSE
{   "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.

POST /api/appointments/

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())
RESPONSE
{   "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.

PUT /api/appointments/<id>/

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())
RESPONSE
{   "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.

POST /api/appointments/<id>/recipient/add/

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())
RESPONSE
{   "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.

POST /api/appointments/<id>/recipient/remove/

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())
RESPONSE
{   "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.

POST /api/appointments/<id>/contractor/add/

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())
RESPONSE
{   "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.

POST /api/appointments/<id>/contractor/remove/

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())
RESPONSE
{   "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

id integer

Unique identifier for the object.

user object

User object containing basic information.

Show child attributes
first_name string

The user's first name.

last_name string

The user's last name.

email string

The user's email address.

mobile string

The user's mobile number.

phone string

The user's phone number.

street string

The user's street address.

state string

This field is only needed for US users. This value will use the state's 2-letter code.

town string

The user's town on address.

country integer

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.

postcode string

The user's postcode on address.

latitude decimal

The user's addresses latitude.

longitude decimal

The user's addresses longitude.

date_created string

The date and time the user was created.

timezone string

The user's timezone, accepted values are timezone database values.

status string

The Client's status, choices are prospect, live and dormant.

is_taxable boolean

Whether or not tax should be paid on payments from this Client.

notify_via_email boolean

If false the Client will receive no emails.

charge_via_branch boolean

Force Invoices associated with this Tutor to be charged via branch.

invoices_count integer

The number of invoice related to the Client.

payment_pending string

Total amount of pending payments related to the Client.

auto_charge integer

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.

associated_admin object

Object of the Client Manager.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

associated_agent object

Object of the set agent.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Agent's object.

pipeline-stage object

PipelineStage of the client if they are a Prosect client.

Show child attributes
id integer

Unique identifier for the object.

name string

The name of the PipelineStage

sort_index integer

The sort index of the PipelineStage (describes the order of the PipelineStages).

paid_recipients array

An array of recipients related to the Client.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Recipient's object.

last_updated string

The date and time the Client was last updated.

calendar_colour string

Use hex values, like #fff000, or use CSS Named colours.

labels array

An array of the Client's labels.

Show child attributes
id integer

Unique identifier for the object.

name string

Name of the label.

machine_name string

Unique slugified name of the label.

extra_attrs array

Custom fields for this object.

invoice_balance string

The Client's invoice balance.

available_balance string

The Client's available balance.

OBJECT
{   "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,   "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": "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": "",       "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.

GET /api/clients/

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())
RESPONSE
{   "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/"     },     ...   ] }

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.

GET /api/clients/<id>/

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())
RESPONSE
{   "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,   "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": "diana_lafayette@example.com"   },   "associated_agent": 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": "",       "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.

POST /api/clients/

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': '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, '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())
RESPONSE
{   "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,     "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": "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": "",         "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.

POST /api/clients/

1

2

3

4

5

6

7

8

9

10

11

12

13

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'user': { 'email': 'billy_bob@example.com', 'last_name': 'Bob2' # ... }, # ... } r = requests.post('https://secure.tutorcruncher.com/api/clients/', json=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "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,     "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": "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": "",         "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

id integer

Unique identifier for the object.

user object

User object containing basic information.

Show child attributes
first_name string

The user's first name.

last_name string

The user's last name.

email string

The user's email address.

mobile string

The user's mobile number.

phone string

The user's phone number.

street string

The user's street address.

state string

This field is only needed for US users. This value will use the state's 2-letter code.

town string

The user's town on address.

country integer

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.

postcode string

The user's postcode on address.

latitude decimal

The user's addresses latitude.

longitude decimal

The user's addresses longitude.

date_created string

The date and time the user was created.

timezone string

The user's timezone, accepted values are timezone database values.

status string

The Contractor's status, choices are pending, approved, rejected and dormant.

charge_via_branch boolean

Force Invoices associated with this Tutor to be charged via branch.

default_rate decimal

The Contractor's rate which will be used to override service default rates.

qualifications array

An array of the Contractor's qualifications.

Show child attributes
id integer

Unique identifier for the object.

institution string

Name of the institution.

subject string

Name of the subject.

qual_level string

Name of the qualification.

grade string

The grade for the qualification.

year integer

The year for the qualification.

governing_body string

Name of the governing body for the qualification.

skills array

An array of the Contractor's skills.

Show child attributes
id integer

Unique identifier for the object.

subject string

Name of the subject.

qual_level string

Name of the qualification.

institutions array

An array of the Contractor's institutions.

Show child attributes
id integer

Unique identifier for the object.

name string

Name of the institution.

receive_service_notifications boolean

When checked the Tutor will receive email notifications of Jobs available for application.

review_rating decimal

Contractor's review rating.

review_duration string

Total amount of time that has been reviewed.

last_updated string

The date and time the Contractor was last updated.

calendar_colour string

Use hex values, like #fff000, or use CSS Named colours.

labels array

An array of the Contractor's labels.

Show child attributes
id integer

Unique identifier for the object.

name string

Name of the label.

machine_name string

Unique slugified name of the label.

extra_attrs array

Custom fields for this object.

work_done_details object

Details about the work the Contractor has done.

Show child attributes
amount_owed decimal

The amount of money the Contractor is owed.

amount_paid decimal

The amount of money the Contractor has been paid.

total_paid_hours string

Total amount of time the Contractor has been paid for.

OBJECT
{   "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"   } }

List all Contractors

Returns a list of your contractors. The contractors are sorted by id, with the largest id first.

GET /api/contractors/

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())
RESPONSE
{   "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/"     },     ...   ] }

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.

GET /api/contractors/<id>/

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())
RESPONSE
{   "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"   } }

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.

GET /api/contractor_availability/<id>/

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())
RESPONSE
[   {     "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.

POST /api/contractors/

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': {}, 'send_emails': True, } r = requests.post('https://secure.tutorcruncher.com/api/contractors/', json=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "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": [],     "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.

POST /api/contractors/

1

2

3

4

5

6

7

8

9

10

11

12

13

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'user': { 'email': 'billy_bob@example.com', 'last_name': 'Bob2' # ... }, # ... } r = requests.post('https://secure.tutorcruncher.com/api/contractors/', json=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "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": [],     "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.

POST /api/enquiry/

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())
RESPONSE
{   "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

id integer

Unique identifier for the object.

charges array

An array of different charges related to the invoice.

Show child attributes
adhoc_charge object

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 string

Amount of the charge.

appointment object

Object that contains information about the Appointment. Attributes in the object are id, start, finish, topic, status, service_id, service_name, and url.

date string

Date and time the charge occured.

payee string

Name of who will recieve the charge amount.

payer object

Object of the Client who will pay invoice. Attributes in the object are id, first_name, last_name, email, and url.

rate string

The rate used to calculate the charge amount.

sales_code string

The sales code used for this charge.

tax_amount string

The amount of tax for this charge.

units string

Amount of units used to calculate the charge amount.

client object

Object of the Client on the Invoice.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Client's object.

date_sent string

Date and time the Invoice was sent to the Client.

date_void string

Date and time the Invoice was marked as void.

date_paid string

Date and time the Invoice was marked as paid.

display_id string

Invoice's unique display name.

gross string

Invoice's gross amount.

net decimal

Invoice's net amount.

status string

Invoice's status. Choice's are draft, confirmed, unpaid, payment-pending, paid, failed, and void.

still_to_pay decimal

Amount of the Invoice that still needs to be payed.

tax string

Invoice's tax amount.

OBJECT
{   "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": 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": "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": 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": "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" }

List all Invoices

Returns a list of your Invoices. The Invoices are sorted by date_sent, with the most recently sent first.

GET /api/invoices/

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())
RESPONSE
{   "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.

GET /api/invoices/<id>/

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())
RESPONSE
{   "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": 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": "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": 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": "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" }

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.

POST /api/invoices/<id>/take_payment/

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())
RESPONSE
{   "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

id integer

Unique identifier for the object.

name string

The name of the Pipeline Stage

sort_index integer

The sort index of the Pipeline Stage (describes the order of the Pipeline Stages).

OBJECT
{     "id": 7,     "colour": "#B3E5FC",     "name": "Initial Contact",     "sort_index": 1 }

List Pipeline Stages

Returns a list of your Pipeline stages.

GET /api/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())
RESPONSE
{     "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

id integer

Unique identifier for the object.

amount string

Amount for the Proforma Invoice.

client object

Object of the Client on the Proforma Invoice.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Client's object.

display_id string

Proforma Invoice's unique display name.

date_sent string

Date and time the Proforma Invoice was sent to the Client.

date_paid string

Date and time the Proforma Invoice was marked as paid.

items array

An array of items linked to the Proforma Invoice.

Show child attributes
amount string

Amount for the item.

custom_description string

Description for the item.

sales_codes string

Unique identifier for the sales code object used.

rcra object

Object for a linked Recipient on an Appointment. Object containes attributes recipient, recipient_name, paying_client, paying_client_name, and charge_rate.

service_recipients array

An array of Recipient objects on the Proforma Invoice.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Recipient's object.

status string

Proforma Invoice's status. Choice's are draft, confirmed, unpaid, payment-pending, paid, failed, and void.

still_to_pay decimal

Amount of the Proforma Invoice that still needs to be payed.

OBJECT
{   "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 }

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.

GET /api/proforma-invoices/

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())
RESPONSE
{   "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/"     },     ...   ] }

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.

GET /api/proforma-invoices/<id>/

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())
RESPONSE
{   "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 }

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.

POST /api/proforma-invoices/

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())
RESPONSE
{   "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.

POST /api/proforma-invoices/<id>/take_payment/

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())
RESPONSE
{   "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

id integer

Unique identifier for the object.

deleted boolean

If the Contractor is deleted or not.

first_name string

Contractor's first name.

last_name string

Contractor's last name.

town string

Contractor's town.

country string

Contractor's country.

review_rating decimal

Contractor's rating.

review_duration integer

Amount of hours that the Contractor has been reviewed for.

location object

Object contain the Contractor's location.

Show child attributes
latitude decimal

Location's latitude.

longitude decimal

Location's longitude.

photo string

URL to access the Contractor's profile photo.

extra_attributes array

An array containing custom field values for the Contractor.

skills array

An array containing the Contractor's skills.

Show child attributes
subject string

Name of the Subject.

category string

Name of the Subject Category.

qual_level string

Name of the Qualification Level.

subject_id integer

Unique identifier for the Subject.

qual_level_id integer

Unique identifier for the Qualification Level.

qual_level_ranking decimal

Rank for the Qualification Level.

labels array

An array of Labels for the Contractor.

Show child attributes
id integer

Unique identifier for the object.

name string

Name of the label.

machine_name string

Unique slugified name of the label.

last_updated string

Date and time of when the Contractor was last updated.

created string

Date and time of when the Contractor was created.

release_timestamp string

Date and time of when the Contractor's Profile was released.

OBJECT
{   "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.

GET /api/public_contractors/

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())
RESPONSE
{   "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.

GET /api/public_contractors/<id>/

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())
RESPONSE
{   "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

id integer

Unique identifier for the object.

name string

Name for the Qualification Level.

ranking decimal

Rank for the Qualification Level.

OBJECT
{   "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.

GET /api/qual_levels/

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())
RESPONSE
{   "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

id integer

Unique identifier for the object.

user object

User object containing basic information.

Show child attributes
first_name string

The user's first name.

last_name string

The user's last name.

email string

The user's email address.

mobile string

The user's mobile number.

phone string

The user's phone number.

street string

The user's street address.

state string

This field is only needed for US users. This value will use the state's 2-letter code.

town string

The user's town on address.

country integer

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.

postcode string

The user's postcode on address.

latitude decimal

The user's addresses latitude.

longitude decimal

The user's addresses longitude.

date_created string

The date and time the user was created.

timezone string

The user's timezone, accepted values are timezone database values.

default_rate decimal

The Recipient's default rate.

paying_client object

An object of the Client who pays invoice on behalf of the Recipient.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Agent's object.

associated_clients array

An array of other Clients associated to this Recipient.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Agent's object.

academic_year string

Name of the academic year the Recipient is in.

last_updated string

The date and time the Agent was last updated.

calendar_colour string

Use hex values, like #fff000, or use CSS Named colours.

labels array

An array of the Agent's labels.

Show child attributes
id integer

Unique identifier for the object.

name string

Name of the label.

machine_name string

Unique slugified name of the label.

extra_attrs array

Custom fields for this object.

OBJECT
{   "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": [] }

List all Recipients

Returns a list of your recipients. The recipients are sorted by id, with the largest id first.

GET /api/recipients/

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())
RESPONSE
{   "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/"     },     ...   ] }

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.

GET /api/recipients/<id>/

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())
RESPONSE
{   "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": [] }

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.

POST /api/recipients/

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': {}, 'send_emails': True, } r = requests.post('https://secure.tutorcruncher.com/api/recipients/', json=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "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": []   } }

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.

POST /api/recipients/

1

2

3

4

5

6

7

8

9

10

11

12

13

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'user': { 'email': 'billy_bob@example.com', 'last_name': 'Bob2' # ... }, # ... } r = requests.post('https://secure.tutorcruncher.com/api/recipients/', json=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "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": []   } }

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

id integer

Unique identifier for the object.

client object

Object of the Client who wrote the Review.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Client's object.

contractor object

Object of the Contractor the Review is for.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Contractor's object.

invoice object

Object of the related Invoice.

Show child attributes
id integer

Unique identifier for the object.

accounting_id integer

Invoice number.

extra_attrs array

Custom fields for this object.

appointments_duration string

Total hours added up for related Appointments.

date_created string

Date and time the Review was created.

OBJECT
{   "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 &quot;When is Brian coming back to teachme more&quot;. 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.

GET /api/reviews/

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())
RESPONSE
{   "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 &quot;When is Brian coming back to teachme more&quot;. 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

id integer

Unique identifier for the object.

allow_proposed_rates boolean

Whether Contractors can propose a rate when applying.

branch integer

Your unique identifier for your Branch.

branch_tax_setup string

Tax setup for the Branch when invoicing.

cap integer

The maximum number of Appointments that are allowed to occur on the Service.

colour string

The Service's calendar colour.

conjobs array

An array of Contractors on the Service.

Show child attributes
contractor integer

Contractor's unique identifier.

contractor_permissions string

Contractor's permissions on the Service.

name string

Contractor's full name.

pay_rate decimal

A custom pay rate for the Contractor on this Service only.

contractor_tax_setup string

Tax setup for the Contractors when invoicing.

created string

Date and time when the Service was created.

description string

Service's description.

dft_charge_type string

How the Service's Appointments will be charged. Types are hourly or one-off.

dft_charge_rate decimal

Defaut charge rate for all Appointments on the Service.

dft_contractor_permissions string

Default Contractor permissions to use for all Contractor's on the Service. Choices are add-edit-complete, add-edit, edit, and complete.

dft_contractor_rate decimal

Default Contractor rate for all Appointments on the Service.

dft_location object

Object of the Service's Default Location.

Show child attributes
id integer

Unique identifier for the object.

name string

Location's name.

description string

Location's description.

can_conflict boolean

Whether the location can conflict with other Appointment's at similar time.

role integer

Unique identifier of the related User to the location.

latitute string

Location's latitude.

longitude string

Location's longitude.

address string

Location's full address.

dft_max_srs integer

Maximum number of Recipients of allowed on the Service.

extra_attrs array

Custom fields for this object.

extra_fee_per_apt string

A fixed amount that will be added for each completed Lesson.

inactivity_time integer

Amount of inactive days before the Service will go cold.

is_bookable boolean

Whether Clients can book Recipients onto the Service.

is_deleted boolean

Whether the Service has been deleted.

labels array

Labels on the Service.

Show child attributes
id integer

Unique identifier for the object.

name string

Name of the label.

machine_name string

Unique slugified name of the label.

latest_apt_ahc string

Date and time of the latest Appointment or Ad Hoc Charge is added to Service.

name string

Service's name.

net_gross string

Whether the Service Appointments are net or gross.

rcrs array

An array of Recipients on the Service.

Show child attributes
recipient integer

Unique identifier of the Recipient.

recipient_name string

Name of the recipient.

paying_client integer

Unique identifier of the Paying Client for the Recipient.

paying_client_name string

Name of the Paying Client.

charge_rate string

Amount the Client will be charged.

agent integer

Unique identifier for the Agent.

agent_name string

Name of the Agent.

agent_percentage string

The Agent's percentage on the Service.

require_con_job boolean

Whether the Service must have a Contractor to go ahead.

require_rcr boolean

Whether the Service must have a Recipient to go ahead.

review_units integer

The default amount of hours before an automatic review request is sent.

sales_codes integer

Unique identifier of the sales code.

sr_premium string

An extra amount paid to each Tutor per Student per unit (eg. hour).

status string

Service's status, choices are pending, available, in-progress, finished, and gone-cold'.

total_apt_units decimal

Total amount of Appointments on the Service, excludes deleted and only cancelled Appointments.

OBJECT
{   "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.

GET /api/services/

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())
RESPONSE
{   "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.

GET /api/services/<id>/

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())
RESPONSE
{   "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.

POST /api/services/

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())
RESPONSE
{   "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

id integer

Unique identifier for the object.

name string

Name of the Subject.

category_id integer

Unique identifier for the Subject's Category.

category_name string

Name of the Subject's Category.

OBJECT
{   "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.

GET /api/subjects/

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())
RESPONSE
{   "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

description string

Tender's description from the Contractor.

contractor object

Object of the Contractor who is applying.

Show child attributes
id integer

Unique identifier for the object.

first_name string

User's first name.

last_name string

User's last name.

email string

User's email address.

url string

URL to the Contractor's object.

created string

Date and time the Tender object was created.

proposed_rate string

Proposed rate from the Contractor when they applied.

service object

Object of the Service the Contractor applied for.

Show child attributes
id integer

Unique identifier for the object.

name string

Service's name.

dft_charge_type string

Service's default charge type. Check out Service Object for the types of choices.

created string

Date and time the Service was created.

dft_charge_rate string

Service's default amount Clients will be charged.

dft_contractor_rate string

Service's default amount Contractors will be paided.

status string

Status of the Service. Check out Service Object for the types of statuses.

url string

URL to the Service object.

status string

Tender's status, choices are pending, requested, accepted, rejected, and withdrawn.

OBJECT
{   "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" }

List all Tenders

Returns of all the Tenders found on your TutorCruncher account, which are sorted by id, with the largest id first.

GET /api/tenders/

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())
RESPONSE
{   "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"     },     ...   ] }