Create Task Endpoint

Task Types

Every task must have a taskType that defines the nature of the delivery operation:

Type	Value	Description
DELIVERY	delivery	Deliver items from a hub or pickup point to a customer's address.
PICKUP	pickup	Collect items from a location and bring them to a hub or warehouse.
RETURN	return	Return items from the customer back to the origin.
TRANSFER	transfer	Transfer items between two locations.

Request Body

The request body is a JSON object with the following structure:

Field	Type	Required	Description
name	string	Yes	Human-readable name for the task (e.g., "Delivery to Downtown")
taskType	string	Yes	Task type: delivery, pickup, return, or transfer
customer	object	Conditional	Inline customer object (see below). Mutually exclusive with customerId — provide one or the other.
customerId	number	Conditional	Reference to an existing customer. Mutually exclusive with customer.
location	object	Conditional	Inline location object (see below). Mutually exclusive with locationId.
locationId	number	Conditional	Reference to an existing location. Mutually exclusive with location.
channelId	number	No	Channel ID. If omitted, inherits from the API key's channel context.
timeToServe	string	No	When to serve: asap (default) or scheduled
scheduledAt	string	No	ISO 8601 date-time. Required when timeToServe is scheduled.
code	string	No	Custom task code (auto-generated if omitted)
notes	string	No	Additional instructions for the courier
packages	array	No	Array of inline package objects describing the items to deliver
packageIds	number[]	No	Array of existing package IDs to attach to the task
autoAssign	boolean	No	Automatically assign an available agent
preferredAgentId	number	No	Preferred agent ID for assignment

Customer Object

Field	Type	Required	Description
name	string	Yes	Full name of the customer
phone	string	Yes	Phone number with country code
email	string	No	Email address for notifications

Location Object

Field	Type	Required	Description
address	string	Yes	Human-readable address
latitude	number	Yes	Geographic latitude (-90 to 90)
longitude	number	Yes	Geographic longitude (-180 to 180)
building	string	No	Building name or number
floor	string	No	Floor number
apartment	string	No	Apartment or unit number

Package Object

Field	Type	Required	Description
description	string	Yes	Description of the package contents
weight	number	No	Weight in kilograms
quantity	number	No	Number of items (defaults to 1)
barcode	string	No	Package barcode or tracking number

Example Request

curl -X POST https://api.deliverty.com/api/v1/tasks \
  -H "x-api-key: dh_live_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Delivery to Hamra",
    "taskType": "delivery",
    "timeToServe": "asap",
    "customer": {
      "name": "Jane Smith",
      "phone": "+961 71 123 456",
      "email": "jane@example.com"
    },
    "location": {
      "address": "456 Hamra Street, Beirut",
      "latitude": 33.8886,
      "longitude": 35.4955,
      "building": "Marina Tower",
      "floor": "3",
      "apartment": "3B"
    },
    "packages": [
      {
        "description": "Electronics - Laptop",
        "weight": 2.5,
        "quantity": 1,
        "barcode": "PKG-2026-001234"
      }
    ],
    "notes": "Call customer before arrival. Fragile items."
  }'

Response

A successful request returns 201 Created with the task object wrapped in the standard response envelope:

{
  "statusIndicator": "SUCCESS",
  "statusCode": 201,
  "message": "Request processed successfully",
  "data": {
    "id": 1042,
    "name": "Delivery to Hamra",
    "code": "TSK-2026-001042",
    "taskType": "delivery",
    "status": "new",
    "timeToServe": "asap",
    "scheduledAt": "2026-02-16T12:30:00.000Z",
    "assignedAt": null,
    "acceptedAt": null,
    "startedAt": null,
    "completedAt": null,
    "description": null,
    "notes": "Call customer before arrival. Fragile items.",
    "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": null,
    "agent": null,
    "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:30:00.000Z",
    "isDelayed": false,
    "autoAssignmentStatus": "not_requested",
    "autoAssignmentFailureReason": null
  },
  "metadata": {
    "timestamp": "2026-02-16T10:30:00.123Z",
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "path": "/v1/tasks",
    "duration": 42
  }
}

Validation Errors

If required fields are missing or invalid, the API returns 400 Bad Request:

{
  "statusCode": 400,
  "message": [
    "taskType must be one of the following values: delivery, pickup, return, transfer",
    "name should not be empty",
    "customer or customerId must be provided"
  ],
  "error": "Bad Request",
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "path": "/v1/tasks",
    "method": "POST"
  }
}