---
updatedAt: 2026-05-27T10:18:53.000Z
agentTools:
  projectIndex: https://gethapn.readme.io/llms.txt
---

# Sets the imeis associated with a task schedule

Sets the imeis associated with a task schedule.
The list of devices can be empty, signaling that there will be no devices associated with the task schedule.

For repeating usage-based schedules, every device carries the starting value matching the
schedule's repeat type: startingActiveHours when the schedule repeats by intervalActiveHours,
startingOdometer when it repeats by intervalOdometer. Date-based and one-time schedules take
imei-only entries. Omitting the field keeps the value already stored for that device; an
explicit null clears it.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "description": "The Hapn API is an HTTP interface for managing devices, accounts, and cloud data.",
    "version": "1.0.0",
    "title": "Hapn API",
    "termsOfService": "https://gethapn.com/terms",
    "contact": {
      "name": "Dev",
      "email": "developer@gethapn.com",
      "url": "http://gethapn.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "https://api.iotgps.io/v1",
      "description": "Prod"
    },
    {
      "url": "https://api-dev.iotgps.io/v1",
      "description": "Dev"
    }
  ],
  "paths": {
    "/tasks/schedule/{taskScheduleId}/devices": {
      "post": {
        "summary": "Sets the imeis associated with a task schedule",
        "tags": [
          "Tasks"
        ],
        "operationId": "set-taskSchedule-devices",
        "description": "Sets the imeis associated with a task schedule.\nThe list of devices can be empty, signaling that there will be no devices associated with the task schedule.\n\nFor repeating usage-based schedules, every device carries the starting value matching the\nschedule's repeat type: startingActiveHours when the schedule repeats by intervalActiveHours,\nstartingOdometer when it repeats by intervalOdometer. Date-based and one-time schedules take\nimei-only entries. Omitting the field keeps the value already stored for that device; an\nexplicit null clears it.\n",
        "parameters": [
          {
            "name": "taskScheduleId",
            "in": "path",
            "required": true,
            "description": "The task schedule id",
            "schema": {
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "x-examples": {
                  "date-or-one-time-schedule": {
                    "devices": [
                      {
                        "imei": "123456789012"
                      },
                      {
                        "imei": "123456789013"
                      }
                    ]
                  },
                  "engine-hours-schedule": {
                    "devices": [
                      {
                        "imei": "123456789012",
                        "startingActiveHours": 1355
                      },
                      {
                        "imei": "123456789013",
                        "startingActiveHours": 980
                      }
                    ]
                  },
                  "odometer-schedule": {
                    "devices": [
                      {
                        "imei": "123456789012",
                        "startingOdometer": 48631
                      },
                      {
                        "imei": "123456789013",
                        "startingOdometer": 5088
                      }
                    ]
                  }
                },
                "properties": {
                  "devices": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/TaskScheduleDeviceInput"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Set task schedule devices result",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "object",
                          "properties": {
                            "taskScheduleId": {
                              "type": "number",
                              "description": "The task schedule identifier"
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "example-1": {
                    "value": {
                      "success": true,
                      "message": "ok",
                      "result": {
                        "taskScheduleId": 1
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/TaskScheduleNotFound"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "result": {
            "type": "object"
          }
        },
        "required": [
          "message",
          "success"
        ],
        "x-examples": {
          "example-1": {
            "value": {
              "success": true,
              "message": "ok",
              "result": {
                "imei": "12345"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "message"
        ],
        "x-examples": {
          "example-1": {
            "value": {
              "success": false,
              "message": "Unauthorized"
            }
          }
        }
      },
      "TaskScheduleDeviceInput": {
        "description": "A device to associate with a task schedule. Provide the starting value matching the schedule's repeat type for every device",
        "title": "Task schedule device input",
        "type": "object",
        "required": [
          "imei"
        ],
        "properties": {
          "imei": {
            "type": "string",
            "description": "The device imei"
          },
          "startingOdometer": {
            "type": "number",
            "nullable": true,
            "description": "Per-device odometer reading (in km) the repeating interval starts from. Required for every device when the schedule repeats by intervalOdometer. Overrides intervalStartingOdometer for this device. On updates, omit to keep the stored value; null clears it"
          },
          "startingActiveHours": {
            "type": "number",
            "nullable": true,
            "description": "Per-device hours of operation the repeating interval starts from. Required for every device when the schedule repeats by intervalActiveHours. Overrides intervalStartingActiveHours for this device. On updates, omit to keep the stored value; null clears it"
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "example-1": {
                "value": {
                  "success": false,
                  "message": "Unauthorized"
                }
              }
            }
          }
        }
      },
      "Error": {
        "description": "Server error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "example-1": {
                "value": {
                  "success": false,
                  "message": "Error"
                }
              }
            }
          }
        }
      },
      "TaskScheduleNotFound": {
        "description": "The specified resource was not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "example-1": {
                "value": {
                  "success": false,
                  "message": "Task schedule not found"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://auth.usehapn.com/oauth2/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Tasks",
      "description": "Maintenance tasks"
    }
  ],
  "security": [
    {
      "OAuth2": []
    }
  ]
}
```