Skip to content

Lock action

POST/actions/lock

Mobile API · Actions

Create Lock action.

Required permissionmobile.action.lock: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
lockCodestring
A lock code. Only required for Macs.
Must match the pattern ^[0-9]{6}$.
lockScreenMessagestring
A message that's shown on the device's lock screen. Only supported on Android and iOS.
Must be at most 500 characters long.
phoneNumberstring
The phone number that's shown on locked iPhones.
Must match the pattern ^(\+?\d+|.{0})$. Must be at most 50 characters long.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/mobile/v1/actions/lock" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"arguments\": {
    \"lockCode\": 123456
  },
  \"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/lock",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'arguments': {'lockCode': 123456},
    '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": {
    "lockCode": 123456
  },
  "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/lock" -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/lock", strings.NewReader(`{
  "arguments": {
    "lockCode": 123456
  },
  "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/lock", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "arguments": {
    "lockCode": 123456
  },
  "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": "lock",
      "state": "accepted"
    }
  ]
}

See the guide for a narrative walkthrough of this API.