📋 Managing Tasks

Retrieve, list, update, and cancel tasks through the API.

Response Envelope

All API responses are wrapped in a standard envelope with statusIndicator, statusCode, message, data (the actual payload), and metadata (timestamp, correlationId, path, duration). The examples below show the full envelope structure.

Get Task by ID

Retrieve the full details of a single task by its ID.

GET /api/v1/tasks/:id

Path Parameters

Parameter	Type	Description
`id`	`number`	The task ID

Example Request

curl -X GET https://api.deliverty.com/api/v1/tasks/1042 \
  -H "x-api-key: dh_live_a1b2c3d4e5f6g7h8i9j0"

Response: 200 OK — Returns the full task object including customer, locations, packages, agent assignment, and current status.

List Tasks

Retrieve a paginated list of tasks. Results are scoped to the authenticated channel's organization and support filtering and sorting.

GET /api/v1/tasks

Query Parameters

Parameter	Type	Default	Description
`page`	`number`	`1`	Page number
`limit`	`number`	`20`	Items per page (max 100)
`status`	`string`	—	Filter by status: `new`, `awaiting_assignment`, `assigned`, `accepted`, `in_transit`, `completed`, `cancelled`
`taskType`	`string`	—	Filter by task type: `delivery`, `pickup`, `return`, `transfer`
`customerId`	`number`	—	Filter by customer ID
`agentId`	`number`	—	Filter by assigned agent ID
`channelId`	`number`	—	Filter by channel ID
`locationId`	`number`	—	Filter by location ID
`timeToServe`	`string`	—	Filter by time to serve: `asap` or `scheduled`
`scheduledFrom`	`string`	—	Filter tasks scheduled on or after this ISO 8601 date
`scheduledTo`	`string`	—	Filter tasks scheduled on or before this ISO 8601 date
`sortBy`	`string`	`createdAt`	Sort field: `createdAt`, `updatedAt`, `status`
`sortOrder`	`string`	`DESC`	Sort direction: `ASC` or `DESC`

Example Request

curl -X GET "https://api.deliverty.com/api/v1/tasks?status=in_transit&page=1&limit=10" \
  -H "x-api-key: dh_live_a1b2c3d4e5f6g7h8i9j0"

Response: 200 OK

{
  "statusIndicator": "SUCCESS",
  "statusCode": 200,
  "message": "Request processed successfully",
  "data": {
    "items": [
      {
        "id": 1042,
        "name": "Delivery to Hamra",
        "code": "TSK-2026-001042",
        "taskType": "delivery",
        "status": "in_transit",
        "timeToServe": "asap",
        "scheduledAt": "2026-02-16T12:30:00.000Z",
        "assignedAt": "2026-02-16T10:35:00.000Z",
        "acceptedAt": "2026-02-16T10:36:00.000Z",
        "startedAt": "2026-02-16T10:37:00.000Z",
        "completedAt": null,
        "description": "Delivery to Hamra",
        "notes": "Call customer before arrival.",
        "customerId": 87,
        "customer": {
          "id": 87,
          "userId": 120,
          "customerType": "regular",
          "user": {
            "id": 120,
            "firstName": "Jane",
            "lastName": "Smith",
            "email": "jane@example.com",
            "phoneNumber": "71123456",
            "countryCode": "+961"
          }
        },
        "agentId": 12,
        "agent": {
          "id": 12,
          "userId": 45,
          "agentType": "employed",
          "user": {
            "id": 45,
            "firstName": "Ahmad",
            "lastName": "Courier",
            "email": "ahmad@deliverty.com",
            "phoneNumber": "71000000",
            "countryCode": "+961"
          }
        },
        "courierType": "internal",
        "courierId": null,
        "courier": null,
        "paymentId": null,
        "locationId": 5,
        "location": {
          "id": 5,
          "address": "456 Hamra Street, Beirut",
          "latitude": "33.88860000",
          "longitude": "35.49550000"
        },
        "channelId": 5,
        "organizationId": 12,
        "parentId": null,
        "children": [],
        "integrationData": null,
        "createdAt": "2026-02-16T10:30:00.000Z",
        "updatedAt": "2026-02-16T10:37:00.000Z",
        "isDelayed": false,
        "autoAssignmentStatus": "not_requested",
        "autoAssignmentFailureReason": null
      }
    ],
    "count": 47
  },
  "metadata": {
    "timestamp": "2026-02-16T12:46:06.825Z",
    "correlationId": "0f0f2227-316e-4019-a2e0-e0962e18d4d9",
    "path": "/v1/tasks?status=in_transit&page=1&limit=10",
    "duration": 7
  }
}

Update Task

Update a task's mutable fields. Only tasks in NEW or AWAITING_ASSIGNMENT status can be updated via the API.

PATCH /api/v1/tasks/:id

Path Parameters

Parameter	Type	Description
`id`	`number`	The task ID

Updatable Fields

Field	Type	Description
`dropoffLocation`	`object`	Update the delivery address and coordinates
`notes`	`string`	Update delivery instructions
`scheduledAt`	`string`	Reschedule the delivery (ISO 8601)
`packages`	`array`	Update package details

Example Request

curl -X PATCH https://api.deliverty.com/api/v1/tasks/1042 \
  -H "x-api-key: dh_live_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Updated: Leave package at reception desk.",
    "dropoffLocation": {
      "address": "789 New Address St, Beirut",
      "latitude": 33.8900,
      "longitude": 35.5000
    }
  }'

Response: 200 OK — Returns the updated task object.

Update Restrictions

Tasks that have already been accepted by a courier (ACCEPTED, IN_TRANSIT) or reached a terminal state (COMPLETED, CANCELLED) cannot be updated. The API will return 409 Conflict.

Cancel Task

Cancel a task that has not yet been completed. A cancellation reason is required.

PUT /api/v1/tasks/:id/status

Cancellation uses the same status update endpoint. Set status to cancelled and provide a reason.

Path Parameters

Parameter	Type	Description
`id`	`number`	The task ID

Request Body

Field	Type	Required	Description
`status`	`string`	Yes	Target status. Use `cancelled` to cancel.
`reason`	`string`	No	Reason for the status change (recommended for cancellations)

Example Request

curl -X PUT https://api.deliverty.com/api/v1/tasks/1042/status \
  -H "x-api-key: dh_live_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cancelled",
    "reason": "Customer requested cancellation"
  }'

Response: 200 OK — Returns the task with status set to CANCELLED.

Cancellation Rules

Tasks can be cancelled from any non-terminal status (NEW through IN_TRANSIT). Once a task is COMPLETED or already CANCELLED, a cancellation attempt returns 409 Conflict. If a courier is already en route, cancellation triggers a notification to the assigned courier.

Filtering Examples

Here are some common query patterns:

All completed tasks for a customer

GET /api/v1/tasks?status=completed&customerId=87&sortBy=updatedAt&sortOrder=DESC

Tasks scheduled today

GET /api/v1/tasks?scheduledFrom=2026-02-16T00:00:00Z&scheduledTo=2026-02-16T23:59:59Z

In-transit deliveries, oldest first

GET /api/v1/tasks?status=in_transit&taskType=delivery&sortOrder=ASC

Paginated results (page 3, 50 per page)

GET /api/v1/tasks?page=3&limit=50

Real-Time Updates

Instead of polling the API for status changes, set up webhooks to receive real-time notifications when task status changes occur.