Update docs for Roles V2

data/actions.json

@@ -931,6 +931,13 @@
     "help_text": "When an Administrator updates the Terms and Conditions.",
     "subject_types": []
   },
+  {
+    "key": "CONFIRMED_AGENCY_EMAIL",
+    "value": "CONFIRMED_AGENCY_EMAIL",
+    "msg": "Confirmed Company Email",
+    "help_text": "When a Company confirms their email address.",
+    "subject_types": []
+  },
   {
     "key": "CREATED_AGENCY",
     "value": "CREATED_AGENCY",

pages/adhoccharges/ad-hoc-charge-object.json

@@ -4,7 +4,6 @@
   "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",

pages/adhoccharges/ad-hoc-charge-object.yml

@@ -87,10 +87,6 @@ attributes:
         name: branch_tax_setup
         type: string
         description: Tax setup for the Branch when invoicing.
-      -
-        name: charge_via_branch
-        type: boolean
-        description: Force Invoices associated with this Tutor to be charged via branch.
       -
         name: contractor_tax_setup
         type: string

pages/adhoccharges/create-an-ad-hoc-charge.json

@@ -4,7 +4,6 @@
   "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",

pages/adhoccharges/get-an-ad-hoc-charge.json

@@ -4,7 +4,6 @@
   "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",

pages/adhoccharges/update-an-ad-hoc-charge.json

@@ -4,7 +4,6 @@
   "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",

pages/agents/agent-object-v1.md

@@ -0,0 +1,4 @@
+### Agent Object (Version 1 - Will be deprecated 3rd July 2025)
+
+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`.

pages/agents/agent-object.yml → pages/agents/agent-object-v1.yml

@@ -130,23 +130,23 @@ attributes:
 
 filters:
   -
-    name: created__gte
+    name: user__created__gte
     type: string
     description: Filter by the date and time the Agent was created.
   -
-    name: created__lte
+    name: user__created__lte
     type: string
     description: Filter by the date and time the Agent was created.
   -
-    name: first_name
+    name: user__first_name
     type: string
     description: Filter by the Agent's first name.
   -
-    name: last_name
+    name: user__last_name
     type: string
     description: Filter by the Agent's last name.
   -
-    name: email
+    name: user__email
     type: string
     description: Filter by the Agent's email address.
   -
@@ -164,4 +164,4 @@ filters:
   -
     name: labels
     type: integer
-    description: Filter by the Agent's labels.
+    description: Filter by the Agent's labels (id).

pages/agents/agent-object-v2.json

@@ -0,0 +1,24 @@
+{
+  "id": 65,
+  "title": null,
+  "first_name": "Billy",
+  "last_name": "Holiday",
+  "email": "[email protected]",
+  "mobile": "07123 456 789",
+  "phone": "0208 123 4567",
+  "street": "8 Albert Road",
+  "state": null,
+  "town": "London",
+  "country": "United Kingdom (GB)",
+  "postcode": "E80 1FA",
+  "latitude": "51.5373258999999990",
+  "longitude": "-0.1496343000000000",
+  "date_created": "2020-02-18T16:13:04.193340Z",
+  "timezone": "Europe/London"
+  "commission_rate": null,
+  "clients": [],
+  "last_updated": "2020-03-16T12:23:39.056867Z",
+  "calendar_colour": "Brown",
+  "labels": [],
+  "extra_attrs": []
+}

pages/agents/agent-object.md → pages/agents/agent-object-v2.md

@@ -1,4 +1,4 @@
-### Agent Object
+### Agent Object (Version 2)
 
 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`.

pages/agents/agent-object-v2.yml

@@ -0,0 +1,162 @@
+attributes:
+  -
+    name: id
+    type: integer
+    description: Unique identifier for the object.
+  -
+    name: first_name
+    type: string
+    description: The user's first name.
+  -
+    name: last_name
+    type: string
+    description: The user's last name.
+  -
+    name: email
+    type: string
+    description: The user's email address.
+  -
+    name: mobile
+    type: string
+    description: The user's mobile number.
+  -
+    name: phone
+    type: string
+    description: The user's phone number.
+  -
+    name: street
+    type: string
+    description: The user's street address.
+  -
+    name: state
+    type: string
+    description: This field is only needed for US users. This value will use the state's 2-letter code.
+  -
+    name: town
+    type: string
+    description: The user's town on address.
+  -
+    name: country
+    type: integer
+    description: |
+      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.
+  -
+    name: postcode
+    type: string
+    description: The user's postcode on address.
+  -
+    name: latitude
+    type: decimal
+    description: The user's addresses latitude.
+  -
+    name: longitude
+    type: decimal
+    description: The user's addresses longitude.
+  -
+    name: date_created
+    type: string
+    description: The date and time the user was created.
+  -
+    name: timezone
+    type: string
+    description: The user's timezone, accepted values are timezone database values.
+  -
+    name: commission_rate
+    type: string
+    description: Percentage of the Agent's commission rate.
+  -
+    name: clients
+    type: array
+    description: An array of Clients which the Agent is related to.
+    children:
+      -
+        name: id
+        type: integer
+        description: Unique identifier for the object.
+      -
+        name: first_name
+        type: string
+        description: User's first name.
+      -
+        name: last_name
+        type: string
+        description: User's last name.
+      -
+        name: email
+        type: string
+        description: User's email address.
+      -
+        name: url
+        type: string
+        description: URL to the Agent's object.
+  -
+    name: last_updated
+    type: string
+    description: The date and time the Agent was last updated.
+  -
+    name: calendar_colour
+    type: string
+    description: Use hex values, like `#fff000`, or use CSS Named colours.
+  -
+    name: labels
+    type: array
+    description: An array of the Agent's labels.
+    children:
+      -
+        name: id
+        type: integer
+        description: Unique identifier for the object.
+      -
+        name: name
+        type: string
+        description: Name of the label.
+      -
+        name: machine_name
+        type: string
+        description: Unique slugified name of the label.
+  -
+    name: extra_attrs
+    type: array
+    description: |
+        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'}`
+
+filters:
+  -
+    name: user__created__gte
+    type: string
+    description: Filter by the date and time the Agent was created.
+  -
+    name: user__created__lte
+    type: string
+    description: Filter by the date and time the Agent was created.
+  -
+    name: user__first_name
+    type: string
+    description: Filter by the Agent's first name.
+  -
+    name: user__last_name
+    type: string
+    description: Filter by the Agent's last name.
+  -
+    name: user__email
+    type: string
+    description: Filter by the Agent's email address.
+  -
+    name: status
+    type: string
+    description: Filter by the Agent's status.
+  -
+    name: distance_address
+    type: string
+    description: Filter by the address.
+  -
+    name: distance_radius
+    type: integer
+    description: Filter by the radius of the address. This is used in conjunction with the `address` filter.
+  -
+    name: labels
+    type: integer
+    description: Filter by the Agent's labels (id).

pages/agents/agents.yml

@@ -1,10 +1,17 @@
 sections:
   -
-    title: Agent Object
-    id: agent-object
-    description: /agents/agent-object.md
-    attributes: /agents/agent-object.yml
-    response: /agents/agent-object.json
+    title: Agent Object (Version 1)
+    id: agent-object-v1
+    description: /agents/agent-object-v1.md
+    attributes: /agents/agent-object-v1.yml
+    response: /agents/agent-object-v1.json
+    response_title: OBJECT
+  -
+    title: Agent Object (Version 2)
+    id: agent-object-v2
+    description: /agents/agent-object-v2.md
+    attributes: /agents/agent-object-v2.yml
+    response: /agents/agent-object-v2.json
     response_title: OBJECT
   -
     title: List all Agents

pages/agents/create-an-agent.json

@@ -1,37 +1,32 @@
 {
-  "status": "success",
-  "role": {
-    "id": 65,
-    "user": {
-      "title": null,
-      "first_name": "Billy",
-      "last_name": "Holiday",
-      "email": "[email protected]",
-      "mobile": "07123 456 789",
-      "phone": "0208 123 4567",
-      "street": "8 Albert Road",
-      "state": null,
-      "town": "London",
-      "country": "United Kingdom (GB)",
-      "postcode": "E80 1FA",
-      "latitude": "51.5373258999999990",
-      "longitude": "-0.1496343000000000",
-      "date_created": "2020-02-18T16:13:04.193340Z",
-      "timezone": "Europe/London"
-    },
-    "commission_rate": null,
-    "clients": [],
-    "last_updated": "2020-03-16T12:23:39.056867Z",
-    "calendar_colour": "Brown",
-    "labels": [],
-    "extra_attrs": [
-      {
-        "id": 1,
-        "value": "1993-06-23",
-        "type": "Date",
-        "machine_name": "user-dob",
-        "name": "Date of birth"
-      }
-    ]
-  }
+  "id": 65,
+  "title": null,
+  "first_name": "Billy",
+  "last_name": "Holiday",
+  "email": "[email protected]",
+  "mobile": "07123 456 789",
+  "phone": "0208 123 4567",
+  "street": "8 Albert Road",
+  "state": null,
+  "town": "London",
+  "country": "United Kingdom (GB)",
+  "postcode": "E80 1FA",
+  "latitude": "51.5373258999999990",
+  "longitude": "-0.1496343000000000",
+  "date_created": "2020-02-18T16:13:04.193340Z",
+  "timezone": "Europe/London",
+  "commission_rate": null,
+  "clients": [],
+  "last_updated": "2020-03-16T12:23:39.056867Z",
+  "calendar_colour": "Brown",
+  "labels": [],
+  "extra_attrs": [
+    {
+      "id": 1,
+      "value": "1993-06-23",
+      "type": "Date",
+      "machine_name": "user-dob",
+      "name": "Date of birth"
+    }
+  ]
 }