Skip to main content

Create a tasking request

Create a new tasking request (API Order) by resolving catalog options, then calling CreateOrder with "serviceID": 3 (the Tasking service ID).

Prerequisites​

  • Valid access token with earthlife.orders (Authentication)
  • Tasking uses "serviceID": 3; other cartItemDataList keys come from your EarthLife catalog/services configuration
  • Target location as GeoJSON (stringified in dataValue), commonly a POI Point
  • Gateway: https://earthlife.sarsatx.com/gateway

:::note Placeholders "serviceID": 3 is the Tasking service. Choose ImageTypeID and ImageResolutionID from the catalog lookups (active IDs only) before calling production. :::

1. Obtain a token​

curl -X POST "https://earthlife.sarsatx.com/auth/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=earthlife-tasking-api" \
  -d "username=user@example.com" \
  -d "password=YOUR_PASSWORD" \
  -d "scope=openid profile email roles offline_access earthlife.orders" \
  -d "culture=en"
export ACCESS_TOKEN="CfDJ8A..."

2. Load catalog options​

curl -X GET "https://earthlife.sarsatx.com/gateway/order/Lookup/GetImageTypesList" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json"
curl -X GET "https://earthlife.sarsatx.com/gateway/order/Lookup/GetImageResolutions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json"

Pick an active imageTypeID ("isActive": true) and an active imageResolutionID ("isActive": true) for the create body. Do not use inactive resolution IDs.

3. Create the request​

Include paymentMethod in the query string (use 1 in the examples below). note and refNo are optional.

curl -X POST "https://earthlife.sarsatx.com/gateway/order/Order/CreateOrder?note=&refNo=0&paymentMethod=1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "serviceID": 3,
    "cartItemDataList": [
      {
        "dataKey": "POI",
        "dataValue": "{\"type\":\"Point\",\"coordinates\":[39.293687516,21.557888091]}"
      },
      {
        "dataKey": "ImageResolutionID",
        "dataValue": "<imageResolutionID from catalog>"
      },
      {
        "dataKey": "FirstImageDate",
        "dataValue": "2026-09-14T09:00:00.000Z"
      },
      {
        "dataKey": "SecondImageDate",
        "dataValue": "2026-09-15T09:00:00.000Z"
      },
      {
        "dataKey": "ImageTypeID",
        "dataValue": "<imageTypeID from catalog>"
      },
      {
        "dataKey": "ImageProviderID",
        "dataValue": "auto"
      },
      {
        "dataKey": "CloudCover",
        "dataValue": "30"
      }
    ]
  }'

Success​

{
  "IsSuccess": true,
  "Message": null,
  "ReturnedValue": {
    "OrderData": {
      "OrderID": 694,
      "UserID": 42,
      "OrderStatusID": 1,
      "OrderStatusTitle": "Pending",
      "PaymentMethodTypeID": 1,
      "OrganizationPaymentType": 1,
      "PaymentMethodTypeTitle": "Subscription",
      "UUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "OrderNo": "ORD-2026-0694",
      "RefNo": "0",
      "Price": 0,
      "Tax": 0,
      "NetPrice": 0,
      "Note": null,
      "OrderDate": "2026-09-13T08:00:00Z",
      "AddedBy": "user@example.com",
      "OrderItems": []
    },
    "HasSubscription": true,
    "PaymentURL": ""
  }
}

Persist OrderID (and OrderNo if you display it) for later listing and detail calls.

Failure: business validation​

HTTP may still be 200 when creation is rejected:

{
  "IsSuccess": false,
  "Message": "Invalid service configuration or missing required inputs.",
  "ReturnedValue": null
}

Failure: unauthorized​

Missing or expired token → HTTP 401. Refresh and retry.

Body field notes​

FieldNotes
serviceID3 = Tasking service (required for tasking orders)
cartItemDataListString dataKey / dataValue pairs for location, catalog, and capture inputs
POIStringified GeoJSON Point (coordinates: [lon, lat])
ImageTypeID / ImageResolutionIDActive IDs from catalog lookups
FirstImageDate / SecondImageDateCapture window timestamps (ISO-8601)
ImageProviderIDProvider selection (example: auto)
CloudCoverMax cloud cover as a string (example: 30)

The gateway accepts camelCase JSON as shown. Schema docs may also list PascalCase property names (ServiceID, CartItemDataList, …).

Next steps​