User Impersonation - ‘x-impersonate-uuid' usage

API & SDK
1

Originally posted by Anthony Rogers

I would like to know more about how to use User Impersonation

I need to mark jobs as completed by a specific staff member.
The following does not appear to work

curl -X POST "https://api.servicem8.com/api_1.0/job/JOB_UUID_HERE.json" ^
  -H "X-Api-Key: API-KEY-HERE" ^
  -H "x-impersonate-uuid: STAFF_UUID_HERE" ^
  -H "accept: application/json" ^
  -H "content-type: application/json" ^
  -d "{ \"completion_date\": \"2025-09-12 12:00:00\", \"status\": \"Completed\" }"

Please provide a working curl example of an API POST to job/{uuid}.json to complete a job as a specific staff

Cheers

2

I’m having the same issue.
When I use OAuth, the x-impersonate-uuid header works.
But when I use the api key, it doesn’t work.

Is this intentional?

3

Hi Chris,

User impersonation is done by including an x-impersonate-uuid header on the API request, and the value needs to be an active staff UUID in the same ServiceM8 account.

To complete a job via the API, you can POST to /job/{uuid}.json (this endpoint supports both API key and OAuth authentication).

Here’s a working cURL example (API key + impersonation) that sets the job status to Completed and sets completion_date:

curl -X POST "https://api.servicem8.com/api_1.0/job/JOB_UUID_HERE.json" \
  -H "X-Api-Key: API_KEY_HERE" \
  -H "x-impersonate-uuid: STAFF_UUID_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Completed",
    "completion_date": "2026-05-26 12:00:00"
  }'

To confirm who ServiceM8 recorded as completing the job, retrieve the job and check completion_actioned_by_uuid.

If the impersonated UUID isn’t valid/active for that account, the API can return a 403.

If you’re still seeing OAuth succeed but API key not apply the impersonation header, email support@servicem8.com with the response body you’re getting (and the request headers, with the API key removed) so we can verify what’s happening.

Thanks,
Cody

4

Hi Cody.

As you requested, I emailed the support email.

Their response was to tell me to ask my question on this community forum.

I explained that I was referred to that email by you, and they haven’t responded.

Where do I go from here? I feel like I’m in a loop

5

Hi Chris,

Sorry you’ve been bounced around. User Impersonation is supported when you authenticate via OAuth 2.0 (Public Application).

To impersonate a staff member, set the x-impersonate-uuid header on the request, and the value must be an active, valid staff UUID for the current account.

To mark a job as completed via the API, POST to /job/{uuid}.json with status set to Completed (the status field is required), and you can also set completion_date.

If you’re using OAuth for this endpoint, it requires the manage_jobs scope. You can authenticate by supplying the access token prefixed with Bearer on the HTTP Authorization header.

curl -X POST "https://api.servicem8.com/api_1.0/job/JOB_UUID_HERE.json" \
  -H "Authorization: Bearer ACCESS_TOKEN_HERE" \
  -H "x-impersonate-uuid: STAFF_UUID_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Completed",
    "completion_date": "2026-06-02 12:00:00"
  }'

Thanks,
Cody

6

Hi Cody.

Does the x-impersonate-uuid header work when using API Key authentication?

7

Hi Chris,

Sorry, I got this wrong in my earlier reply. I initially thought x-impersonate-uuid was supported with API key authentication, but after checking this properly, it is only supported when authenticating with OAuth 2.0.

So the direct answer is: no, x-impersonate-uuid does not work with API key authentication.

To impersonate a staff member, use OAuth and pass the access token in the Authorization header. The impersonated UUID must be an active staff UUID in the same account.

curl -X POST "https://api.servicem8.com/api_1.0/job/JOB_UUID_HERE.json" \
  -H "Authorization: Bearer ACCESS_TOKEN_HERE" \
  -H "x-impersonate-uuid: STAFF_UUID_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Completed",
    "completion_date": "2026-06-02 12:00:00"
  }'

For this endpoint, the OAuth app needs the manage_jobs scope.

Sorry again for the confusion and for sending you down the wrong path.

Thanks,
Cody

8

Hi Chris,

Yes, you can use the x-impersonate-uuid header on API requests, and that includes requests authenticated with an API key.

User impersonation is done by adding the x-impersonate-uuid header to your API request, and the value must be an active staff UUID in the same account.

The Job update endpoint (POST /job/{uuid}.json) supports API key authentication (header X-Api-Key) as well as OAuth.

If the impersonation UUID isn’t valid/active, you’ll typically see a 403 Forbidden response.

To mark a job completed via POST /job/{uuid}.json, status is required (valid values include Completed) and you can also set completion_date.

Also, completion_actioned_by_uuid is a read-only field on the Job record, so impersonation is the mechanism that controls who ServiceM8 records as having completed it.

If you’re still seeing OAuth work but API key not apply the impersonation, reply here with the HTTP status code and response body you’re getting (with credentials removed) so we can pinpoint what’s happening.

Thanks,
Cody