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.

Currently users are rate limited to 100 API requests per minute so please take this into account when completing bulk operations.

We are continuously adding and improving the API by adding new endpoints and more information for existing endpoints. If there is a particular piece of information you would like access to then let us know.

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)

What are webhooks?

Webhooks are a way for TutorCruncher to push information about events to another app, for example, Zapier or your custom-built app.

When do webhooks fire?

Webhooks are fired from TutorCruncher every time an action takes place involving a user or a job. For instance, a webhook would fire when a tutor is created, or a client makes an enquiry.

Click here to view a list of all actions in TutorCruncher and what they mean

What information does a webhook contain?

The webhook contains basic information about the actions such as action (type), branch, verb, timestamp, actor and subject.The branch is the id of the associated branch. The actor is the person who performed the action within TutorCruncher. The subject is the item which the action was performed on. For example, creating/editing a Lesson will send a webhook with the details about that Lesson.

Click here to view an example of the webhook response

How can I set up webhooks?

Simply add an integration to your TutorCruncher account, System > Settings > Integrations, and add the webhook URL that you wish your webhooks to be fired to.

Webhook logs

We have webhook logs so that you can monitor any issues with them. Simply go to your integration to view them.

Webhook Object

This is an example of the webhook TutorCruncher sends to the specified URL on your integration.

RESPONSE
{     "events": [         {             "action": "CHANGED_CONTRACTOR_STATUS",             "verb": "Changed a Tutor's status",             "timestamp": "2023-04-21T09:43:09.065099Z",             "branch": 17597,             "actor": {                 "name": "Sebastian Prentice",                 "id": 1865753,                 "user_id": 1781627,                 "url": ""             },             "subject": {                 "model": "Tutor",                 "url": "https://secure.tutorcruncher.com/api/contractors/1865751/",                 "id": 1865751,                 "user": {                     "title": null,                     "first_name": "Bettie",                     "last_name": "Canales",                     "email": "bettie_canales@online-olive.example.com",                     "mobile": "07037 773 614",                     "phone": null,                     "street": "104 Robert Street",                     "state": null,                     "town": "Kings Cross",                     "country": "United Kingdom (GB)",                     "postcode": "NW1 3QP",                     "latitude": "51.5285679999999999",                     "longitude": "-0.1405610000000000",                     "date_created": "2022-08-31T14:14:20.678562Z",                     "timezone": null                 },                 "status": "pending",                 "charge_via_branch": false,                 "default_rate": null,                 "qualifications": [],                 "skills": [                     {                         "id": 1851,                         "subject": "Textiles and Fashion Design",                         "qual_level": "International Baccalaureate"                     },                     {                         "id": 345,                         "subject": "Theatre Studies",                         "qual_level": "International Baccalaureate"                     }                 ],                 "institutions": [],                 "received_notifications": [                     "service_notifications",                     "broadcasts",                     "apt_reminders",                     "apt_marked_complete_reminder"                 ],                 "review_rating": null,                 "review_duration": "00:00:00",                 "calendar_colour": "Teal",                 "labels": [],                 "extra_attrs": [                     {                         "id": 12757955,                         "value": "After work I enjoy playing spanish classical and flamenco guitar. I also perform at weddings occasionally.",                         "type": "Long Textbox",                         "machine_name": "contractor_bio",                         "name": "Bio"                     },                     {                         "id": 12757954,                         "value": "I was responsible for managing a class of 16 students, ages 7-12, and planning activities that stimulate growth in language, social, and motor skills. Bachelor of Arts in English in 2004",                         "type": "Long Textbox",                         "machine_name": "contractor_exp",                         "name": "Teaching Experience"                     }                 ],                 "work_done_details": {                     "amount_owed": 804.4,                     "amount_paid": 2230,                     "total_paid_hours": "2 02:30:00"                 }             }         }     ],     "_request_time": 1682070189 }

Signature Verification

We include a signature in the webhooks header which you can use to verify if the webhook came from TutorCruncher.

VERIFICATION

1

2

3

4

5

6

7

8

import hashlib, hmac HMAC_PRIVATE_KEY = 'YOUR_PRIVATE_API_KEY' def webhook_view(request): payload = request.body header_signature = request.META['Webhook-Signature'] assert hmac.new(HMAC_PRIVATE_KEY.encode(), payload, hashlib.sha256).hexdigest() == header_signature

Agents, Clients, Contractors, Recipients all use the user's email address as a unique identifier when creating/updating using the API. If you use the email address when creating/updating, we will check for an email address in the user data and check if this user already exists.

You can create a user without an email address, however, you will not be able to update the user. You must also include the users last name when creating/updating as this field is required. Any other role specific required fields are specified on the endpoint description.

POST

1

2

3

4

5

6

7

8

9

10

11

12

import requests headers = {'Authorization': 'token <API KEY>'} data = { 'user': { 'email': 'billy_bob@example.com', 'last_name': 'Bob' # ... }, # ... } requests.post('...', json=data, headers=headers)

Many objects in TutorCruncher can be customised with custom fields. These custom fields are stored in array called extra_attrs, you can see the shape of a custom field in an extra_attrs array in the response on the right.

However, to update a custom field you must not post this whole array. Instead, you should assign extra_attrs with an object with keys equal to custom field machine names and values equal to the new values. For example a valid payload would be: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'},

You can find the machine name of a custom field by clicking on it in your custom field settings. See creating a client for an example which sets a custom field for the Client's date of birth.

POST /api/clients/

1

2

3

4

5

6

7

8

9

10

11

12

13

14

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'user': { 'email': 'billy_bob@example.com', 'last_name': 'Bob2', 'extra_attrs': {'client_dob': '1993-06-23'}, # ... }, # ... } r = requests.post('https://secure.tutorcruncher.com/api/clients/', json=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "status": "success",   "role": {     "id": 3,     "user": {       "title": "Mr",       "first_name": "Jamie",       "last_name": "Bob2",       "email": "billy_bob@example.com",       // ...     },     // ...     "extra_attrs": [       {         "id": 1,         "value": "1993-06-23",         "type": "Date",         "machine_name": "client-dob",         "name": "Date of birth"       }     ],     // ...   } }

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.

All Action Types

LOGIN Logged in

When a User logs in.

We do not currently send webhooks for this Action

AGREE_TERMS Agreed to Terms and Conditions

When a User agrees to the Terms and Conditions.

Webhooks are sent for this Action for the following Subject Types: Tutor Affiliate Client Student

RECORDED_TERMS_CONSENT Recorded consent to Terms and Conditions

When an Administrator records consent to Terms and Conditions.

Webhooks are sent for this Action for the following Subject Types: Tutor Affiliate Student Client

REQUESTED_DELETION Requested their data be deleted

When a User has requested that they want their data to be deleted.

We do not currently send webhooks for this Action

LOGGED_OUT Logged out

When a User logs out.

We do not currently send webhooks for this Action

PW_RESET_EMAIL Requested password reset email

When a User gets sent a password reset email.

We do not currently send webhooks for this Action

PW_ENTER_NEW Entered new password

When a User resets their password.

We do not currently send webhooks for this Action

CHANGED_OWN_ROLE Changed Role

When a User switches to a different Role.

We do not currently send webhooks for this Action

UNSUBSCRIBED_FROM_EMAILS Unsubscribed from emails

When a User opts out from receiving emails.

We do not currently send webhooks for this Action

GENERATED_ACCOUNTING Generated Invoices & Payment Orders

When an Administrator generates Invoices and Payment Orders.

We do not currently send webhooks for this Action

GENERATED_PFIS Generated Credit Requests

When an Administrator generates Credit Requests.

We do not currently send webhooks for this Action

RAISED_INVOICES Raised Invoices

Occurs every time an Administrator sends Invoices.

We do not currently send webhooks for this Action

RAISED_INVOICE Raised an Invoice

Occurs once for each Invoice when an Administrator sends Invoices.

Webhooks are sent for this Action for the following Subject Types: Invoice

SENT_INVOICE_REMINDER Sent an Invoice Reminder

When an Administrator sends an Invoice Reminder.

Webhooks are sent for this Action for the following Subject Types: Invoice

CREATED_DEFERRED_PAYMENT Created a deferred payment

When an Administrator sets up a Deferred Payment.

Webhooks are sent for this Action for the following Subject Types: Credit Request Invoice

VOIDED_INVOICE Voided an Invoice

When an Administrator voids an Invoice.

Webhooks are sent for this Action for the following Subject Types: Invoice

VOIDED_PO Voided a Payment Order

When an Administrator voids a Payment Order.

Webhooks are sent for this Action for the following Subject Types: Payment Order

MARKED_INVOICE_AS_PAID Marked an Invoice as paid

When an Invoice gets marked as paid.

Webhooks are sent for this Action for the following Subject Types: Invoice

CLIENT_PAID_INVOICE Paid their Invoice

When a Client pays their Invoice.

Webhooks are sent for this Action for the following Subject Types: Credit Request Invoice

ADMIN_PAID_INVOICE Paid an Invoice

When an Administrator pays an Invoice.

Webhooks are sent for this Action for the following Subject Types: Invoice

ADMIN_QUICK_PAY_INVOICE Created a Quick Payment Invoice

When an Administrator quick pays for an Invoice.

Webhooks are sent for this Action for the following Subject Types: Invoice

ACCOUNTING_ITEM_AUTOCHARGED Charged a client using Autocharge

Occurs once for each Credit Request or Invoice when they are charged via Autocharge.

Webhooks are sent for this Action for the following Subject Types: Credit Request Invoice

RAISED_POS Raised Payment Orders

Occurs when an Administrator sends Payment Orders.

We do not currently send webhooks for this Action

RAISED_PO Raised a Payment Order

Occurs once for each Payment Order when an Administrator sends Payment Orders.

Webhooks are sent for this Action for the following Subject Types: Payment Order

RESENT_PO Resent a Payment Order

When an Administrator resends a Payment Order.

Webhooks are sent for this Action for the following Subject Types: Payment Order

MARKED_PO_AS_PAID Marked a Payment Order as paid

When an Administrator marks a Payment Order as paid.

Webhooks are sent for this Action for the following Subject Types: Payment Order

CREATED_PAYOUT Created a Payout

Occurs when a Payment Order is sent and creates a payout in Telleroo.

Webhooks are sent for this Action for the following Subject Types: Payment Order

ADDED_PO_TO_PAYRUN Added a Payment Order to a Pay Run

Occurs when a Payment Order added to a Pay Run.

We do not currently send webhooks for this Action

CREATED_PROFORMA_INVOICE Created a Credit Request

When an Administrator creates a Credit Request.

Webhooks are sent for this Action for the following Subject Types: Credit Request

CREATED_PROFORMA_INVOICE_ITEM Added an item to a Credit Request

When an Administrator creates a Credit Request Item.

Webhooks are sent for this Action for the following Subject Types: Credit Request

EDIT_PROFORMA_INVOICE Edited a Credit Request

When an Administrator edits a Credit Request.

Webhooks are sent for this Action for the following Subject Types: Credit Request

DELETED_PROFORMA_INVOICE Deleted a Credit Request

When an Administrator deletes a Credit Request.

Webhooks are sent for this Action for the following Subject Types: Credit Request

MARKED_PROFORMA_INVOICE_AS_PAID Marked Credit Request as paid

When an Administrator marks a Credit Request as paid.

Webhooks are sent for this Action for the following Subject Types: Credit Request

RAISED_PROFORMA_INVOICES Sent Credit Requests

Occurs when an Administrator sends Credit Requests.

We do not currently send webhooks for this Action

RAISED_PROFORMA_INVOICE Sent a Credit Request

Occurs once for each Credit Request when an Administrator sends Credit Requests.

Webhooks are sent for this Action for the following Subject Types: Credit Request

SENT_PROFORMA_INVOICE_REMINDER Sent a Credit Request Reminder

When an Administrator sends a Credit Request Reminder.

Webhooks are sent for this Action for the following Subject Types: Credit Request

CLIENT_PAID_PROFORMA_INVOICE Paid their Credit Request

When a Client pays their Credit Request.

Webhooks are sent for this Action for the following Subject Types: Credit Request

ADMIN_PAID_PROFORMA_INVOICE Paid a Credit Request

When an Administrator pays a Client's Credit Request.

Webhooks are sent for this Action for the following Subject Types: Credit Request

ADMIN_QUICK_PAY_PFI Created a Quick Payment Credit Request

When an Administrator creates a Quick Payment Credit Request.

Webhooks are sent for this Action for the following Subject Types: Credit Request

CREATED_ADHOC_CHARGE Created Ad Hoc Charge

When an Administrator creates an Ad Hoc Charge.

Webhooks are sent for this Action for the following Subject Types: Ad Hoc Charge

EDITED_ADHOC_CHARGE Edited Ad Hoc Charge

When an Administrator creates an Ad Hoc Charge.

Webhooks are sent for this Action for the following Subject Types: Ad Hoc Charge

DELETED_ADHOC_CHARGE Deleted Ad Hoc Charge

When an Administrator creates an Ad Hoc Charge.

We do not currently send webhooks for this Action

BALANCE_ADJUSTMENT Adjusted a Client's balance

When an Administrator adjusts a Client's Balance.

Webhooks are sent for this Action for the following Subject Types: Client

CLIENT_TOPPED_UP Client topped up

When a Client tops up their Balance.

Webhooks are sent for this Action for the following Subject Types: Client

ACCOUNTING_EXPORT Exported accounting information

When an Administrator exports a Branch's accounting information.

We do not currently send webhooks for this Action

EDITED_OWN_PROFILE Edited their own profile

When a User edits their own profile.

Webhooks are sent for this Action for the following Subject Types: Tutor Affiliate Client Student

CREATED_AN_ADMINISTRATOR Created an Administrator

When an Administrator is created.

We do not currently send webhooks for this Action

EDITED_AN_ADMINISTRATOR Edited an Administrator

When an Administrator is edited.

We do not currently send webhooks for this Action

DELETED_AN_ADMINISTRATOR Deleted an Administrator

When an Administrator is deleted.

We do not currently send webhooks for this Action

CREATED_AN_AGENT Created an Affiliate

When an Affiliate is created.

Webhooks are sent for this Action for the following Subject Types: Affiliate

EDITED_AN_AGENT Edited an Affiliate

When an Affiliate is edited.

Webhooks are sent for this Action for the following Subject Types: Affiliate

DELETED_AN_AGENT Deleted an Affiliate

When an Affiliate is deleted.

Webhooks are sent for this Action for the following Subject Types: Affiliate

CREATED_A_CLIENT Created a Client

When an Client is created.

Webhooks are sent for this Action for the following Subject Types: Client

EDITED_A_CLIENT Edited a Client

When an Client is edited.

Webhooks are sent for this Action for the following Subject Types: Client

DELETED_A_CLIENT Deleted a Client

When an Client is deleted.

Webhooks are sent for this Action for the following Subject Types: Client

CHANGED_CLIENT_STATUS Changed a Client's status

When a Client's status gets updated.

Webhooks are sent for this Action for the following Subject Types: Client

CREATED_A_CONTRACTOR Created a Tutor

When an Tutor is created.

Webhooks are sent for this Action for the following Subject Types: Tutor

EDITED_A_CONTRACTOR Edited a Tutor

When an Tutor is edited.

Webhooks are sent for this Action for the following Subject Types: Tutor

DELETED_A_CONTRACTOR Deleted a Tutor

When an Tutor is deleted.

Webhooks are sent for this Action for the following Subject Types: Tutor

CHANGED_CONTRACTOR_STATUS Changed a Tutor's status

When a Tutor's status gets updated.

Webhooks are sent for this Action for the following Subject Types: Tutor

INVITED_CONTRACTOR_FOR_INTERVIEW Invited a Tutor for an interview

When an Administrator sends a Tutor an invitation for an interview.

Webhooks are sent for this Action for the following Subject Types: Tutor

CREATED_A_SR Created a Student

When a Student is created.

Webhooks are sent for this Action for the following Subject Types: Student

EDITED_A_SR Edited a Student

When a Student is edited.

Webhooks are sent for this Action for the following Subject Types: Student

DELETED_A_SR Deleted a Student

When a Student is deleted.

Webhooks are sent for this Action for the following Subject Types: Student

IMPORTED_USERS Imported Users

When an Administrator imports Users.

We do not currently send webhooks for this Action

EDITED_SKILLS Edited Skills

When a User's skills are edited.

Webhooks are sent for this Action for the following Subject Types: Tutor

EDITED_OWN_SKILLS Edited their own Skills

When a User edits their own skills.

We do not currently send webhooks for this Action

EDITED_QUALIFICATIONS Edited Qualifications

When a User's qualifications are edited.

Webhooks are sent for this Action for the following Subject Types: Tutor

EDITED_OWN_QUALIFICATIONS Edited their own Qualifications

When a User edits their own qualifications.

We do not currently send webhooks for this Action

CREATED_A_SERVICE Created a Job

When a Job is created.

Webhooks are sent for this Action for the following Subject Types: Job

EDITED_A_SERVICE Edited a Job

When a Job is edited.

Webhooks are sent for this Action for the following Subject Types: Job

DELETED_A_SERVICE Deleted a Job

When a Job is deleted.

Webhooks are sent for this Action for the following Subject Types: Job

CHANGED_SERVICE_STATUS Changed a Job's status

When a Job's status is updated.

Webhooks are sent for this Action for the following Subject Types: Job

SENT_SERVICE_NOTIFICATIONS Sent Notifications to Tutors

When an Administrator sends Job Notifications to Tutors on the Job.

Webhooks are sent for this Action for the following Subject Types: Job

ADDED_CONTRACTOR_TO_SERVICE Added a Tutor to a Job

When a Tutor is added to a Job.

Webhooks are sent for this Action for the following Subject Types: Job

REMOVED_CONTRACTOR_FROM_SERVICE Removed a Tutor from a Job

When a Tutor is removed from a Job.

Webhooks are sent for this Action for the following Subject Types: Tutor

EDITED_CONTRACTOR_ON_SERVICE Edited a Tutor on a Job

When a Tutor on a Job is updated.

Webhooks are sent for this Action for the following Subject Types: Job

ADDED_CONTRACTOR_TO_APPOINTMENT Added a Tutor to a Lesson

When a Tutor is added to a Lesson.

Webhooks are sent for this Action for the following Subject Types: Lesson

REMOVED_CONTRACTOR_FROM_APPOINTMENT Removed a Tutor from a Lesson

When a Tutor is removed from a Lesson.

Webhooks are sent for this Action for the following Subject Types: Lesson

EDITED_CONTRACTOR_ON_APPOINTMENT Edited a Tutor on a Lesson

When a Tutor on a Lesson is updated.

Webhooks are sent for this Action for the following Subject Types: Lesson

ADDED_SR_TO_SERVICE Added a Student to a Job

When a Student is added to a Job.

Webhooks are sent for this Action for the following Subject Types: Job

REMOVED_SR_FROM_SERVICE Removed a Student from a Job

When a Student is removed from a Job.

Webhooks are sent for this Action for the following Subject Types: Student

EDITED_SR_ON_SERVICE Edited a Student on a Job

When a Student on a Job is updated.

Webhooks are sent for this Action for the following Subject Types: Job

ADDED_SR_TO_APPOINTMENT Added a Student to a Lesson

When a Student is added to a Lesson.

Webhooks are sent for this Action for the following Subject Types: Lesson

REMOVED_SR_FROM_APPOINTMENT Removed a Student from a Lesson

When a Student is removed from a Lesson.

Webhooks are sent for this Action for the following Subject Types: Lesson

EDITED_SR_ON_APPOINTMENT Edited a Student on a Lesson

When a Student on a Lesson is updated.

Webhooks are sent for this Action for the following Subject Types: Lesson

APPLIED_FOR_SERVICE Applied for a Job

When a Tutor applies for a Job.

Webhooks are sent for this Action for the following Subject Types: Job Application

EDITED_APPLICATION_FOR_SERVICE Edited their application for a Job

When a tutor edits their application for a job

Webhooks are sent for this Action for the following Subject Types: Application

WITHDREW_APPLICATION_FOR_SERVICE Withdrew their application for a Job

When a tutor withdraws their application for a job

Webhooks are sent for this Action for the following Subject Types: Application

TENDER_WAS_DECLINED Application for a Job was declined

When a tutor's application for a job has been declined

Webhooks are sent for this Action for the following Subject Types: Application

TENDER_WAS_ACCEPTED Application for a Job was accepted

When a tutor's application for a job has been accepted

Webhooks are sent for this Action for the following Subject Types: Application

CONTRACTOR_WAS_REQUESTED_FOR_SERVICE Tutor was requested for a Job

When a tutor is requested for a Job by a Client Enquiry

Webhooks are sent for this Action for the following Subject Types: Application

CREATED_AN_APPOINTMENT Created a Lesson

When a Lesson is created.

Webhooks are sent for this Action for the following Subject Types: Lesson

CREATED_A_REPEATING_APPOINTMENT Created a Repeating Lesson

Occurs for each Lesson which is created via repeated Lessons.

Webhooks are sent for this Action for the following Subject Types: Lesson

EDITED_AN_APPOINTMENT Edited a Lesson

When a Lesson is updated.

Webhooks are sent for this Action for the following Subject Types: Lesson

EDITED_REPEATED_APPOINTMENTS Edited a Lesson and all future linked Lessons

When repeated Lessons are updated.

Webhooks are sent for this Action for the following Subject Types: Lesson

DELETED_AN_APPOINTMENT Deleted a Lesson

When a Lesson is deleted.

Webhooks are sent for this Action for the following Subject Types: Lesson

MARKED_AN_APPOINTMENT_AS_COMPLETE Marked a Lesson as complete

When a Lesson is marked as complete.

Webhooks are sent for this Action for the following Subject Types: Lesson

MARKED_AN_APPOINTMENT_AS_CANCELLED Cancelled a Lesson

When a Lesson is cancelled.

Webhooks are sent for this Action for the following Subject Types: Lesson

APPOINTMENT_EXPORT Exported Lessons

When an Administrator exports data about Lessons.

We do not currently send webhooks for this Action

SERVICE_EXPORT Exported Jobs

When an Administrator exports data about Jobs.

We do not currently send webhooks for this Action

REPORTS_EXPORT Exported Reports

When an Administrator exports data about Reports.

We do not currently send webhooks for this Action

EXPORTED_USERS Exported Users

When an Administrator exports data about Users.

We do not currently send webhooks for this Action

EDITED_SYSTEM_SETTINGS Edited system settings

When an Administrator makes changes to a Branch's or Company's settings.

We do not currently send webhooks for this Action

CHANGED_TERMS Changed Terms and Conditions

When an Administrator updates the Terms and Conditions.

We do not currently send webhooks for this Action

CREATED_AGENCY Created Company

When a User sets up an Company on TutorCruncher.

We do not currently send webhooks for this Action

TERMINATED_AGENCY Company was terminated

When a Company's status is marked as Terminated.

Webhooks are sent for this Action for the following Subject Types: Client

EDITED_AVAILABILITY Edited availability

When a Tutor's availability is updated.

Webhooks are sent for this Action for the following Subject Types: Tutor

RECOVERED_AN_ADMINISTRATOR Recovered an Administrator

When an Administrator is recovered from the Trash.

We do not currently send webhooks for this Action

RECOVERED_AN_AGENT Recovered an Affiliate

When an Affiliate is recovered from the Trash.

Webhooks are sent for this Action for the following Subject Types: Affiliate

RECOVERED_A_CLIENT Recovered a Client

When a Client is recovered from the Trash.

Webhooks are sent for this Action for the following Subject Types: Client

RECOVERED_A_CONTRACTOR Recovered a Tutor

When a Tutor is recovered from the Trash.

Webhooks are sent for this Action for the following Subject Types: Tutor

RECOVERED_A_SR Recovered a Student

When a Student is recovered from the Trash.

Webhooks are sent for this Action for the following Subject Types: Student

RECOVERED_A_SERVICE Recovered a Job

When a Job is recovered from the Trash.

Webhooks are sent for this Action for the following Subject Types: Job

RECOVERED_AN_APPOINTMENT Recovered a Lesson

When a Lesson is recovered from the Trash.

Webhooks are sent for this Action for the following Subject Types: Lesson

RECOVERED_AN_EXTRA_ATTRIBUTE Recovered a Custom Field

When a Custom Field is recovered from the Trash.

We do not currently send webhooks for this Action

CREATED_A_LOCATION Created a Location

When a Location is created.

We do not currently send webhooks for this Action

EDITED_A_LOCATION Edited a Location

When a Location is edited.

We do not currently send webhooks for this Action

DELETED_A_LOCATION Deleted a Location

When a Location is deleted.

We do not currently send webhooks for this Action

CREATED_A_LABEL Created a Label

When a Label is created.

We do not currently send webhooks for this Action

EDITED_A_LABEL Edited a Label

When a Label is edited.

We do not currently send webhooks for this Action

DELETED_A_LABEL Deleted a Label

When a Label is deleted.

We do not currently send webhooks for this Action

ADDED_A_LABEL_TO_A_USER Added a Label to a User

When a Label is added to a Role/User.

Webhooks are sent for this Action for the following Subject Types: Tutor Affiliate Student Client

REMOVED_A_LABEL_FROM_A_USER Removed a Label from a User

When a Label is removed from a Role/User.

We do not currently send webhooks for this Action

CREATED_AN_EXTRA_ATTRIBUTE Created a Custom Field

When a Custom Field is created.

We do not currently send webhooks for this Action

EDITED_AN_EXTRA_ATTRIBUTE Edited a Custom Field

When a Custom Field is edited.

We do not currently send webhooks for this Action

DELETED_AN_EXTRA_ATTRIBUTE Deleted a Custom Field

When a Custom Field is deleted.

We do not currently send webhooks for this Action

IMPORTED_EXTRA_ATTRIBUTES Imported Custom Fields

When a Custom Field is imported.

We do not currently send webhooks for this Action

CHANGED_ATTRIBUTE_ORDERING Changed Custom Field Ordering

When the Custom Field order is changed.

We do not currently send webhooks for this Action

SENT_BROADCAST Sent a Broadcast

When an Administrator sends a Broadcast.

We do not currently send webhooks for this Action

SENT_BROADCAST_PREVIEW Sent a Broadcast Preview

When an Administrator sends a Broadcast Preview.

We do not currently send webhooks for this Action

CREATED_A_BROADCAST Created a Broadcast

When an Administrator creates a Broadcast.

We do not currently send webhooks for this Action

EDITED_A_BROADCAST Edited a Broadcast

When an Administrator edits a Broadcast.

We do not currently send webhooks for this Action

DELETED_A_BROADCAST Deleted a Broadcast

When an Administrator deletes a Broadcast.

We do not currently send webhooks for this Action

UPLOADED_A_CV Uploaded a Résumé

When an Administrator or Tutor uploads a Résumé.

We do not currently send webhooks for this Action

EDITED_ATTENDED_INSTITUTIONS Edited Attended Institutions

When a Tutor edits their Institutions.

Webhooks are sent for this Action for the following Subject Types: Tutor

ADDED_CUSTOM_INSTITUTION Added a Custom Institution

When an Administrator or Tutor adds a Custom Institution.

Webhooks are sent for this Action for the following Subject Types: Tutor

ADDED_A_NOTE Added a Note

When an Administrator adds a Note.

Webhooks are sent for this Action for the following Subject Types: Note

EDITED_A_NOTE Edited a Note

When an Administrator edits a Note.

Webhooks are sent for this Action for the following Subject Types: Note

DELETED_A_NOTE Deleted a Note

When an Administrator deletes a Note.

Webhooks are sent for this Action for the following Subject Types: Tutor Affiliate Client Student Job Lesson

ADDED_A_DOCUMENT Added a Document

When a User uploads a Document.

We do not currently send webhooks for this Action

EDITED_A_DOCUMENT Edited a Document

When a User edits a Document.

We do not currently send webhooks for this Action

ADDED_PUBLIC_DOCUMENT Added a Public Document

When an Administrator uploads a Public Document.

We do not currently send webhooks for this Action

CREATED_A_TASK Created a Task

When an Administrator creates a Task.

Webhooks are sent for this Action for the following Subject Types: Task

CHANGED_CLIENTS_AGENT Changed a Client's Affiliate

When a Client's Affiliate is changed.

Webhooks are sent for this Action for the following Subject Types: Client

CHANGED_CLIENT_ADMIN Changed a Client's Admin

When a Client's Client Manager is changed.

Webhooks are sent for this Action for the following Subject Types: Client

ADDED_A_CLIENT_TO_AN_AGENT Added a Client to an Affiliate

When a Client is added to an Affiliate.

Webhooks are sent for this Action for the following Subject Types: Affiliate

EDITED_A_TASK Edited a Task

When an Administrator edits a Task.

Webhooks are sent for this Action for the following Subject Types: Task

ADDED_A_LABEL_TO_A_SERVICE Added a Label to a Job

When a Label is added to a Job.

Webhooks are sent for this Action for the following Subject Types: Job

REMOVED_A_LABEL_FROM_A_SERVICE Removed a Label from a Job

When a Label is removed from a Job.

Webhooks are sent for this Action for the following Subject Types: Job

ADDED_DESIRED_SKILL Added a desired Skill to a Job

When a desired Skill is added to a Job.

Webhooks are sent for this Action for the following Subject Types: Job

EDITED_REPORT Edited a Report

When a Report is edited.

Webhooks are sent for this Action for the following Subject Types: Report

APPROVED_A_REPORT Approved a Report

When an Administrator approves a Report.

Webhooks are sent for this Action for the following Subject Types: Report

APPROVED_MULTIPLE_REPORTS Approved Reports

When an Administrator approved multiple Reports.

We do not currently send webhooks for this Action

CREATED_REPORT Created a Report

When a Report is created.

Webhooks are sent for this Action for the following Subject Types: Report

CREATED_SUBSCRIPTION Created a Subscription

When a Subscription is created.

We do not currently send webhooks for this Action

EDITED_SUBSCRIPTION Edited a Subscription

When a Subscription is edited.

We do not currently send webhooks for this Action

DELETED_SUBSCRIPTION Deleted a Subscription

When a Subscription is deleted.

We do not currently send webhooks for this Action

ADDED_CLIENT_SUBSCRIPTION Added a Client to a Subscription

When a Client is added to Subscription.

We do not currently send webhooks for this Action

REMOVED_CLIENT_SUBSCRIPTION Removed a Client from a Subscription

When a Client is removed from a Subscription.

We do not currently send webhooks for this Action

CLIENT_ENQUIRY Made an Enquiry

When a Client makes an Enquiry.

Webhooks are sent for this Action for the following Subject Types: Client

REQUESTED_A_CONTRACTOR Request a tutor

When a Client requests a Tutor in their enquiry.

Webhooks are sent for this Action for the following Subject Types: Tutor

REQUESTED_A_SERVICE Request a job

When a Client requests a Job in their enquiry.

Webhooks are sent for this Action for the following Subject Types: Job

CONTRACTOR_SIGN_UP Signed up as a Tutor

When a Tutor signs up to the Branch.

Webhooks are sent for this Action for the following Subject Types: Tutor

CLIENT_SIGN_UP Signed up as a Client

When a Client signs up to the Branch.

Webhooks are sent for this Action for the following Subject Types: Client

WELCOME_EMAIL_SENT Sent a Welcome Email

When a Welcome Email is sent to a User.

Webhooks are sent for this Action for the following Subject Types: Tutor Affiliate Client Student

ADDED_APPOINTMENT_REMINDER Added a Lesson Reminder

When a Lesson Reminder is added.

We do not currently send webhooks for this Action

CLICKED_SSO Clicked an SSO Link

When a User clicks a Single Sign On (SSO) link.

We do not currently send webhooks for this Action

CHANGED_DEFAULT_PAYMENT_CARD Changed the default payment card

When a Card is set as the Default Payment Card.

Webhooks are sent for this Action for the following Subject Types: Client

DELETED_CARD_DETAILS Deleted Card Details

When Card Details are removed from a User.

Webhooks are sent for this Action for the following Subject Types: Client

SAVED_CARD_DETAILS Saved card details

When Card Details are added to a User.

Webhooks are sent for this Action for the following Subject Types: Client

ADDED_BANK_DETAILS Added their bank details

When a Client adds their Bank Account Details.

Webhooks are sent for this Action for the following Subject Types: Tutor Client

EDITED_BANK_DETAILS Edited their bank details

When a Client edits their Bank Account Details.

Webhooks are sent for this Action for the following Subject Types: Tutor

REMOVED_BANK_DETAILS Removed their saved bank details

When a Client removes their Bank Account Details.

Webhooks are sent for this Action for the following Subject Types: Tutor Affiliate Student Client

REQUESTED_REVIEWS Requested tutor reviews

When an Administrator sends a Client a request to review a Tutor.

Webhooks are sent for this Action for the following Subject Types: Client Job

REQUESTED_AUTO_REVIEW_FROM Was asked for an automatic review for a job

When a Job review is requested automatically.

Webhooks are sent for this Action for the following Subject Types: Job

CREATED_A_REVIEW Reviewed a Tutor

When a Client creates a Review.

Webhooks are sent for this Action for the following Subject Types: Tutor

DELETED_A_REVIEW Deleted a Review

When an Administrator deletes a Client's Reivew.

We do not currently send webhooks for this Action

MOVED_PIPELINE_STAGE Moved a Client in the Pipeline

When an Administrator moves a Client in the Client Pipeline.

Webhooks are sent for this Action for the following Subject Types: Client

SENT_SERVICE_CONFIRMATION_CLIENT Sent a job confirmation email to a client

When a Job Confirmation Email is sent to a Client.

Webhooks are sent for this Action for the following Subject Types: Job

SENT_SERVICE_CONFIRMATION_CONTRACTOR Sent a job confirmation email to a tutor

When a Job Confirmation Email is sent to a Tutor.

Webhooks are sent for this Action for the following Subject Types: Job

BOOKED_AN_APPOINTMENT Booked a Lesson

When a Client books a Lesson.

Webhooks are sent for this Action for the following Subject Types: Lesson

CANCELLED_A_BOOKING Cancelled a booking

When a client cancels a booked Lesson.

Webhooks are sent for this Action for the following Subject Types: Lesson

CANCELLED_DEFERRED_PAYMENT Cancelled a deferred payment

When a Deferred Payment is cancelled.

Webhooks are sent for this Action for the following Subject Types: Credit Request Invoice

DEFERRED_PAYMENT_FAILED A deferred payment failed

When a Deferred Payment Fails.

Webhooks are sent for this Action for the following Subject Types: Credit Request Invoice

PAYMENT_FAILED A payment failed

When a Payment Fails.

Webhooks are sent for this Action for the following Subject Types: Credit Request Invoice

CHANGED_BILLING_PLAN Changed their price plan

When a Company updates their Billing Plan.

We do not currently send webhooks for this Action

CHANGED_SUPPORT_PLAN Changed their support plan

When a Company updates their Support Plan.

We do not currently send webhooks for this Action

SWITCH_BRANCH Switched to another Branch

When a User switches to a different Branch.

We do not currently send webhooks for this Action

COPY_ROLE Copied a Role to another Branch

When a Role is copied over to a different Branch.

Webhooks are sent for this Action for the following Subject Types: Tutor Affiliate Client Student

SENT_ONE_OFF_EMAIL Sent a one off Email

When an Administrator sends a User a One Off Email.

Webhooks are sent for this Action for the following Subject Types: Tutor Affiliate Client Student

REQUESTED_JS_REVIEW Requested a JavaScript review

When an Administrator sends his JavaScript to be reviewed.

We do not currently send webhooks for this Action

SENT_CLIENT_APT_SCHEDULE Sent a Client their Lesson schedule

When a Client is sent their Lesson Schedule.

Webhooks are sent for this Action for the following Subject Types: Client

AGENCY_IN_ARREARS Company status set to In Arrears

When a Company's status is set to In Arrears.

We do not currently send webhooks for this Action

TRIAL_ENDING_SOON_EMAIL Was sent a trial expiring email

When a Company's Trial expires they will receive an email.

We do not currently send webhooks for this Action

CONTRACTOR_WAS_CREATED_API Was created through the API

When a Tutor is created through the API.

Webhooks are sent for this Action for the following Subject Types: Tutor

CLIENT_WAS_CREATED_API Was created through the API

When a Client is created through the API.

Webhooks are sent for this Action for the following Subject Types: Client

SR_WAS_CREATED_API Was created through the API

When a Student is created through the API.

Webhooks are sent for this Action for the following Subject Types: Student

AGENT_WAS_CREATED_API Was created through the API

When a Affiliate is created through the API.

Webhooks are sent for this Action for the following Subject Types: Affiliate

GENERATED_PAYRUN_EXPORT Generated a Pay Run Export

When an Admin generates a Pay Run export

We do not currently send webhooks for this Action

FAILED_LOGIN_ATTEMPT Failed to log in

When someone attempts to login into an account with the wrong password.

We do not currently send webhooks for this Action

EDITED_AGENCY_DETAILS Edited an agency's details

When an agency's details have been edited

Webhooks are sent for this Action for the following Subject Types: Client

EDITED_PRICE_PLAN Edited an agency's price plan

When an agency's price plan has been edited

Webhooks are sent for this Action for the following Subject Types: Client

EXPORTED_AHCS Exported Ad Hoc Charges

When someone exports a list of Ad Hoc Charges

We do not currently send webhooks for this Action

TRANSFER_CREATED Received a transfer to their Stripe account

When a tutor/branch receives money into their Stripe account

We do not currently send webhooks for this Action

SUPPORT_OTP_CONFIRMED Confirmed a support OTP code

When someone confirms their OTP code over the phone

We do not currently send webhooks for this Action

EXPORTED_CX_FEED Exported Stripe feed

When someone exports their Stripe bank feed

We do not currently send webhooks for this Action

CREATED_LESSON_RECORDING Created a Lesson Recording

When a lesson recording has been created.

We do not currently send webhooks for this Action

DELETED_LESSON_RECORDING Deleted a Lesson Recording details

When a lesson recording has been deleted.

We do not currently send webhooks for this Action

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": "AGREE_TERMS",     "value": "AGREE_TERMS",     "msg": "Agreed to Terms and Conditions",     "help_text": "When a User agrees to the Terms and Conditions.",     "subject_types": [       "Tutor",       "Affiliate",       "Client",       "Student"     ]   },   ... ]

Ad Hoc Charge 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 category and 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 object

Object that contains information about the Service. Attributes in the object are id, name, dft_charge_type, created, dft_charge_rate, dft_conractor_rate, last_updated, status, url.

url string

URL to the Appointment object.

category object

Object of the Ad Hoc Charge Category.

Show child attributes
id integer

Unique identifier for the object.

name string

Name of the Ad Hoc Charge Category.

branch_tax_setup string

Tax setup for the Branch when invoicing.

charge_via_branch boolean

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

contractor_tax_setup string

Tax setup for the Contractors when invoicing.

contractor_usable boolean

If Contractors can use the category for expenses.

default_charge_amount decimal

Default charge_client amount for the Ad Hoc Charge Category.

default_description string

Default description for the Ad Hoc Charge Category.

default_pay_amount decimal

Default pay_contractor amount for the Ad Hoc Charge Category.

dft_net_gross string

Default net/gross value for the Ad Hoc Charge Category.

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": {     "branch_tax_setup": "Default Company Tax (20%)",     "charge_via_branch": true,     "contractor_tax_setup": "Default Company Tax (20%)",     "contractor_usable": true,     "default_charge_amount": "10.00",     "default_description": "Fee for registering on the course",     "default_pay_amount": "10.00",     "dft_net_gross": "net",     "id": 7,     "name": "Registration fee"   },   "category_id": 7,   "category_name": "Registration fee",   "charge_client_forex": null,   "client_cost": "25.00",   "client": {     "id": 37,     "first_name": "Nicole",     "last_name": "Beggs",     "email": "nicole_beggs@example.com",     "url": "https://secure.tutorcruncher.com/api/clients/37/"   },   "contractor": null,   "creator": null,   "currency": "GBP",   "currency_conversion": null,   "date_occurred": "2019-12-23T16:11:48.312507Z",   "invoices": [     {       "id": 49,       "display_id": "INV-49",       "date_sent": "2020-01-03T16:11:48.312507Z",       "gross": "1059.95",       "net": 883.29,       "tax": "176.66",       "client": {         "id": 37,         "first_name": "Nicole",         "last_name": "Beggs",         "email": "nicole_beggs@example.com",         "url": "https://secure.tutorcruncher.com/api/clients/37/"       },       "status": "paid",       "url": "https://secure.tutorcruncher.com/api/invoices/49/"     }   ],   "payment_orders": [],   "net_gross": "gross",   "pay_contractor": null,   "service": {     "id": 26,     "name": "UK tax law",     "dft_charge_type": "hourly",     "created": "2019-12-19T16:11:48.312507Z",     "dft_charge_rate": "95.00",     "dft_contractor_rate": "30.00",     "status": "in-progress",     "url": "https://secure.tutorcruncher.com/api/services/26/"   },   "tax_amount": 4.166666666666667 }

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": "Registration fee.",       "date_occurred": "2020-01-01T12:00:00.000000Z",       "category_id": 7,       "category_name": "Registration fee",       "client_cost": "25.00",       "pay_contractor": "20.00",       "agent_percentage": null,       "url": "https://secure.tutorcruncher.com/api/adhoccharges/32/"     },     ...   ] }

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": {     "branch_tax_setup": "Default Company Tax (20%)",     "charge_via_branch": true,     "contractor_tax_setup": "Default Company Tax (20%)",     "contractor_usable": true,     "default_charge_amount": "10.00",     "default_description": "Fee for registering on the course",     "default_pay_amount": "10.00",     "dft_net_gross": "net",     "id": 7,     "name": "Registration fee"   },   "category_id": 7,   "category_name": "Registration fee",   "charge_client_forex": null,   "client_cost": "25.00",   "client": {     "id": 37,     "first_name": "Nicole",     "last_name": "Beggs",     "email": "nicole_beggs@example.com",     "url": "https://secure.tutorcruncher.com/api/clients/37/"   },   "contractor": null,   "creator": null,   "currency": "GBP",   "currency_conversion": null,   "date_occurred": "2019-12-23T16:11:48.312507Z",   "invoices": [     {       "id": 49,       "display_id": "INV-49",       "date_sent": "2020-01-03T16:11:48.312507Z",       "gross": "1059.95",       "net": 883.29,       "tax": "176.66",       "client": {         "id": 37,         "first_name": "Nicole",         "last_name": "Beggs",         "email": "nicole_beggs@example.com",         "url": "https://secure.tutorcruncher.com/api/clients/37/"       },       "status": "paid",       "url": "https://secure.tutorcruncher.com/api/invoices/49/"     }   ],   "payment_orders": [],   "net_gross": "gross",   "pay_contractor": null,   "service": {     "id": 26,     "name": "UK tax law",     "dft_charge_type": "hourly",     "created": "2019-12-19T16:11:48.312507Z",     "dft_charge_rate": "95.00",     "dft_contractor_rate": "30.00",     "status": "in-progress",     "url": "https://secure.tutorcruncher.com/api/services/26/"   },   "tax_amount": 4.166666666666667 }

Create an Ad Hoc Charge

Creating an Ad Hoc Charge can be completed by simply supplying the date_occurred, category, description and either both charge_client and client or pay_contractor and contractor.

POST /api/adhoccharges/

1

2

3

4

5

6

7

8

9

10

11

12

13

import pprint, requests, datetime headers = {'Authorization': 'token <API KEY>'} data = { 'service': 26, 'client': 37, 'charge_client': 25, 'category': 7, 'date_occurred': datetime.datetime(2021, 1, 1), 'description': 'Registration fee' } r = requests.post('https://secure.tutorcruncher.com/api/adhoccharges/', data=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "id": 32,   "agent": null,   "appointment": null,   "category": {     "branch_tax_setup": "Default Company Tax (20%)",     "charge_via_branch": true,     "contractor_tax_setup": "Default Company Tax (20%)",     "contractor_usable": true,     "default_charge_amount": "10.00",     "default_description": "Fee for registering on the course",     "default_pay_amount": "10.00",     "dft_net_gross": "net",     "id": 7,     "name": "Registration fee"   },   "category_id": 7,   "category_name": "Registration fee",   "charge_client_forex": null,   "client_cost": "25.00",   "client": {     "id": 37,     "first_name": "Nicole",     "last_name": "Beggs",     "email": "nicole_beggs@example.com",     "url": "https://secure.tutorcruncher.com/api/clients/37/"   },   "contractor": null,   "creator": {     "email": "billy_holiday@example.com",     "first_name": "Billy",     "id": 59,     "last_name": "Holiday"   },   "currency": "GBP",   "currency_conversion": null,   "date_occurred": "2021-01-01T00:00:00Z",   "invoices": [],   "payment_orders": [],   "net_gross": "gross",   "pay_contractor": null,   "service": {     "id": 26,     "name": "UK tax law",     "dft_charge_type": "hourly",     "created": "2021-01-01 T16:11:48.312507Z",     "dft_charge_rate": "95.00",     "dft_contractor_rate": "30.00",     "status": "in-progress",     "url": "https://secure.tutorcruncher.com/api/services/26/"   },   "tax_amount": 4.166666666666667 }

Update an Ad Hoc Charge

Updating an Ad Hoc Charge can be completed by simply supplying the date_occurred, category, description, any fields to update and include the id in the url.

PUT /api/adhoccharges/<id>/

1

2

3

4

5

6

7

8

9

10

11

12

13

import pprint, requests, datetime headers = {'Authorization': 'token <API KEY>'} data = { 'service': 26, 'client': 37, 'charge_client': 25, 'category': 7, 'date_occurred': datetime.datetime(2021, 1, 1), 'description': 'Registration fee' } r = requests.put('https://secure.tutorcruncher.com/api/adhoccharges/<id>/', data=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "id": 32,   "agent": null,   "appointment": null,   "category": {     "branch_tax_setup": "Default Company Tax (20%)",     "charge_via_branch": true,     "contractor_tax_setup": "Default Company Tax (20%)",     "contractor_usable": true,     "default_charge_amount": "10.00",     "default_description": "Fee for registering on the course",     "default_pay_amount": "10.00",     "dft_net_gross": "net",     "id": 7,     "name": "Registration fee"   },   "category_id": 7,   "category_name": "Registration fee",   "charge_client_forex": null,   "client_cost": "25.00",   "client": {     "id": 37,     "first_name": "Nicole",     "last_name": "Beggs",     "email": "nicole_beggs@example.com",     "url": "https://secure.tutorcruncher.com/api/clients/37/"   },   "contractor": null,   "creator": {     "email": "billy_holiday@example.com",     "first_name": "Billy",     "id": 59,     "last_name": "Holiday"   },   "currency": "GBP",   "currency_conversion": null,   "date_occurred": "2021-01-01T00:00:00Z",   "invoices": [],   "payment_orders": [],   "net_gross": "gross",   "pay_contractor": null,   "service": {     "id": 26,     "name": "UK tax law",     "dft_charge_type": "hourly",     "created": "2021-01-01 T16:11:48.312507Z",     "dft_charge_rate": "95.00",     "dft_contractor_rate": "30.00",     "status": "in-progress",     "url": "https://secure.tutorcruncher.com/api/services/26/"   },   "tax_amount": 4.166666666666667 }

Delete an Ad Hoc Charge

Deletes an Ad Hoc Charge and returns the details of an existing ah hoc charge. You only need to specify the unique id of the ad hoc charge in the url to achieve this.

DELETE /api/adhoccharges/<id>/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.delete('https://secure.tutorcruncher.com/api/adhoccharges/<id>/', headers=headers) pprint.pprint(r.json())
RESPONSE
{   "message": "Successfully deleted Ad Hoc Charge 37: Registration fee" }

Ad Hoc Charge Category Object

Returns the details of an existing Ah Hoc Charge Category. You only need to send a get request to the Ad Hoc Charge Categories url to get a list of available Categories.

Attributes

id integer

Unique identifier for the object.

name string

Name of the Ad Hoc Charge Category.

branch_tax_setup string

Tax setup for the Branch when invoicing.

charge_via_branch boolean

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

contractor_tax_setup string

Tax setup for the Contractors when invoicing.

contractor_usable boolean

If Contractors can use the category for expenses.

default_charge_amount decimal

Default charge_client amount for the Ad Hoc Charge Category.

default_description string

Default description for the Ad Hoc Charge Category.

default_pay_amount decimal

Default pay_contractor amount for the Ad Hoc Charge Category.

dft_net_gross string

Default net/gross value for the Ad Hoc Charge Category.

OBJECT
{   "branch_tax_setup": "Default Company Tax (20%)",   "charge_via_branch": true,   "contractor_tax_setup": "Default Company Tax (20%)",   "contractor_usable": true,   "default_charge_amount": "10.00",   "default_description": "Fee for registering on the course",   "default_pay_amount": "10.00",   "dft_net_gross": "net",   "id": 7,   "name": "Registration fee" }

List all Ad Hoc Charges Categories

Returns a list of your Ad Hoc Charges Categories. The Ad Hoc Charges Categories are sorted by id, with the smallest id first.

GET /api/ahc-categories/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.get('https://secure.tutorcruncher.com/api/ahc-categories/', headers=headers) pprint.pprint(r.json())
RESPONSE
{   "count": 32,   "next": null,   "previous": null,   "results": [     {       "branch_tax_setup": "Default Company Tax (20%)",       "charge_via_branch": true,       "contractor_tax_setup": "Default Company Tax (20%)",       "contractor_usable": true,       "default_charge_amount": "10.00",       "default_description": "Fee for registering on the course",       "default_pay_amount": "10.00",       "dft_net_gross": "net",       "id": 7,       "name": "Registration fee"     },     ...   ] }

Agent 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.

Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}

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.

Filters

created__gte string

Filter by the date and time the Agent was created.

created__lte string

Filter by the date and time the Agent was created.

first_name string

Filter by the Agent's first name.

last_name string

Filter by the Agent's last name.

email string

Filter by the Agent's email address.

status string

Filter by the Agent's status.

distance_address string

Filter by the address.

distance_radius integer

Filter by the radius of the address. This is used in conjunction with the address filter.

labels integer

Filter by the Agent's labels.

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.

Check out Creating/Updating Users for more information on linking to a specific user.

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': {'user_dob': '1993-06-23'}, 'send_emails': True, } r = requests.post('https://secure.tutorcruncher.com/api/agents/', json=data, headers=headers) pprint.pprint(r.json())
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": [       {         "id": 1,         "value": "1993-06-23",         "type": "Date",         "machine_name": "user-dob",         "name": "Date of birth"       }     ]   } }

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.

Check out Creating/Updating Users for more information on linking to a specific user.

POST /api/agents/

1

2

3

4

5

6

7

8

9

10

11

12

13

14

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'user': { 'email': 'billy_bob@example.com', 'last_name': 'Bob2', # ... }, 'extra_attrs': {'user_dob': '1993-06-23'}, # ... } r = requests.post('https://secure.tutorcruncher.com/api/agents/', json=data, headers=headers) pprint.pprint(r.json())
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": [       {         "id": 1,         "value": "1993-06-23",         "type": "Date",         "machine_name": "user-dob",         "name": "Date of birth"       }     ]   } }

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.

status string

The status of the student for that Appointment. Normally is attended, but can be different for group lessons where one or more students might have cancelled/not turned up but the Appointment still went ahead. This field is currently read_only, and cannot be changed through the API. If you would like this to change, please email devteam@tutorcruncher.com.

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 object

Object that contains information about the Service. Attributes in the object are id, name, dft_charge_type, created, dft_charge_rate, dft_conractor_rate, last_updated, status, url.

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",       "status": "attended"     }   ],   "cjas": [     {       "contractor": 43,       "contractor_name": "Billy Holiday",       "pay_rate": "80.00"     }   ],   "status": "Planned",   "repeater": null,   "service": {                 "id": 699444,                 "name": "test",                 "dft_charge_type": "hourly",                 "created": "2023-03-15T17:37:46.829300Z",                 "dft_charge_rate": "12.00",                 "dft_contractor_rate": "21.00",                 "last_updated": "2023-03-15T17:38:02.989696Z",                 "status": "available",                 "url": "https://secure.tutorcruncher.com/api/services/699444/"             },   "charge_type": "Hourly" }

List all Appointments

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

Filters

start_gte string

Filter by the date and time the Appointment was started.

start_lte string

Filter by the date and time the Appointment was ended.

service integer

Filter by the Appointment's linked Job (id).

contractor string

Filter by the Appointment's linked Tutor (id).

recipient integer

Filter by the Appointment's recipient email address (id).

location integer

Filter by the Appointment's location (id).

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": 699444,                 "name": "test",                 "dft_charge_type": "hourly",                 "created": "2023-03-15T17:37:46.829300Z",                 "dft_charge_rate": "12.00",                 "dft_contractor_rate": "21.00",                 "last_updated": "2023-03-15T17:38:02.989696Z",                 "status": "available",                 "url": "https://secure.tutorcruncher.com/api/services/699444/"             },       "url": "https://secure.tutorcruncher.com/api/appointments/10/"     },     ...   ] }

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",       "status": "attended"     }   ],   "cjas": [     {       "contractor": 43,       "contractor_name": "Billy Holiday",       "pay_rate": "80.00"     }   ],   "status": "Planned",   "repeater": null,   "service": {                 "id": 699444,                 "name": "test",                 "dft_charge_type": "hourly",                 "created": "2023-03-15T17:37:46.829300Z",                 "dft_charge_rate": "12.00",                 "dft_contractor_rate": "21.00",                 "last_updated": "2023-03-15T17:38:02.989696Z",                 "status": "available",                 "url": "https://secure.tutorcruncher.com/api/services/699444/"             },   "charge_type": "Hourly" }

Creating an Appointment

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",       "status": "attended"     }   ],   "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",       "status": "attended"     }   ],   "cjas": [     {       "contractor": 43,       "contractor_name": "Billy Holiday",       "pay_rate": "80.00"     }   ],   "status": "Planned",   "repeater": null,   "service": {                 "id": 699444,                 "name": "test",                 "dft_charge_type": "hourly",                 "created": "2023-03-15T17:37:46.829300Z",                 "dft_charge_rate": "12.00",                 "dft_contractor_rate": "21.00",                 "last_updated": "2023-03-15T17:38:02.989696Z",                 "status": "available",                 "url": "https://secure.tutorcruncher.com/api/services/699444/"             },   "charge_type": "Hourly" }

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": 699444,                 "name": "test",                 "dft_charge_type": "hourly",                 "created": "2023-03-15T17:37:46.829300Z",                 "dft_charge_rate": "12.00",                 "dft_contractor_rate": "21.00",                 "last_updated": "2023-03-15T17:38:02.989696Z",                 "status": "available",                 "url": "https://secure.tutorcruncher.com/api/services/699444/"             },   "charge_type": "Hourly" }

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": 699444,                 "name": "test",                 "dft_charge_type": "hourly",                 "created": "2023-03-15T17:37:46.829300Z",                 "dft_charge_rate": "12.00",                 "dft_contractor_rate": "21.00",                 "last_updated": "2023-03-15T17:38:02.989696Z",                 "status": "available",                 "url": "https://secure.tutorcruncher.com/api/services/699444/"             },   "charge_type": "Hourly" }

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": 699444,                 "name": "test",                 "dft_charge_type": "hourly",                 "created": "2023-03-15T17:37:46.829300Z",                 "dft_charge_rate": "12.00",                 "dft_contractor_rate": "21.00",                 "last_updated": "2023-03-15T17:38:02.989696Z",                 "status": "available",                 "url": "https://secure.tutorcruncher.com/api/services/699444/"             },   "charge_type": "Hourly" }

Branch Object

The Branch Object contains information related to a physical location. It includes details such as the id of the branch, name of the branch, its agency information which includes the id, name, blurb, status, created, and url_slug of the agency associated with the branch. The created field represents the date and time the branch was created. Other fields of the Branch object include country, currency, demo, longitude, latitude, page_logo, phone, postcode, street, timezone, town, and website. These fields provide additional information about the branch location, such as the country, currency used in the branch, whether it's a demo branch or not, its location coordinates, logo, phone number, postcode, street, timezone, town, and website URL.

Attributes

id integer

Unique identifier for the Branch object.

agency object

Object of the agency associated with the branch.

Show child attributes
id integer

Unique identifier for the agency object.

blurb string

Brief description of the agency.

created string

Date and time when the agency was created.

login_url string

URL to the agency's login page.

name string

The name of the agency.

status string

Status of the agency, choices are active-paying, active-not-paying, archived, or deleted.

url_slug string

The URL slug for the agency.

country string

The country where the branch is located.

created string

Date and time when the branch was created.

currency string

The currency used in the branch.

datetime_output_formats object

Object containing the datetime output formats for the branch.

Show child attributes
date_name string

The date format for display.

dj_date array

Array of Django date formats.

mt_date string

Moment.js date format.

tpl_date string

The date format for templates.

time_name string

The time format for display.

dj_time array

Array of Django time formats.

mt_time string

Moment.js time format.

tpl_time string

The time format for templates.

tpl_datetime string

The datetime format for templates.

tpl_datetime_short string

The short datetime format for templates.

day_first boolean

If True, the day comes before the month in date formats.

cal_date_display string

The date format for the calendar.

display_input string

The datetime format for display.

dj_datetime array

Array of Django datetime formats.

mt_datetime string

Moment.js datetime format.

datetime_name string

The datetime format for display.

demo boolean

If True, the branch is a demo branch.

longitude float

The longitude of the branch location.

latitude float

The latitude of the branch location.

name string

The name of the branch.

page_logo string

The URL of the branch's logo.

phone string

The phone number of the branch.

postcode string

The postcode of the branch.

street string

The street address of the branch.

timezone string

The timezone of the branch.

town string

The town of the branch.

website string

The website of the branch.

OBJECT
{     "id": 17597,     "agency": {         "id": 9214,         "blurb": "",         "created": "2022-10-19T10:14:20.034536-04:00",         "login_url": "/online-olive/login/",         "name": "online olive",         "status": "active-not-paying",         "url_slug": "online-olive"     },     "country": "United Kingdom",     "created": "2022-10-19T10:14:20.687490-04:00",     "currency": "GBP",     "datetime_output_formats": {         "date_name": "dd/mm/yyyy",         "dj_date": [             "%d/%m/%Y",             "%d/%m/%y",             "%Y-%m-%d"         ],         "mt_date": "DD/MM/YYYY",         "tpl_date": "%d/%m/%Y",         "time_name": "HH:MM",         "dj_time": [             "%H:%M",             "%H:%M:%S"         ],         "mt_time": "HH:mm",         "tpl_time": "%H:%M",         "tpl_datetime": "%d/%m/%Y %H:%M",         "tpl_datetime_short": "%d/%m %H:%M",         "day_first": true,         "cal_date_display": "ddd DD/MM",         "display_input": "25/7/2014 14:30",         "dj_datetime": [             "%d/%m/%Y %H:%M",             "%d/%m/%Y %H:%M:%S",             "%d/%m/%y %H:%M",             "%d/%m/%y %H:%M:%S",             "%Y-%m-%d %H:%M",             "%Y-%m-%d %H:%M:%S"         ],         "mt_datetime": "DD/MM/YYYY HH:mm",         "datetime_name": "dd/mm/yyyy HH:MM"     },     "demo": true,     "longitude": null,     "latitude": null,     "name": "Demo Branch",     "page_logo": null,     "phone": null,     "postcode": "SW1W 0EN",     "street": "Testing House, Demo street",     "timezone": "Europe/London",     "town": "London",     "website": "http://test.test.com" }

Client 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.

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.

Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}

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

Filters

created__gte string

Filter by the date and time the Client was created.

created__lte string

Filter by the date and time the Client was created.

first_name string

Filter by the Client's first name.

last_name string

Filter by the Client's last name.

email string

Filter by the Client's email address.

status string

Filter by the Client's status.

distance_address string

Filter by the address.

distance_radius integer

Filter by the radius of the address. This is used in conjunction with the address filter.

labels integer

Filter by the Client's labels (id).

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,   "pipeline_stage": null,   "paid_recipients": [     {       "id": 4,       "first_name": "Arthur",       "last_name": "Hoskins",       "email": "arthur_hoskins@example.com",       "url": "https://secure.tutorcruncher.com/api/recipients/4/"     },     {       "id": 6,       "first_name": "Harry",       "last_name": "Hoskins",       "email": "harry_hoskins@example.com",       "url": "https://secure.tutorcruncher.com/api/recipients/6/"     },     {       "id": 5,       "first_name": "Archie",       "last_name": "Hoskins",       "email": "archie_hoskins@example.com",       "url": "https://secure.tutorcruncher.com/api/recipients/5/"     }   ],   "calendar_colour": "ForestGreen",   "labels": [],   "extra_attrs": [     {       "id": 1,       "value": "",       "type": "Date",       "machine_name": "client-dob",       "name": "Date of birth"     }   ],   "invoice_balance": "-120.00",   "available_balance": "-220.50" }

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.

Check out Creating/Updating Users for more information on linking to a specific user.

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': {'client_dob': '1993-06-23'}, 'send_emails': True, } r = requests.post('https://secure.tutorcruncher.com/api/clients/', json=data, headers=headers) pprint.pprint(r.json())
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": "1993-06-23",         "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.

Check out Creating/Updating Users for more information on linking to a specific user.

POST /api/clients/

1

2

3

4

5

6

7

8

9

10

11

12

13

14

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'user': { 'email': 'billy_bob@example.com', 'last_name': 'Bob2', # ... }, 'extra_attrs': {'client_dob': '1993-06-23'}, # ... } r = requests.post('https://secure.tutorcruncher.com/api/clients/', json=data, headers=headers) pprint.pprint(r.json())
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/"       }     ],     "calendar_colour": "ForestGreen",     "labels": [],     "extra_attrs": [       {         "id": 1,         "value": "1993-06-23",         "type": "Date",         "machine_name": "client-dob",         "name": "Date of birth"       }     ],     "invoice_balance": "-120.00",     "available_balance": "-220.50"   } }

Contractor 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.

Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}

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.

Filters

created__gte string

Filter by the date and time the Contractor was created.

created__lte string

Filter by the date and time the Contractor was created.

first_name string

Filter by the Contractor's first name.

last_name string

Filter by the Contractor's last name.

email string

Filter by the Contractor's email address.

status string

Filter by the Contractor's status.

address string

Filter by the address.

radius integer

Filter by the radius of the address. This is used in conjunction with the address filter.

labels integer

Filter by the Contractor's labels (id).

skills integer

Filter by the Contractor's skills (id).

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.

Check out Creating/Updating Users for more information on linking to a specific user.

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': {'user_dob': '1993-06-23'}, 'send_emails': True, } r = requests.post('https://secure.tutorcruncher.com/api/contractors/', json=data, headers=headers) pprint.pprint(r.json())
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": [       {         "id": 1,         "value": "1993-06-23",         "type": "Date",         "machine_name": "user-dob",         "name": "Date of birth"       }     ],     "work_done_details": {       "amount_owed": 264.49,       "amount_paid": 175.0,       "total_paid_hours": "05:00:00"     }   } }

Update a Contractor

Update a Contractor object by supplying the email address as the unique identifier. You must also supply required fields like last_name even if they are not being updated. You only need to post information that you want to change and not the whole Contractor object.

Check out Creating/Updating Users for more information on linking to a specific user.

POST /api/contractors/

1

2

3

4

5

6

7

8

9

10

11

12

13

14

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'user': { 'email': 'billy_bob@example.com', 'last_name': 'Bob2', # ... }, 'extra_attrs': {'user_dob': '1993-06-23'} # ... } r = requests.post('https://secure.tutorcruncher.com/api/contractors/', json=data, headers=headers) pprint.pprint(r.json())
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": [       {         "id": 1,         "value": "1993-06-23",         "type": "Date",         "machine_name": "user-dob",         "name": "Date of birth"       }     ],     "work_done_details": {       "amount_owed": 264.49,       "amount_paid": 175.0,       "total_paid_hours": "05:00:00"     }   } }

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, url, it also contains a service object.

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": 699444,                 "name": "test",                 "dft_charge_type": "hourly",                 "created": "2023-03-15T17:37:46.829300Z",                 "dft_charge_rate": "12.00",                 "dft_contractor_rate": "21.00",                 "last_updated": "2023-03-15T17:38:02.989696Z",                 "status": "available",                 "url": "https://secure.tutorcruncher.com/api/services/699444/"             },         "url": "https://secure.tutorcruncher.com/api/appointments/251/"       },       "date": "2019-12-31T13:30:33.173982Z",       "payee": "Demo Branch",       "payer": {         "id": 35,         "first_name": "Melissa",         "last_name": "Spencer",         "email": "melissa_spencer@example.com",         "url": "https://secure.tutorcruncher.com/api/clients/35/"       },       "rate": "95.00000",       "sales_code": "200",       "tax_amount": "23.75000",       "units": "1.50000"     },     {       "adhoc_charge": null,       "amount": "142.50000",       "appointment": {         "id": 250,         "start": "2019-12-24T12:00:33.173982Z",         "finish": "2019-12-24T13:30:33.173982Z",         "topic": "Microelectronics and application of semiconductors 1",         "status": 20,         "service": {                 "id": 699444,                 "name": "test",                 "dft_charge_type": "hourly",                 "created": "2023-03-15T17:37:46.829300Z",                 "dft_charge_rate": "12.00",                 "dft_contractor_rate": "21.00",                 "last_updated": "2023-03-15T17:38:02.989696Z",                 "status": "available",                 "url": "https://secure.tutorcruncher.com/api/services/699444/"             },         "url": "https://secure.tutorcruncher.com/api/appointments/250/"       },       "date": "2019-12-24T13:30:33.173982Z",       "payee": "Demo Branch",       "payer": {         "id": 35,         "first_name": "Melissa",         "last_name": "Spencer",         "email": "melissa_spencer@example.com",         "url": "https://secure.tutorcruncher.com/api/clients/35/"       },       "rate": "95.00000",       "sales_code": "200",       "tax_amount": "23.75000",       "units": "1.50000"     }   ],   "client": {     "id": 35,     "first_name": "Melissa",     "last_name": "Spencer",     "email": "melissa_spencer@example.com",     "url": "https://secure.tutorcruncher.com/api/clients/35/"   },   "date_sent": "2020-01-03T16:11:48.312507Z",   "date_void": null,   "date_paid": "2020-02-03T16:11:48.312507Z",   "display_id": "INV-48",   "gross": "340.90",   "net": 284.08,   "status": "paid",   "still_to_pay": 0.0,   "tax": "56.82" }

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": 22,         "display_id": "INV-2",         "gross": "100.00",         "net": 92.5,         "tax": "7.50",         "date_sent": "2020-01-01T00:00:00Z",         "client": {             "id": 52,             "first_name": "Jane",             "last_name": "cli_a",             "email": "testing+cli_a@tutorcruncher.com",             "url": "https://secure.tutorcruncher.com/api/clients/52/"         },         "status": "unpaid",         "url": "https://secure.tutorcruncher.com/api/invoices/22/"     },     ...   ] }

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": 699444,                 "name": "test",                 "dft_charge_type": "hourly",                 "created": "2023-03-15T17:37:46.829300Z",                 "dft_charge_rate": "12.00",                 "dft_contractor_rate": "21.00",                 "last_updated": "2023-03-15T17:38:02.989696Z",                 "status": "available",                 "url": "https://secure.tutorcruncher.com/api/services/699444/"             },         "url": "https://secure.tutorcruncher.com/api/appointments/251/"       },       "date": "2019-12-31T13:30:33.173982Z",       "payee": "Demo Branch",       "payer": {         "id": 35,         "first_name": "Melissa",         "last_name": "Spencer",         "email": "melissa_spencer@example.com",         "url": "https://secure.tutorcruncher.com/api/clients/35/"       },       "rate": "95.00000",       "sales_code": "200",       "tax_amount": "23.75000",       "units": "1.50000"     },     {       "adhoc_charge": null,       "amount": "142.50000",       "appointment": {         "id": 250,         "start": "2019-12-24T12:00:33.173982Z",         "finish": "2019-12-24T13:30:33.173982Z",         "topic": "Microelectronics and application of semiconductors 1",         "status": 20,         "service": {                 "id": 699444,                 "name": "test",                 "dft_charge_type": "hourly",                 "created": "2023-03-15T17:37:46.829300Z",                 "dft_charge_rate": "12.00",                 "dft_contractor_rate": "21.00",                 "last_updated": "2023-03-15T17:38:02.989696Z",                 "status": "available",                 "url": "https://secure.tutorcruncher.com/api/services/699444/"             },         "url": "https://secure.tutorcruncher.com/api/appointments/250/"       },       "date": "2019-12-24T13:30:33.173982Z",       "payee": "Demo Branch",       "payer": {         "id": 35,         "first_name": "Melissa",         "last_name": "Spencer",         "email": "melissa_spencer@example.com",         "url": "https://secure.tutorcruncher.com/api/clients/35/"       },       "rate": "95.00000",       "sales_code": "200",       "tax_amount": "23.75000",       "units": "1.50000"     }   ],   "client": {     "id": 35,     "first_name": "Melissa",     "last_name": "Spencer",     "email": "melissa_spencer@example.com",     "url": "https://secure.tutorcruncher.com/api/clients/35/"   },   "date_sent": "2020-01-03T16:11:48.312507Z",   "date_void": null,   "date_paid": "2020-02-03T16:11:48.312507Z",   "display_id": "INV-48",   "gross": "340.90",   "net": 284.08,   "status": "paid",   "still_to_pay": 0.0,   "tax": "56.82" }

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 }

Label Object

Label objects are used to categorise and group objects in TutorCruncher. They are used to group Administrators, Tutors, Affiliates, Clients, Students and Jobs.

Attributes

id integer

Unique identifier for the object.

name string

The name of the label.

machine_name string

Unique slugified name of the label.

colour string

The colour of the label.

applicable_role_types string

The role types the label is applicable to.

email_recipients object

The email recipients for the label.

contractor_editable boolean

Whether the label is editable by contractors.

url string

URL to the label's object.

OBJECT
{     "id": 42,     "name": "External",     "machine_name": "external",     "colour": "MediumBlue",     "applicable_role_types": [         "client",         "service"     ],     "email_recipients": [         {             "id": 2,             "first_name": "Diana",             "last_name": "Lafayette",             "email": "diana_lafayette@testagency.example.com"         },         {             "id": 59,             "first_name": "Billy",             "last_name": "Holiday",             "email": "testing+owner@tutorcruncher.com"         }     ],     "contractor_editable": true,     "url": "http://localhost:8000/api/labels/42/" }

List all Labels

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

GET /api/labels/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.get('https://secure.tutorcruncher.com/api/labels/', headers=headers) pprint.pprint(r.json())
RESPONSE
{     "count": 4,     "next": null,     "previous": null,     "results": [         {             "id": 26,             "name": "Public Job",             "machine_name": "public-job",             "url": "https://secure.tutorcruncher.com/api/labels/26/"         },         {             "id": 25,             "name": "Public Profile",             "machine_name": "public-profile",             "url": "https://secure.tutorcruncher.com/api/labels/25/"         },         {             "id": 24,             "name": "Invited for Interview",             "machine_name": "invited-for-interview",             "url": "https://secure.tutorcruncher.com/api/labels/24/"         },         {             "id": 23,             "name": "Job Finished",             "machine_name": "service-finished",             "url": "https://secure.tutorcruncher.com/api/labels/23/"         }     ] }

Get a Label

Returns the details of an existing label. You only need to specify the unique id of the Label to get the correct details.

GET /api/labels/<id>/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.get('https://secure.tutorcruncher.com/api/labels/<id>/', headers=headers) pprint.pprint(r.json())
RESPONSE
{     "id": 42,     "name": "External",     "machine_name": "external",     "colour": "MediumBlue",     "applicable_role_types": [         "client",         "service"     ],     "email_recipients": [         {             "id": 2,             "first_name": "Diana",             "last_name": "Lafayette",             "email": "diana_lafayette@testagency.example.com"         },         {             "id": 59,             "first_name": "Billy",             "last_name": "Holiday",             "email": "testing+owner@tutorcruncher.com"         }     ],     "contractor_editable": true,     "url": "http://localhost:8000/api/labels/42/" }

Note Object

Notes can be attached to Clients, Tutors, Agents (Affiliates), Students, Services and Appointments.

Attributes

id integer

Unique identifier for the object.

dt_created string

The date the Note was created.

dt_updated string

The date the Note was last updated.

creator object

The creator of the Note.

Show child attributes
id integer

The ID of the note creator.

first_name string

The first name of the note creator.

last_name string

The last name of the note creator.

email string

The email address of the note creator.

text string

The text of the Note.

focus object

Details about the object the Note was added to.

OBJECT
{     "id": 1,     "dt_created": "2023-08-16T15:40:18.922862Z",     "dt_updated": "2023-08-16T15:40:18.922874Z",     "creator": {         "id": 2,         "first_name": "Diana",         "last_name": "Lafayette",         "email": "diana_lafayette@testagency.example.com"     },     "text": "This is a test note.",     "focus": {         "id": 62,         "first_name": "Jamie",         "last_name": "Hoskins",         "email": "jamie_hoskins@testagency.example.com",         "url": "http://localhost:8000/api/clients/62/"     } }

List all Notes

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

GET /api/notes/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.get('https://secure.tutorcruncher.com/api/notes/', headers=headers) pprint.pprint(r.json())
RESPONSE
{     "count": 3,     "next": null,     "previous": null,     "results": [         {             "id": 3,             "dt_created": "2023-08-16T16:05:54.465325Z",             "dt_updated": "2023-08-16T16:05:54.465348Z",             "creator": 2,             "text": "This note is on an appointment.",             "url": "http://localhost:8000/api/notes/3/"         },         {             "id": 2,             "dt_created": "2023-08-16T16:05:37.596813Z",             "dt_updated": "2023-08-16T16:05:37.596842Z",             "creator": 2,             "text": "This is a note on a job.",             "url": "http://localhost:8000/api/notes/2/"         },         {             "id": 1,             "dt_created": "2023-08-16T15:40:18.922862Z",             "dt_updated": "2023-08-16T15:40:18.922874Z",             "creator": 2,             "text": "* test",             "url": "http://localhost:8000/api/notes/1/"         }     ] }

Get a Note

Returns the details of an existing Note. You only need to specify the unique id of the Note to get the correct details.

GET /api/notes/<id>/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.get('https://secure.tutorcruncher.com/api/notes/<id>/', headers=headers) pprint.pprint(r.json())
RESPONSE
{     "id": 1,     "dt_created": "2023-08-16T15:40:18.922862Z",     "dt_updated": "2023-08-16T15:40:18.922874Z",     "creator": {         "id": 2,         "first_name": "Diana",         "last_name": "Lafayette",         "email": "diana_lafayette@testagency.example.com"     },     "text": "This is a test note.",     "focus": {         "id": 62,         "first_name": "Jamie",         "last_name": "Hoskins",         "email": "jamie_hoskins@testagency.example.com",         "url": "http://localhost:8000/api/clients/62/"     } }

Payment Order Object

Payment Order objects provide all the details of a TutorCruncher Payment Order including the related appointments, adhoc_charges and the paying_client for the Payment Order.

Attributes

id integer

Unique identifier for the object.

charges array

An array of different charges related to the payment order.

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, url and service object.

date string

Date and time the charge occured.

payee string

Object of the Contractor/Agent who will get paid. Attributes in the object are id, first_name, last_name, email, and url.

payer object

Name of the branch that will be paying the invoice

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.

payee object

Object of the Contractor/Agent on the Payment Order.

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/Agent's object.

date_sent string

Date and time the Payment Order was sent to the Contractor/Agent.

date_void string

Date and time the Payment Order was marked as void.

date_paid string

Date and time the Payment Order was marked as paid.

display_id string

Payment Order's unique display name.

amount decimal

Payment Order's amount.

status string

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

still_to_pay decimal

Amount of the Payment Order that still needs to be payed.

tax string

Payment Order's tax amount.

OBJECT
{     "id": 4985119,     "amount": "225.00",     "charges": [         {             "adhoc_charge": null,             "amount": "45.00000",             "appointment": {                 "id": 8255569,                 "start": "2022-09-17T18:00:47.967724+01:00",                 "finish": "2022-09-17T19:30:47.967724+01:00",                 "topic": "Programming patterns, algorithms and data structures 4",                 "status": "complete",                 "service": {                     "id": 604713,                     "name": "Theory of computer programming",                     "dft_charge_type": "hourly",                     "created": "2022-08-20T15:14:20.678562+01:00",                     "dft_charge_rate": "95.00",                     "dft_contractor_rate": "30.00",                     "last_updated": "2022-10-19T15:14:43.607845+01:00",                     "status": "in-progress",                     "url": "https://secure.tutorcruncher.com/api/services/604713/"                 },                 "url": "https://secure.tutorcruncher.com/api/appointments/8255569/"             },             "date": "2022-09-17T19:30:47.967724+01:00",             "payee": {                 "id": 1865751,                 "first_name": "Bettie",                 "last_name": "Canales",                 "email": "bettie_canales@online-olive.example.com",                 "url": "https://secure.tutorcruncher.com/api/contractors/1865751/"             },             "payer": "Demo Branch",             "rate": "30.00000",             "sales_code": "325",             "tax_amount": "0.00000",             "units": "1.50000"         }     ],     "date_sent": "2022-10-19T15:15:36.488105+01:00",     "date_void": null,     "date_paid": null,     "display_id": "PO-46",     "status": "unpaid",     "payee": {         "id": 1865751,         "first_name": "Bettie",         "last_name": "Canales",         "email": "bettie_canales@online-olive.example.com",         "url": "https://secure.tutorcruncher.com/api/contractors/1865751/"     },     "still_to_pay": 225.0 }

List all Payment Orders

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

GET /api/payment-orders/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.get('https://secure.tutorcruncher.com/api/payment-orders/', headers=headers) pprint.pprint(r.json())
RESPONSE
{   "count": 34,   "next": "https://secure.tutorcruncher.com/api/payment-orders/?page=2",   "previous": null,   "results": [     {       "id": 22,       "display_id": "PO-2",       "amount": "55.00",       "date_sent": "2020-01-01T00:00:00Z",       "payee": {           "id": 68,           "first_name": "Jane",           "last_name": "con_a",           "email": "jane_con_a@example.com",           "url": "https://secure.tutorcruncher.com/api/contractors/68/"       },       "status": "unpaid",       "url": "https://secure.tutorcruncher.com/api/payment-orders/22/"     },     ...   ] }

Get a Payment Order

Returns the details of an existing Payment Order. You only need to specify the unique id of the Payment Order to get the correct details.

GET /api/payment-orders/<id>/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.get('https://secure.tutorcruncher.com/api/payment-orders/<id>/', headers=headers) pprint.pprint(r.json())
RESPONSE
{     "id": 4985119,     "amount": "225.00",     "charges": [         {             "adhoc_charge": null,             "amount": "45.00000",             "appointment": {                 "id": 8255569,                 "start": "2022-09-17T18:00:47.967724+01:00",                 "finish": "2022-09-17T19:30:47.967724+01:00",                 "topic": "Programming patterns, algorithms and data structures 4",                 "status": "complete",                 "service": {                     "id": 604713,                     "name": "Theory of computer programming",                     "dft_charge_type": "hourly",                     "created": "2022-08-20T15:14:20.678562+01:00",                     "dft_charge_rate": "95.00",                     "dft_contractor_rate": "30.00",                     "last_updated": "2022-10-19T15:14:43.607845+01:00",                     "status": "in-progress",                     "url": "https://secure.tutorcruncher.com/api/services/604713/"                 },                 "url": "https://secure.tutorcruncher.com/api/appointments/8255569/"             },             "date": "2022-09-17T19:30:47.967724+01:00",             "payee": {                 "id": 1865751,                 "first_name": "Bettie",                 "last_name": "Canales",                 "email": "bettie_canales@online-olive.example.com",                 "url": "https://secure.tutorcruncher.com/api/contractors/1865751/"             },             "payer": "Demo Branch",             "rate": "30.00000",             "sales_code": "325",             "tax_amount": "0.00000",             "units": "1.50000"         },         {             "adhoc_charge": null,             "amount": "45.00000",             "appointment": {                 "id": 8255568,                 "start": "2022-09-10T18:00:47.967724+01:00",                 "finish": "2022-09-10T19:30:47.967724+01:00",                 "topic": "Programming patterns, algorithms and data structures 3",                 "status": "complete",                 "service": {                     "id": 604713,                     "name": "Theory of computer programming",                     "dft_charge_type": "hourly",                     "created": "2022-08-20T15:14:20.678562+01:00",                     "dft_charge_rate": "95.00",                     "dft_contractor_rate": "30.00",                     "last_updated": "2022-10-19T15:14:43.607845+01:00",                     "status": "in-progress",                     "url": "https://secure.tutorcruncher.com/api/services/604713/"                 },                 "url": "https://secure.tutorcruncher.com/api/appointments/8255568/"             },             "date": "2022-09-10T19:30:47.967724+01:00",             "payee": {                 "id": 1865751,                 "first_name": "Bettie",                 "last_name": "Canales",                 "email": "bettie_canales@online-olive.example.com",                 "url": "https://secure.tutorcruncher.com/api/contractors/1865751/"             },             "payer": "Demo Branch",             "rate": "30.00000",             "sales_code": "325",             "tax_amount": "0.00000",             "units": "1.50000"         },         {             "adhoc_charge": null,             "amount": "45.00000",             "appointment": {                 "id": 8255567,                 "start": "2022-09-03T18:00:47.967724+01:00",                 "finish": "2022-09-03T19:30:47.967724+01:00",                 "topic": "Programming patterns, algorithms and data structures 2",                 "status": "complete",                 "service": {                     "id": 604713,                     "name": "Theory of computer programming",                     "dft_charge_type": "hourly",                     "created": "2022-08-20T15:14:20.678562+01:00",                     "dft_charge_rate": "95.00",                     "dft_contractor_rate": "30.00",                     "last_updated": "2022-10-19T15:14:43.607845+01:00",                     "status": "in-progress",                     "url": "https://secure.tutorcruncher.com/api/services/604713/"                 },                 "url": "https://secure.tutorcruncher.com/api/appointments/8255567/"             },             "date": "2022-09-03T19:30:47.967724+01:00",             "payee": {                 "id": 1865751,                 "first_name": "Bettie",                 "last_name": "Canales",                 "email": "bettie_canales@online-olive.example.com",                 "url": "https://secure.tutorcruncher.com/api/contractors/1865751/"             },             "payer": "Demo Branch",             "rate": "30.00000",             "sales_code": "325",             "tax_amount": "0.00000",             "units": "1.50000"         },         {             "adhoc_charge": null,             "amount": "45.00000",             "appointment": {                 "id": 8255561,                 "start": "2022-09-14T12:00:47.967724+01:00",                 "finish": "2022-09-14T13:30:47.967724+01:00",                 "topic": "Microelectronics and application of semiconductors 4",                 "status": "complete",                 "service": {                     "id": 604712,                     "name": "Microelectronics, Semiconductors, Industrial applications",                     "dft_charge_type": "hourly",                     "created": "2022-08-17T15:14:20.678562+01:00",                     "dft_charge_rate": "95.00",                     "dft_contractor_rate": "30.00",                     "last_updated": "2022-10-19T15:14:43.576396+01:00",                     "status": "in-progress",                     "url": "https://secure.tutorcruncher.com/api/services/604712/"                 },                 "url": "https://secure.tutorcruncher.com/api/appointments/8255561/"             },             "date": "2022-09-14T13:30:47.967724+01:00",             "payee": {                 "id": 1865751,                 "first_name": "Bettie",                 "last_name": "Canales",                 "email": "bettie_canales@online-olive.example.com",                 "url": "https://secure.tutorcruncher.com/api/contractors/1865751/"             },             "payer": "Demo Branch",             "rate": "30.00000",             "sales_code": "325",             "tax_amount": "0.00000",             "units": "1.50000"         },         {             "adhoc_charge": null,             "amount": "45.00000",             "appointment": {                 "id": 8255560,                 "start": "2022-09-07T12:00:47.967724+01:00",                 "finish": "2022-09-07T13:30:47.967724+01:00",                 "topic": "Microelectronics and application of semiconductors 3",                 "status": "complete",                 "service": {                     "id": 604712,                     "name": "Microelectronics, Semiconductors, Industrial applications",                     "dft_charge_type": "hourly",                     "created": "2022-08-17T15:14:20.678562+01:00",                     "dft_charge_rate": "95.00",                     "dft_contractor_rate": "30.00",                     "last_updated": "2022-10-19T15:14:43.576396+01:00",                     "status": "in-progress",                     "url": "https://secure.tutorcruncher.com/api/services/604712/"                 },                 "url": "https://secure.tutorcruncher.com/api/appointments/8255560/"             },             "date": "2022-09-07T13:30:47.967724+01:00",             "payee": {                 "id": 1865751,                 "first_name": "Bettie",                 "last_name": "Canales",                 "email": "bettie_canales@online-olive.example.com",                 "url": "https://secure.tutorcruncher.com/api/contractors/1865751/"             },             "payer": "Demo Branch",             "rate": "30.00000",             "sales_code": "325",             "tax_amount": "0.00000",             "units": "1.50000"         }     ],     "date_sent": "2022-10-19T15:15:36.488105+01:00",     "date_void": null,     "date_paid": null,     "display_id": "PO-46",     "status": "unpaid",     "payee": {         "id": 1865751,         "first_name": "Bettie",         "last_name": "Canales",         "email": "bettie_canales@online-olive.example.com",         "url": "https://secure.tutorcruncher.com/api/contractors/1865751/"     },     "still_to_pay": 225.0 }

Take Payment Order Payment

Pay partially or pay in full, post how much to be paid towards the Payment Order and we'll return how much there is still_to_pay. If fully paid off, paid will return a value of true.

POST /api/payment-orders/<id>/take_payment/

1

2

3

4

5

6

7

8

9

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'amount': 100.0, 'method': 'cash', } r = requests.post('https://secure.tutorcruncher.com/api/payment-orders/<id>/take_payment/', json=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "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 Invoices

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.

Note that, if a Proforma Invoice exists that is either Draft or Confirmed, TutorCruncher will simply add a new item to it and it will NOT be raised, even if send_pfi is set to true.

POST /api/proforma-invoices/

1

2

3

4

5

6

7

8

9

10

11

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'amount': 120, 'client': 312, 'send_pfi': True, 'description': 'Credit Request for Billy Holiday' } r = requests.post('https://secure.tutorcruncher.com/api/proforma-invoices/', json=data, headers=headers) pprint.pprint(r.json())
RESPONSE
{   "id": 2,   "amount": "120.00",   "client": {     "id": 321,     "first_name": "Anthony",     "last_name": "Clay",     "email": "anthony_clay@example.com",     "url": "https://secure.tutorcruncher.com/api/clients/321/"   },   "created": true,   "display_id": "PFI-2",   "date_sent": "2020-01-17T16:11:48.312507Z",   "date_paid": null,   "items": [     {       "amount": "60.00",       "custom_description": "Credit Request from terminal",       "sales_codes": null,       "rcra": null     }   ],   "service_recipients": [],   "status": "unpaid",   "still_to_pay": 120.0 }

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.

Filters

release__gte string

Filter by the date and time the Agent was released.

release__lte string

Filter by the date and time the Agent was released.

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.

Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}

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.

Filters

user__created__gte string

Filter by the date and time the Recipient was created.

user__created__lte string

Filter by the date and time the Recipient was created.

user__first_name string

Filter by the Recipient's first name.

user__last_name string

Filter by the Recipient's last name.

user__email string

Filter by the Recipient's email address.

distance_address string

Filter by the address.

distance_radius integer

Filter by the radius of the address. This is used in conjunction with the address filter.

labels integer

Filter by the Recipient's labels (id).

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.

Check out Creating/Updating Users for more information on linking to a specific user.

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': {'user_dob': '1993-06-23'}, 'send_emails': True, } r = requests.post('https://secure.tutorcruncher.com/api/recipients/', json=data, headers=headers) pprint.pprint(r.json())
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": [       {         "id": 1,         "value": "1993-06-23",         "type": "Date",         "machine_name": "user-dob",         "name": "Date of birth"       }     ]   } }

Update a Recipient

Update a Recipient object by supplying the email address as the unique identifier. You must also supply the required fields like last_name even if they are not being updated. You only need to post information that you want to change and not the whole Recipient object.

If the Recipient doesn't have an email address, if you supply a first_name, last_name and paying_client, we will update a Recipient if the names match an existing Recipient linked to the Client ID you supply for paying_client.

Check out Creating/Updating Users for more information on linking to a specific user.

POST /api/recipients/

1

2

3

4

5

6

7

8

9

10

11

12

13

14

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'user': { 'email': 'billy_bob@example.com', 'last_name': 'Bob2', # ... }, 'extra_attrs': {'user_dob': '1993-06-23'}, # ... } r = requests.post('https://secure.tutorcruncher.com/api/recipients/', json=data, headers=headers) pprint.pprint(r.json())
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": [       {         "id": 1,         "value": "1993-06-23",         "type": "Date",         "machine_name": "user-dob",         "name": "Date of birth"       }     ]   } }

Reports Object

Reports object contains important information like the creator(the contractor or administrator) who wrote the Report, the service_recipient who the Review is about, the client related to the student and the custom fields used to build your Report.

Attributes

appointment object

Object of Appointment related to the Report.

Show child attributes
id integer

Unique identifier for the object.

finish string

Appointment's finish date and time.

start string

Appointment's start date and time.

topic string

Appointment's topic.

status string

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

url string

URL to the Appointment's object.

service object

The Service the Appointment is in.

approved boolean

If the Report has been approved or not.

client object

Object of the Client related to the Report.

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.

creator object

Object of the Contractor or Administrator who wrote the Report.

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 or Administrator object.

dt_created string

Date and time when the Report was created.

extra_attrs array

An array of the Report's extra fields.

Show child attributes
id integer

Unique identifier for the field's object.

machine_name string

Unique slugified name of the field.

name string

The name of the field.

type string

The type of the field.

value string

The value of the field.

service_recipient object

Object of the Service recipient related to the Report.

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 Service recipient's object.

OBJECT
{   "appointment": {     "finish": "2021-06-03T09:30:02.733619Z",     "id": 52,     "service": {       "created": "2021-05-27T14:43:32.572794Z",       "dft_charge_rate": "55.00",       "dft_charge_type": "hourly",       "dft_contractor_rate": "35.00",       "id": 3,       "last_updated": "2021-05-17T14:43:32.572794Z",       "name": "A level Physics",       "status": "in-progress",       "url": "https://secure.tutorcruncher.com/api/services/3/"     },     "start": "2021-06-03T07:30:02.733619Z",     "status": "Complete",     "topic": "Lesson 1",     "url": "https://secure.tutorcruncher.com/api/appointments/52/"   },   "approved": true,   "client": {     "email": "katherine_brown@example.com",     "first_name": "Katherine",     "id": 17,     "last_name": "Brown",     "url": "https://secure.tutorcruncher.com/api/clients/17/"   },   "creator": {     "email": "brain_johnson@example.com",     "first_name": "brian",     "id": 33,     "last_name": "Johnson",     "url": "https://secure.tutorcruncher.com/api/contractors/33/"   },   "dt_created": "2021-06-22T14:43:52.172855Z",   "extra_attrs": [     {       "id": 43,       "machine_name": "client_report",       "name": "Client Report",       "type": "Long Textbox",       "value": "Great start, 2 more lessons needed"     }   ],   "service_recipient": {     "email": "jennifer_brown@testagency.example.com",     "first_name": "Jennifer",     "id": 10,     "last_name": "Brown",     "url": "http://localhost:8000/api/recipients/10/"   } }

List all Reports

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

GET /api/reports/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.get('https://secure.tutorcruncher.com/api/reports/', headers=headers) pprint.pprint(r.json())
RESPONSE
{   "count": 37,   "next": null,   "previous": null,   "results": [     {       "appointment": {         "finish": "2021-06-03T09:30:02.733619Z",         "id": 52,         "service": {           "created": "2021-05-27T14:43:32.572794Z",           "dft_charge_rate": "55.00",           "dft_charge_type": "hourly",           "dft_contractor_rate": "35.00",           "id": 3,           "last_updated": "2021-05-17T14:43:32.572794Z",           "name": "A level Physics",           "status": "in-progress",           "url": "https://secure.tutorcruncher.com/api/services/3/"         },         "start": "2021-06-03T07:30:02.733619Z",         "status": "Complete",         "topic": "Lesson 1",         "url": "https://secure.tutorcruncher.com/api/appointments/52/"       },       "approved": true,       "client": {         "email": "katherine_brown@example.com",         "first_name": "Katherine",         "id": 17,         "last_name": "Brown",         "url": "https://secure.tutorcruncher.com/api/clients/17/"       },       "creator": {         "email": "brain_johnson@example.com",         "first_name": "brian",         "id": 33,         "last_name": "Johnson",         "url": "https://secure.tutorcruncher.com/api/contractors/33/"       },       "dt_created": "2021-06-22T14:43:52.172855Z",       "service_recipient": {         "email": "jennifer_brown@testagency.example.com",         "first_name": "Jennifer",         "id": 10,         "last_name": "Brown",         "url": "http://localhost:8000/api/recipients/10/"       },     "url": "http://localhost:8000/api/reports/12/"     },     ...   ] }

Get a Report

Returns the details of an existing report. You only need to specify the unique id of the Report to get the correct details.

GET /api/reports/<id>/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.get('https://secure.tutorcruncher.com/api/reports/<id>/', headers=headers) pprint.pprint(r.json())
RESPONSE
{   "appointment": {     "finish": "2021-06-03T09:30:02.733619Z",     "id": 52,     "service": {       "created": "2021-05-27T14:43:32.572794Z",       "dft_charge_rate": "55.00",       "dft_charge_type": "hourly",       "dft_contractor_rate": "35.00",       "id": 3,       "last_updated": "2021-05-17T14:43:32.572794Z",       "name": "A level Physics",       "status": "in-progress",       "url": "https://secure.tutorcruncher.com/api/services/3/"     },     "start": "2021-06-03T07:30:02.733619Z",     "status": "Complete",     "topic": "Lesson 1",     "url": "https://secure.tutorcruncher.com/api/appointments/52/"   },   "approved": true,   "client": {     "email": "katherine_brown@example.com",     "first_name": "Katherine",     "id": 17,     "last_name": "Brown",     "url": "https://secure.tutorcruncher.com/api/clients/17/"   },   "creator": {     "email": "brain_johnson@example.com",     "first_name": "brian",     "id": 33,     "last_name": "Johnson",     "url": "https://secure.tutorcruncher.com/api/contractors/33/"   },   "dt_created": "2021-06-22T14:43:52.172855Z",   "extra_attrs": [     {       "id": 43,       "machine_name": "client_report",       "name": "Client Report",       "type": "Long Textbox",       "value": "Great start, 2 more lessons needed"     }   ],   "service_recipient": {     "email": "jennifer_brown@testagency.example.com",     "first_name": "Jennifer",     "id": 10,     "last_name": "Brown",     "url": "http://localhost:8000/api/recipients/10/"   } }

Reviews Object

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.

Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}

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.

Updated with payload shape: 'extra_attrs': {'custom_field_machine_name_1': 'value_1', 'custom_field_machine_name_2': 'value_2'}

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.

Filters

created_gte string

Filter by the date and time the Service was created.

created_lte string

Filter by the date and time the Service was created.

last_updated_gte string

Filter by the date and time the Service was updated.

last_updated_lte string

Filter by the date and time the Service was updated.

labels integer

Filter by the Service's labels (id).

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": true,     "branch": 17597,     "branch_tax_setup": "Default Company Tax (20%)",     "cap": null,     "colour": "Khaki",     "conjobs": [         {             "contractor": 1865741,             "contractor_permissions": "add-edit-complete",             "name": "James Higgins",             "pay_rate": "45.00"         }     ],     "contractor_tax_setup": "Default Tutor Tax (no tax)",     "created": "2023-04-18T17:44:08.058135+01:00",     "description": "Example description for the Service which will appear on TutorCruncher",     "dft_charge_type": "hourly",     "dft_charge_rate": 45.0,     "dft_contractor_permissions": "add-edit-complete",     "dft_contractor_rate": 35.0,     "dft_location": null,     "dft_max_srs": 10,     "extra_attrs": [],     "extra_fee_per_apt": null,     "id": 719520,     "inactivity_time": 14,     "is_bookable": false,     "is_deleted": false,     "labels": [],     "last_updated": "2023-04-18T17:44:08.058199+01:00",     "latest_apt_ahc": "2023-04-18T17:44:08.058206+01:00",     "name": "Example Name",     "net_gross": "gross",     "rcrs": [         {             "recipient": 1865698,             "recipient_name": "Arthur Hoskins",             "paying_client": 1865697,             "paying_client_name": "Jamie Hoskins",             "charge_rate": "35.00",             "agent": null,             "agent_name": null,             "agent_percentage": null         }     ],     "report_required": false,     "require_con_job": false,     "require_rcr": false,     "review_units": 0,     "sales_codes": null,     "desired_skills": [],     "sr_premium": "0.00",     "status": "pending",     "total_apt_units": 0 }

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

46

47

48

49

50

51

52

53

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'allow_proposed_rates': True, 'branch_tax_setup': None, 'cap': None, 'conjobs': [ { 'contractor': 1865741, 'contractor_permissions': 'add-edit-complete', 'pay_rate': 45.0 }, { 'contractor': 1865742, 'contractor_permissions': 'add-edit-complete', 'pay_rate': 35.0 } ], 'rcrs': [ { 'recipient': 1865698, 'charge_rate': 35.0 }, { 'recipient': 1865702, 'charge_rate': 25.0 } ], 'colour': 'Khaki', 'contractor_tax_setup': None, 'description': 'Example description for the Service which will appear on TutorCruncher', 'dft_charge_type': 'hourly', 'dft_charge_rate': 45.0, 'dft_contractor_permissions': 'add-edit-complete', 'dft_contractor_rate': 35.0, 'dft_location': None, 'dft_max_srs': 10, 'extra_attrs': {'study_level': 'GCSE'}, 'extra_fee_per_apt': None, 'inactivity_time': None, 'name': 'Example Name', 'net_gross': 'gross', 'report_required': False, 'require_rcr': False, 'require_con_job': False, 'review_units': 0, 'sales_codes': None, 'sr_premium': 0.0, 'status': 'pending' } r = requests.post('https://secure.tutorcruncher.com/api/services/', json=data, headers=headers) pprint.pprint(r.json())
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": [       {         "id": 1,         "value": "GCSE",         "type": "Short Textbox",         "machine_name": "study_level",         "name": "Study Level"       }     ],   "extra_fee_per_apt": null,   "inactivity_time": null,   "name": "Example Name",   "net_gross": "gross",   "require_rcr": true,   "require_con_job": true,   "review_units": 0,   "sales_codes": null,   "sr_premium": "0.00",   "status": "pending" }

Update a Service

Updating a Service is similar to Creating a Service using the required fields name, dft_charge_rate, and dft_contractor_rate. One major difference is that you cannot add, edit or delete Recipients or Contractors on the Service.

PUT /api/services/<id>/

1

2

3

4

5

6

7

8

9

10

11

12

13

14

import pprint, requests headers = {'Authorization': 'token <API KEY>'} data = { 'name': 'SAT Maths with Philip', 'dft_charge_type': 'hourly', 'dft_charge_rate': 55, 'dft_contractor_rate': 40, 'status': 'pending', 'colour': 'blue', 'extra_attrs': {'study_level': 'A Level'} } r = requests.put('https://secure.tutorcruncher.com/api/services/<id>/', json=data, headers=headers) pprint.pprint(r.json())
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": 55.0,   "dft_contractor_permissions": "add-edit-complete",   "dft_contractor_rate": 40.0,   "dft_location": null,   "dft_max_srs": null,   "extra_attrs": [       {         "id": 1,         "value": "A Level",         "type": "Short Textbox",         "machine_name": "study_level",         "name": "Study Level"       }     ],   "extra_fee_per_apt": null,   "id": 11,   "inactivity_time": 14,   "is_bookable": false,   "is_deleted": false,   "labels": [],   "latest_apt_ahc": "2020-02-18T16:12:09.888465Z",   "name": "SAT Maths with Philip",   "net_gross": "gross",   "rcrs": [     {       "recipient": 20,       "recipient_name": "Caroline Bain",       "paying_client": 19,       "paying_client_name": "Christian Bain",       "charge_rate": null,       "agent": null,       "agent_name": null,       "agent_percentage": null     },     {       "recipient": 21,       "recipient_name": "Mary Bain",       "paying_client": 19,       "paying_client_name": "Christian Bain",       "charge_rate": null,       "agent": null,       "agent_name": null,       "agent_percentage": null     }   ],   "require_con_job": true,   "require_rcr": true,   "review_units": null,   "sales_codes": null,   "sr_premium": null,   "status": "finished",   "total_apt_units": 15.0 }

Subject Object

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

Task Object

Tasks can be attached to a Client, Student or Tutor to remind you to do something at a certain time.

Attributes

id integer

Unique identifier for the object.

admin object

The admin responsible for the Task.

Show child attributes
id integer

Unique identifier for the object.

first_name string

The users first name.

last_name string

The users last name.

email string

The users email address.

complete boolean

Whether or not the Task is completed.

description string

The description of the Task.

due_dt string

The date the Task is due.

notification_pending boolean

Whether or not a reminder is still to be sent.

reminder_dt string

The date the reminder is to be sent.

repeater string

How often the Task is to be repeated, the two choices are weekly or monthly.

repeat_every string

Repeat every x weeks or months.

role object

Object of the Role.

Show child attributes
id integer

Unique identifier for the object.

first_name string

The users first name.

last_name string

The users last name.

email string

The users email address.

url string

URL to the Role's object.

service object

Object of the Service.

Show child attributes
id integer

Unique identifier for the object.

name string

The name of the Service.

dft_charge_type string

The default charge type of the Service.

created string

The date the Service was created.

dft_charge_rate string

The default charge rate of the Service.

dft_contractor_rate string

The default contractor rate of the Service.

last_updated string

The date the Service was last updated.

status string

The status of the Service.

url string

URL to the Service's object.

task_type string

The type of Task, the options are phone, email, service-cold or other.

OBJECT
{     "id": 1,     "admin": {         "id": 59,         "first_name": "Melissa",         "last_name": "Spencer",         "email": "melissa_spencer@example.com"     },     "complete": false,     "description": "This is an example description of a task.",     "due_dt": "2023-07-04T17:40:00+01:00",     "notification_pending": true,     "reminder_dt": "2023-07-04T17:40:00+01:00",     "repeater": "weekly",     "repeat_every": 1,     "role": {         "id": 3,         "first_name": "Jamie",         "last_name": "Hoskins",         "email": "jamie_hoskins@testagency.example.com",         "url": "https://secure.tutorcruncher.com/api/clients/3/"     },     "service": {         "id": 11,         "name": "A Level Physics",         "dft_charge_type": "hourly",         "created": "2023-03-15T15:40:13.104951Z",         "dft_charge_rate": "75.00",         "dft_contractor_rate": "35.00",         "last_updated": "2023-07-03T16:40:24.291003+01:00",         "status": "finished",         "url": "https://secure.tutorcruncher.com/api/services/11/"     },     "task_type": "phone" }

List all Tasks

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

GET /api/tasks/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.get('https://secure.tutorcruncher.com/api/tasks/', headers=headers) pprint.pprint(r.json())
RESPONSE
{     "count": 4,     "next": null,     "previous": null,     "results": [         {             "id": 5,             "complete": false,             "description": "This is the fourth tasks description",             "due_dt": "2023-07-08T08:10:00Z",             "task_type": "other",             "url": "https://secure.tutorcruncher.com/api/tasks/5/"         },         {             "id": 4,             "complete": false,             "description": "This is the third tasks description.",             "due_dt": "2023-07-07T08:10:00Z",             "task_type": "service-cold",             "url": "https://secure.tutorcruncher.com/api/tasks/4/"         },         {             "id": 3,             "complete": false,             "description": "This is the second tasks description.",             "due_dt": "2023-07-06T08:09:00Z",             "task_type": "email",             "url": "https://secure.tutorcruncher.com/api/tasks/3/"         },         {             "id": 2,             "complete": false,             "description": "This is the first tasks description.",             "due_dt": "2023-07-05T08:08:00Z",             "task_type": "phone",             "url": "https://secure.tutorcruncher.com/api/tasks/2/"         }     ] }

Get a Task

Returns the details of an existing Task. You only need to specify the unique id of the Task to get the correct details.

GET /api/tasks/<id>/

1

2

3

4

5

import pprint, requests headers = {'Authorization': 'token <API KEY>'} r = requests.get('https://secure.tutorcruncher.com/api/tasks/<id>/', headers=headers) pprint.pprint(r.json())
RESPONSE
{     "id": 1,     "admin": {         "id": 59,         "first_name": "Melissa",         "last_name": "Spencer",         "email": "melissa_spencer@example.com"     },     "complete": false,     "description": "This is an example description of a task.",     "due_dt": "2023-07-04T17:40:00+01:00",     "notification_pending": true,     "reminder_dt": "2023-07-04T17:40:00+01:00",     "repeater": "weekly",     "repeat_every": 1,     "role": {         "id": 3,         "first_name": "Jamie",         "last_name": "Hoskins",         "email": "jamie_hoskins@testagency.example.com",         "url": "https://secure.tutorcruncher.com/api/clients/3/"     },     "service": {         "id": 11,         "name": "A Level Physics",         "dft_charge_type": "hourly",         "created": "2023-03-15T15:40:13.104951Z",         "dft_charge_rate": "75.00",         "dft_contractor_rate": "35.00",         "last_updated": "2023-07-03T16:40:24.291003+01:00",         "status": "finished",         "url": "https://secure.tutorcruncher.com/api/services/11/"     },     "task_type": "phone" }

Tender Object

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.

Filters

contractor integer

Filter by the Contractor's id.

service integer

Filter by the Service's id.

created_gte string

Filter by the date and time the Tender was created.

created_lte string

Filter by the date and time the Tender was created.

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