Merge pull request #197 from tutorcruncher/roles-profile-pic-doc

HenryTraill · web-flow · commit 0ab855fd4940 · 2025-04-10T17:11:41.000+01:00
Added docs adding profile photos to roles
diff --git a/pages/agents/agent-object-v2.json b/pages/agents/agent-object-v2.json
@@ -14,7 +14,8 @@
   "latitude": "51.5373258999999990",
   "longitude": "-0.1496343000000000",
   "date_created": "2020-02-18T16:13:04.193340Z",
-  "timezone": "Europe/London"
+  "timezone": "Europe/London",
+  "photo": "https://secure.tutorcruncher.com/media/photo/65.jpg",
   "commission_rate": null,
   "clients": [],
   "last_updated": "2020-03-16T12:23:39.056867Z",
diff --git a/pages/agents/agent-object-v2.md b/pages/agents/agent-object-v2.md
@@ -1,4 +1,4 @@
 ### Agent Object (Version 2)
 
-Agent objects, Affiliates in TutorCruncher, includes basic user information including fields that are only linked to the Agent Role. 
+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`.
diff --git a/pages/agents/agent-object-v2.yml b/pages/agents/agent-object-v2.yml
@@ -61,6 +61,10 @@ attributes:
     name: timezone
     type: string
     description: The user's timezone, accepted values are timezone database values.
+  -
+    name: photo
+    type: string
+    description: The URL to the Agent's photo.
   -
     name: commission_rate
     type: string
diff --git a/pages/clients/client-object-v2.json b/pages/clients/client-object-v2.json
@@ -14,7 +14,8 @@
   "latitude": "51.5249280000000027",
   "longitude": "-0.0944689940000000",
   "date_created": "2020-01-01T12:00:00.000000Z",
-  "timezone": null
+  "timezone": null,
+  "photo": "https://secure.tutorcruncher.com/media/photo/44bc4e56.jpg",
   "status": "live",
   "is_taxable": true,
   "received_notifications": [
diff --git a/pages/clients/client-object-v2.yml b/pages/clients/client-object-v2.yml
@@ -61,6 +61,10 @@ attributes:
     name: timezone
     type: string
     description: The user's timezone, accepted values are timezone database values.
+  -
+    name: photo
+    type: string
+    description: The URL to the Client's photo.
   -
     name: status
     type: string
diff --git a/pages/contractors/contractor-object-v2.json b/pages/contractors/contractor-object-v2.json
@@ -15,6 +15,7 @@
   "longitude": "-0.1370000000000005",
   "date_created": "2018-11-22T09:23:55.297608Z",
   "timezone": null,
+  "photo": "https://secure.tutorcruncher.com/media/photo/44bc4e56.jpg",
   "status": "approved",
   "default_rate": null,
   "qualifications": [],
diff --git a/pages/contractors/contractor-object-v2.yml b/pages/contractors/contractor-object-v2.yml
@@ -61,6 +61,10 @@ attributes:
     name: timezone
     type: string
     description: The user's timezone, accepted values are timezone database values.
+  -
+    name: photo
+    type: string
+    description: The URL to the Contractor's photo.
   -
     name: status
     type: string
diff --git a/pages/creating-updating-users/creating-updating-users.md b/pages/creating-updating-users/creating-updating-users.md
@@ -6,3 +6,4 @@ You can create a user without an email address, however, you will not be able to
 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.
 
+Profile photos can be optionally added or updated for all user roles — [Agents](#agents), [Clients](#clients), [Contractors](#contractors), and [Recipients](#recipients) — by including a `photo` field with a valid image URL when creating or updating a user. If the image is valid and accessible, it will be downloaded, processed into thumbnails, and included in the response. If the `photo` field is omitted during an update, the current photo remains unchanged. To remove an existing photo, set the `photo` field to `null`. Invalid, corrupted, or inaccessible image URLs will result in a `400 Bad Request` with an appropriate error message.
diff --git a/pages/creating-updating-users/creating-updating-users.py b/pages/creating-updating-users/creating-updating-users.py
@@ -1,12 +1,14 @@
 import requests
 
 headers = {'Authorization': 'token <API KEY>'}
+
 data = {
-    'user': {
-        'email': 'billy_bob@example.com',
-        'last_name': 'Bob'
-        # ...
-    },
-    # ...
+  "id": 568433,
+  "email": "billy_bob@example.com",
+  "last_name": "Bob",
+  "mobile": "07842 485 204",
+  "photo": "https://photo_url.com/200/300"
+   #...
 }
+
 requests.post('...', json=data, headers=headers)
diff --git a/pages/recipients/recipient-object-v2.json b/pages/recipients/recipient-object-v2.json
@@ -14,7 +14,8 @@
   "latitude": "51.5249280000000027",
   "longitude": "-0.0944689940000000",
   "date_created": "2019-11-24T16:11:48.312507Z",
-  "timezone": null
+  "timezone": null,
+  "photo": "https://secure.tutorcruncher.com/media/photo/44bc4e56.jpg",
   "default_rate": null,
   "paying_client": {
     "id": 3,
diff --git a/pages/recipients/recipient-object-v2.yml b/pages/recipients/recipient-object-v2.yml
@@ -61,6 +61,10 @@ attributes:
     name: timezone
     type: string
     description: The user's timezone, accepted values are timezone database values.
+  -
+    name: photo
+    type: string
+    description: The URL to the Recipient's photo.
   -
     name: default_rate
     type: decimal
diff --git a/pages/roles_versioning/roles_versioning.md b/pages/roles_versioning/roles_versioning.md
@@ -28,6 +28,7 @@ but the data we return will be dependent on the version set on your Branch. See
 ### Other changes include:
 * Version 2 allows you to update the role by ID now instead of email or name by posting to the endpoint for that specific role. e.g. to update the Client with ID 1234 I can use post to `secure.tutorcruncher.com/api/clients/1234/` with a dictionary of data to update that client and its related user data.
 * Version 2 will not match on a users first and last name.
+* Version 2 contains a new field `photo` for all roles containing a URL to the photo of the user. You can update a user's photo by sending a URL to the `photo` field in the request. For more info checkout the [Creating/Updating User](#creating-updating-users) section.
 * In Version 1 you could update a role by posting to the list page e.g. `secure.tutorcruncher.com/api/clients/` and update a role based on the email passed. In Version 2 this will return an error as it is expecting to create a user with that email. 
 * In both Versions, if I have a client with the email `example@example.com` and I post to the list page for contractors with the same email then it will create a new contractor role that is linked to the existing client.
 * We no longer send emails about failed requests, the errors are returned when the request fails and should be handled then.
diff --git a/pages/webhooks/webhook-object.json b/pages/webhooks/webhook-object.json
@@ -47,8 +47,9 @@
         "country": null,
         "postcode": null,
         "timezone": null,
-        "title": null
+        "title": null,
+        "photo": "https://secure.tutorcruncher.com/media/photo/65.jpg"
       }
     }
   ]
-}
+}

Original file line number	Diff line number	Diff line change
`@@ -6,3 +6,4 @@ You can create a user without an email address, however, you will not be able to`
`6`	`6`	`include the users last name when creating/updating as this field is required. Any other role specific required`
`7`	`7`	`fields are specified on the endpoint description.`
`8`	`8`
	`9`	+Profile photos can be optionally added or updated for all user roles — [Agents](#agents), [Clients](#clients), [Contractors](#contractors), and [Recipients](#recipients) — by including a `photo` field with a valid image URL when creating or updating a user. If the image is valid and accessible, it will be downloaded, processed into thumbnails, and included in the response. If the `photo` field is omitted during an update, the current photo remains unchanged. To remove an existing photo, set the `photo` field to `null`. Invalid, corrupted, or inaccessible image URLs will result in a `400 Bad Request` with an appropriate error message.