Job Photo API Endpoints & Permissions for Custom Add-ons

Developer API & SDK
1

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

2

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.

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, create attachment, download attachment file, and 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