Skip to content

Locate action

POST/actions/locate

Mobile API · Actions

Create Locate action.

Required permissionmobile.action.locate:create

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
fields query array of string No The fields to return in a partial response.
view query string No Type of view to be returned in response.
Must be one of: basic, summary, full.

Request body

Content type: application/json

Request body fields

endpointsarray of string (uuid)required
List of endpoint IDs.
Must contain at most 50 items.
argumentsobjectrequired
Parameter object.
Show child attributesHide child attributes
reasonstringrequired
The reason for locating the device(s). Will be logged in the Sophos Mobile privacy log.
Must be at most 255 characters long.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/mobile/v1/actions/locate" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"arguments\": {
    \"reason\": \"Device is lost and must be located.\"
  },
  \"endpoints\": [
    \"dd40830b-b103-4f9a-ae02-bbf0d792466d\",
    \"e7e88612-d9b1-4e2f-b248-f2fad48579e4\"
  ]
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/mobile/v1/actions/locate",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'arguments': {'reason': 'Device is lost and must be located.'},
    'endpoints': [   'dd40830b-b103-4f9a-ae02-bbf0d792466d',
                     'e7e88612-d9b1-4e2f-b248-f2fad48579e4']},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "arguments": {
    "reason": "Device is lost and must be located."
  },
  "endpoints": [
    "dd40830b-b103-4f9a-ae02-bbf0d792466d",
    "e7e88612-d9b1-4e2f-b248-f2fad48579e4"
  ]
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/mobile/v1/actions/locate" -Headers $headers -Body $body -ContentType "application/json"


package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/mobile/v1/actions/locate", strings.NewReader(`{
  "arguments": {
    "reason": "Device is lost and must be located."
  },
  "endpoints": [
    "dd40830b-b103-4f9a-ae02-bbf0d792466d",
    "e7e88612-d9b1-4e2f-b248-f2fad48579e4"
  ]
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/mobile/v1/actions/locate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "arguments": {
    "reason": "Device is lost and must be located."
  },
  "endpoints": [
    "dd40830b-b103-4f9a-ae02-bbf0d792466d",
    "e7e88612-d9b1-4e2f-b248-f2fad48579e4"
  ]
}),
});
const data = await response.json();
console.log(data);

Responses

201 — The action create response.

Response fields

createdarray of object
List of created actions.
Action object.
Show child attributesHide child attributes
idstring (uuid)
The action ID.
tenantobject
Tenant this resource belongs to.
Show child attributesHide child attributes
idstring (uuid)required
namestring
deviceobject
A device reference.
Show child attributesHide child attributes
idstring (uuid)required
Unique ID of the device.
namestring
The device name.
typestring
The action type.
namestring
The action name.
statestring
The action status.
errorstring
The action's error description.
propertiesobject
The action properties.
scheduledAtstring (date-time)
Time when the action must be executed.
executedAtstring (date-time)
Time when the action was executed.
createdAtstring (date-time)
Time when the action was created.
createdByobject
Principal reference.
Show child attributesHide child attributes
idstring (uuid)
Principal ID.
typestring (enum)required
Principal type.
Must be one of: user, service, system.
accountIdstring (uuid)
Account ID.
accountTypestring (enum)
Account type.
Must be one of: partner, tenant, organization.
namestring
Principal name or email.
updatedAtstring (date-time)
Time when the action was updated.
updatedByobject
Principal reference.
Show child attributesHide child attributes
idstring (uuid)
Principal ID.
typestring (enum)required
Principal type.
Must be one of: user, service, system.
accountIdstring (uuid)
Account ID.
accountTypestring (enum)
Account type.
Must be one of: partner, tenant, organization.
namestring
Principal name or email.
errorsobject
Action create error object.
Show child attributesHide child attributes
failedToCreateobject
Details why the action could not be created.
Show child attributesHide child attributes
endpointsNotFoundarray of string (uuid)
List of unknown endpoints.
endpointsInWrongStatearray of string (uuid)
List of endpoints with wrong status.
endpointsWithUnsupportedPlatformarray of string (uuid)
List of endpoints with unsupported platforms for the action.
endpointsWithUnsatisfiedArgumentsarray of string (uuid)
List of endpoints with missing mandatory arguments for the action.

Errors

Status Meaning
400 Invalid request.
401 Unauthorized.
403 Forbidden.
409 Conflicting modification.
422 Maximum number of actions exceeded.
429 Too many requests. See Retry-After header.
500 Internal server error.

All error responses share the same shape — see the error response object.

Response examples

201

{
  "created": [
    {
      "id": "ec09add5-a752-4b6e-b1b6-b89000252edb",
      "tenant": {
        "id": "b8a75c7d-7492-4009-9f95-8c815551dc55",
        "name": "The name of the tenant"
      },
      "device": {
        "id": "7670382c-9027-46ff-b51d-996c8d8ff8c2",
        "name": "My iPhone"
      },
      "type": "locate",
      "state": "accepted"
    }
  ]
}

See the guide for a narrative walkthrough of this API.