Update docs for Roles V2

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-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: created__gte
+    type: string
+    description: Filter by the date and time the Agent was created.
+  -
+    name: created__lte
+    type: string
+    description: Filter by the date and time the Agent was created.
+  -
+    name: first_name
+    type: string
+    description: Filter by the Agent's first name.
+  -
+    name: last_name
+    type: string
+    description: Filter by the Agent's last name.
+  -
+    name: 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.

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"
+    }
+  ]
 }

pages/agents/create-an-agent.py

@@ -2,21 +2,19 @@
 
 headers = {'Authorization': 'token <API KEY>'}
 data = {
-    'user': {
-        'first_name': 'Billy',
-        'last_name': 'Bob',
-        'email': '[email protected]',
-        'mobile': '07123456789',
-        'phone': '02081234567',
-        'street': '177 South Lambeth Road',
-        'state': None,
-        'town': 'London',
-        'country': 183,
-        'postcode': 'SW8 1XP',
-        'latitude': '51.5549',
-        'longitude': '-0.1084',
-        'timezone': 'Europe/London',
-    },
+    'first_name': 'Billy',
+    'last_name': 'Bob',
+    'email': '[email protected]',
+    'mobile': '07123456789',
+    'phone': '02081234567',
+    'street': '177 South Lambeth Road',
+    'state': None,
+    'town': 'London',
+    'country': 183,
+    'postcode': 'SW8 1XP',
+    'latitude': '51.5549',
+    'longitude': '-0.1084',
+    'timezone': 'Europe/London',
     'commission_rate': 10.1,
     'calendar_colour': 'LimeGreen',
     'extra_attrs': {'user_dob': '1993-06-23'},

pages/agents/delete-an-agent.json

@@ -0,0 +1 @@
+{"message": "Successfully deleted role 65: Billy Holiday"}

pages/agents/delete-an-agent.md

@@ -0,0 +1,4 @@
+### Delete an Agent
+
+Deletes an existing agent. You only need to specify the unique
+`id` of the Agent to get the correct details. This will put the agent in the trash but will not permanently delete them.

pages/agents/delete-an-agent.py

@@ -0,0 +1,5 @@
+import pprint, requests
+
+headers = {'Authorization': 'token <API KEY>'}
+r = requests.delete('https://secure.tutorcruncher.com/api/agents/', headers=headers)
+pprint.pprint(r.json())

pages/agents/get-an-agent.json

@@ -1,22 +1,20 @@
 {
   "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"
-  },
+  "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",