# Job Photo API Endpoints & Permissions for Custom Add-ons **URL:** \ **Category:** API & SDK\ **Created:** [October 13, 2026, 2:53am UTC](https://community.servicem8.com/t/job-photo-api-endpoints-permissions-for-custom-add-ons/1230 "2026-10-13T02:53:35Z")\ **Posts on this page:** 2\ **Page:** 1
**Author:** ![nicole\_fahey](https://avatars.discourse-cdn.com/v4/letter/n/a5b964/32.png) [@nicole\_fahey](https://community.servicem8.com/u/nicole_fahey)\ **Post date:** [October 13, 2026, 2:53am UTC](https://community.servicem8.com/t/job-photo-api-endpoints-permissions-for-custom-add-ons/1230/1 "2026-10-13T02:53:35Z")
Hi ServiceM8 Developer Team, We’re developing a custom Job Plan add-on for our roofing business, launched directly from an existing ServiceM8 Job Card. The add-on allows onsite staff to manage individual tasks, and we’re now looking to add photo uploads to those tasks. **What we’re trying to achieve:** - Staff open the add-on from a ServiceM8 Job Card. - Select a task and take or choose a photo. - The photo is saved against that existing ServiceM8 job. - The add-on retains a photo reference so it can display the photo against the relevant task. - Photos remain accessible through the normal ServiceM8 job where supported. We’ve reviewed the developer documentation and identified the `publish_job_photos` and `read_job_photos` scopes, but haven’t been able to verify the endpoints or request formats associated with them. We also found the generic Attachments API, which appears to require the broader `manage_attachments` permission. Could someone from the developer team please clarify: 1. Are `publish_job_photos` and `read_job_photos` supported for custom Job Action add-ons? If so, what endpoints and HTTP methods do they use? 2. What request format, supported file types and size limits apply? 3. Can uploaded photos be retrieved using a stable UUID or similar reference? 4. Will uploaded photos appear in the normal ServiceM8 job photos or diary? 5. Can a mobile Job Action support taking photos with the device camera or selecting existing photos? 6. Is there a supported way to achieve this without requesting `manage_attachments`? We’re particularly interested in using the **least-permission approach** , as the add-on doesn’t need to manage unrelated job attachments. Our photo interface is already built and tested locally. We’re holding off on connecting it until we can confirm the supported API and permissions. Thanks for any guidance or documentation references! Kind regards, Nicci ---
**Author:** ![Cody](https://sea2.discourse-cdn.com/flex002/user_avatar/community.servicem8.com/cody/32/52_2.png) [@Cody](https://community.servicem8.com/u/Cody)\ **Post date:** [October 16, 2026, 2:56am UTC](https://community.servicem8.com/t/job-photo-api-endpoints-permissions-for-custom-add-ons/1230/2 "2026-10-16T02:56:36Z")
Hi Nicci, You can upload a photo to an existing job using the Attachments API, retain its attachment UUID against your task, and have the uploaded file appear in that job’s Diary. The supported attachment upload workflow requires `manage_attachments`. **1. Photo scopes and attachment permissions** `publish_job_photos` and `read_job_photos` are listed OAuth scopes for adding and reading job photos. For the attachment endpoints below, however, the required scopes are `manage_attachments` for creation/upload and `read_attachments` for retrieval/download. Don’t substitute the photo scopes for these endpoint requirements. The Attachments API covers account attachments, including photos, PDFs and other files; `manage_attachments` grants creation, update, deletion and upload access, rather than being restricted to files created by your add-on. **2. Upload request** For new uploads, use a single `multipart/form-data` request to `POST https://api.servicem8.com/api_1.0/attachment.json`. Supply exactly one non-empty file named `file`, `related_object=job`, and the existing job UUID in `related_object_uuid`. An optional `attachment_name` sets the display name. ```bash curl --request POST 'https://api.servicem8.com/api_1.0/attachment.json' \ --include \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Accept: application/json' \ --form 'file=@/path/to/roof-photo.jpg' \ --form 'related_object=job' \ --form 'related_object_uuid=YOUR_EXISTING_JOB_UUID' \ --form 'attachment_name=Roof task photo' ``` This follows the multipart upload format, with `.jpg` as an example image extension. The filename must include an extension. Let cURL set the multipart boundary; don’t JSON-encode the form fields or base64-encode the file. `file_type` is derived from the filename and must not be supplied in this multipart request. Uploads exceeding the server’s upload size limit return HTTP `413`. **3. Retaining and retrieving the photo** A successful multipart upload returns `201 Created`, with the attachment UUID in both `X-Record-UUID` and the JSON body’s `uuid`. Store that UUID alongside your task as the photo reference. Using that UUID, the retrieval endpoints are: - Metadata: `GET /api_1.0/dboattachment/{uuid}.json`, requiring `read_attachments`. - File: `GET /api_1.0/attachment/{uuid}.file`, requiring `read_attachments`. The file endpoint returns a `302` redirect to storage. Treat its destination URL as temporary and request the endpoint again when you need a fresh URL. Don’t forward your ServiceM8 API credentials to the redirect destination. **4. Visibility in ServiceM8** A successful upload linked with `related_object=job` and that job’s UUID makes the attachment available through the API and in the specified Job Diary. **5. Mobile Job Actions** A mobile Job Action is supported through a manifest action with `type: "app"` and `entity: "job"`; the job context is supplied automatically when the action invokes your backend. Relevant references: [upload guide](https://developer.servicem8.com/docs/attaching-files-to-a-job-diary), [create attachment](https://developer.servicem8.com/reference/createattachments), [download attachment file](https://developer.servicem8.com/reference/downloadattachmentfile), and [manifest reference](https://developer.servicem8.com/docs/manifest-reference). We’ll confirm with the team the endpoint mapping and availability of the narrower photo scopes for custom Job Actions, whether your workflow can avoid `manage_attachments`, the complete supported image formats and numeric upload limit, camera/photo-library selection inside a mobile Job Action, and visibility in the job’s photo gallery beyond the Diary. Thanks, Cody