Task commands

Task Commands are used for updating task states, positions, and assignments. Commands are processed asynchronously and support batching for efficient bulk operations.

Please find the tehnical API specification here for task commands.

Available actions

Action	Description
`update`	Update task data (including position)
`assign`	Assign task to a worker
`reassign`	Reassign to a different worker
`unassign`	Remove assignee
`accept`	Worker accepts the task
`unaccept`	Worker reverts acceptance
`reject`	Worker rejects assignment
`transit`	Worker traveling to location
`activate`	Worker begins work
`complete`	Mark as completed
`fail`	Mark as failed
`cancel`	Cancel the task
`restart`	Restart a failed task

Creating a task command

HTTP request

POST https://api.gsmtasks.com/task_commands/

Request fields

Field	Type	Required	Description
`task`	URL	Yes	The task URL this command applies to
`external_id`	String	Yes	Unique identifier generated by the client
`time`	DateTime	Yes	When the interaction occurred
`action`	String	Yes	The action to perform (see Available Actions)
`assignee`	URL	For assign/reassign	The user to assign the task to
`task_data`	Object	For update	Data to update on the task
`notes`	String	No	Optional notes for the command
`location`	Point	No	Geographic location where command was issued

Single command example

{
  "task": "https://api.gsmtasks.com/tasks/e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05/",
  "external_id": "e31017a8889b8f106bd59f5f6febe40eb1f8c51a",
  "time": "2022-09-09T13:43:00.580000+03:00",
  "action": "transit"
}

Response (accepted)

{
  "id": "856ae165-9595-4f1d-8377-6f4c4db073d1",
  "url": "https://api.gsmtasks.com/task_commands/856ae165-9595-4f1d-8377-6f4c4db073d1/",
  "account": "https://api.gsmtasks.com/accounts/a6f60fdf-d87b-4c5d-b5ec-67a90cd16236/",
  "task": "https://api.gsmtasks.com/tasks/e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05/",
  "external_id": "e31017a8889b8f106bd59f5f6febe40eb1f8c51a",
  "time": "2022-09-09T13:43:00.580000+03:00",
  "action": "transit",
  "user": "https://api.gsmtasks.com/users/8495e730-e5c2-400c-8ffc-ad830d4fa6a2/",
  "notes": "",
  "location": null,
  "assignee": null,
  "state": "accepted",
  "error_message": "",
  "task_data": {},
  "accepted_at": "2022-09-09T13:43:01.052384+03:00",
  "rejected_at": null,
  "created_at": "2022-09-09T13:43:00.993254+03:00",
  "updated_at": "2022-09-09T13:43:01.052490+03:00"
}

Response (rejected)

When a command cannot be applied (e.g., invalid state transition or permission denied):

{
  "id": "71dd847f-596d-48f1-bf50-db6c8cee4796",
  "url": "https://api.gsmtasks.com/task_commands/71dd847f-596d-48f1-bf50-db6c8cee4796/",
  "account": "https://api.gsmtasks.com/accounts/a6f60fdf-d87b-4c5d-b5ec-67a90cd16236/",
  "task": "https://api.gsmtasks.com/tasks/e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05/",
  "external_id": "86ea541b917fa464023cfeef05dc6d79df02bf10",
  "time": "2022-09-09T13:46:32.556000+03:00",
  "action": "accept",
  "user": "https://api.gsmtasks.com/users/8495e730-e5c2-400c-8ffc-ad830d4fa6a2/",
  "notes": "",
  "location": null,
  "assignee": null,
  "state": "rejected",
  "error_message": "Can't switch from state 'accepted' using method 'accept'",
  "task_data": {},
  "accepted_at": null,
  "rejected_at": "2022-09-09T13:46:32.735993+03:00",
  "created_at": "2022-09-09T13:46:32.705774+03:00",
  "updated_at": "2022-09-09T13:46:32.736151+03:00"
}

Batch commands

HTTP request

POST https://api.gsmtasks.com/task_commands/

Request

[
  {
    "task": "https://api.gsmtasks.com/tasks/e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05/",
    "external_id": "e31017a8889b8f106bd59f5f6febe40eb1f8c51a",
    "time": "2022-09-09T13:43:00.580000+03:00",
    "action": "transit"
  },
  {
    "task": "https://api.gsmtasks.com/tasks/e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05/",
    "external_id": "461505e9-38b5-4109-a15f-85375d41c4b8",
    "time": "2022-09-09T13:48:00.580000+03:00",
    "action": "activate"
  },
  {
    "task": "https://api.gsmtasks.com/tasks/e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05/",
    "external_id": "63ea82de-e579-436d-a9b0-dceb42cc1ec0",
    "time": "2022-09-09T13:51:00.580000+03:00",
    "action": "complete"
  }
]

Updating task data

Use the update action with task_data to modify task fields.

Task data fields

Field	Type	Description
`position`	Float	Task order in worker’s list
`scheduled_time`	DateTime	Scheduled time for the task
`duration`	Duration	Expected task duration
`metafields`	Object	Custom metadata
`address`	Object	Task address
`contact_address`	Object	Contact address
`route`	URL	Route assignment

Update position (reordering)

Change the order of tasks in a worker’s list.

{
  "task": "https://api.gsmtasks.com/tasks/e1f228fe-cf4f-44ef-ad9f-6b5d4034a25c/",
  "external_id": "c3d4e5f6789012345678901234567890abcdef",
  "time": "2022-09-19T06:19:25.482Z",
  "action": "update",
  "task_data": {
    "position": 16343544103.775824
  }
}

Calculating position values

// Insert between two tasks
const newPosition = (taskAbove.position + taskBelow.position) / 2;
 
// Insert at the beginning
const newPosition = firstTask.position - 100;
 
// Insert at the end
const newPosition = lastTask.position + 100;

💡

Worker reordering is controlled by the account setting feature_allow_worker_reordering.

Update scheduled time

Set when the task should be executed.

{
  "task": "https://api.gsmtasks.com/tasks/e1f228fe-cf4f-44ef-ad9f-6b5d4034a25c/",
  "external_id": "a1b2c3d4e5f6789012345678901234567890abcd",
  "time": "2022-09-19T06:19:25.482Z",
  "action": "update",
  "task_data": {
    "scheduled_time": "2022-09-20T09:00:00Z"
  }
}

Update metafields

Add or modify custom metadata on a task.

{
  "task": "https://api.gsmtasks.com/tasks/e1f228fe-cf4f-44ef-ad9f-6b5d4034a25c/",
  "external_id": "b2c3d4e5f6789012345678901234567890abcde",
  "time": "2022-09-19T06:19:25.482Z",
  "action": "update",
  "task_data": {
    "metafields": {
      "priority": "high",
      "package_size": "large"
    }
  }
}

Update address

Change the task’s destination address.

{
  "task": "https://api.gsmtasks.com/tasks/e1f228fe-cf4f-44ef-ad9f-6b5d4034a25c/",
  "external_id": "d4e5f6789012345678901234567890abcdef01",
  "time": "2022-09-19T06:19:25.482Z",
  "action": "update",
  "task_data": {
    "address": {
      "raw_address": "123 New Street, London, UK",
      "location": {
        "type": "Point",
        "coordinates": [-0.1276, 51.5074]
      }
    }
  }
}

Update route

Assign the task to a specific route.

{
  "task": "https://api.gsmtasks.com/tasks/e1f228fe-cf4f-44ef-ad9f-6b5d4034a25c/",
  "external_id": "e5f6789012345678901234567890abcdef0123",
  "time": "2022-09-19T06:19:25.482Z",
  "action": "update",
  "task_data": {
    "route": "https://api.gsmtasks.com/routes/a1b2c3d4-e5f6-7890-abcd-ef0123456789/"
  }
}

Update duration

Set the expected time to complete the task.

{
  "task": "https://api.gsmtasks.com/tasks/e1f228fe-cf4f-44ef-ad9f-6b5d4034a25c/",
  "external_id": "f6789012345678901234567890abcdef012345",
  "time": "2022-09-19T06:19:25.482Z",
  "action": "update",
  "task_data": {
    "duration": "00:30:00"
  }
}

Assignment commands

Assign task

Assign an unassigned task to a worker.

{
  "task": "https://api.gsmtasks.com/tasks/abc123/",
  "external_id": "cmd-assign-001",
  "time": "2022-09-09T09:00:00Z",
  "action": "assign",
  "assignee": "https://api.gsmtasks.com/users/worker123/"
}

Reassign with position

Move a task to a different worker and set its position in their list.

{
  "task": "https://api.gsmtasks.com/tasks/e1f228fe-cf4f-44ef-ad9f-6b5d4034a25c/",
  "external_id": "f93b4be79be47e9913ed89c8d6e9bca9e2c21409",
  "time": "2022-09-19T06:19:25.482Z",
  "action": "reassign",
  "assignee": "https://api.gsmtasks.com/users/8495e730-e5c2-400c-8ffc-ad830d4fa6a2/",
  "task_data": {
    "position": 16343544103.775824
  }
}

Unassign task

Remove a task from its current worker.

{
  "task": "https://api.gsmtasks.com/tasks/abc123/",
  "external_id": "cmd-unassign-001",
  "time": "2022-09-09T09:00:00Z",
  "action": "unassign"
}

Tasks Orders