Delivery Job Endpoints

These endpoints use organization-scoped API keys. Agent keys can only access jobs visible to the agent organization. Contractor keys can only access jobs visible to the contractor organization.

Authentication

Send one of these headers on every request.

x-api-key: shiplah_live_xxx

Authorization: Bearer shiplah_live_xxx

Common Types

Returns paginated delivery jobs visible to the API key's organization.

Query Parameters

Example Request

curl -H "x-api-key: shiplah_live_xxx" \
  "https://www.shiplahsg.com/api/v1/open-api/jobs?marking_number=MARK-001&page=1&page_size=10"

Response Data

{
  "items": [
    {
      "id": "job-id",
      "marking_number": "MARK-001",
      "batch_number": "BATCH-001",
      "group_code": "A1",
      "piece_quantity": 3,
      "labels": null,
      "pts": 1.5,
      "weight": 12.5,
      "recipient_name": "Jane Tan",
      "recipient_contact": "90000000",
      "delivery_address": "10 Test Road",
      "postal_code": "100001",
      "scheduled_date": "2026-05-21",
      "instructions": "Leave at reception",
      "normalized_status": "completed",
      "failure_reason": null,
      "scheduled_delivery_date": null,
      "scheduled_delivery_pending": false,
      "provider_status": "completed",
      "created_at": "2026-05-20T10:00:00.000Z",
      "updated_at": "2026-05-21T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total": 1
  }
}

Updates one delivery job by Marking Number.

Path Parameters

Request Body

Provide at least one editable field.

Example Request

curl -X PATCH \
  -H "content-type: application/json" \
  -H "x-api-key: shiplah_live_xxx" \
  -d '{"normalized_status":"completed","recipient_contact":"90000000"}' \
  "https://www.shiplahsg.com/api/v1/open-api/jobs/by-marking/MARK-001"

Updates up to 100 delivery jobs. Each item is matched by Marking Number.

Request Body

Example Request

{
  "jobs": [
    {
      "marking_number": "MARK-001",
      "normalized_status": "completed"
    },
    {
      "marking_number": "MARK-002",
      "failure_reason": "wrong_incomplete_address"
    }
  ]
}

Response Data

{
  "updated_count": 1,
  "failed_count": 1,
  "results": [
    {
      "marking_number": "MARK-001",
      "success": true,
      "job": {}
    },
    {
      "marking_number": "MARK-002",
      "success": false,
      "error": "Delivery job not found for Marking Number"
    }
  ]
}

Job Object Fields

Error Responses

Errors use the same response envelope with success: false.

{
  "request_id": "req_...",
  "success": false,
  "data": null,
  "error": {
    "code": "BadRequestException",
    "message": "No editable fields provided",
    "details": null
  }
}