Skip to main content

Worked Example: Create a Unit

This walks through adding a tracking unit end-to-end, tying together authentication, the form-data pattern, and creation. Recall that a Unit is the physical device; it's later allocated to a Vehicle (see Data Model).

1. Authenticate​

curl -X POST https://www.acmdestiny.net/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"your-username","password":"your-password"}'
# → grab the token from the Authorization response header

2. Get the create-form data​

This returns the valid unit types, models, sensors and other option lists you'll need to supply a valid unit.

curl "https://www.acmdestiny.net/api/v1/units/create" \
  -H "Authorization: bearer YOUR_TOKEN"

3. (Optional) Check you're allowed to create here​

If you're scoping to a client, you can confirm permission first to avoid a predictable rejection:

curl "https://www.acmdestiny.net/api/v1/auth/permission/units/action/create?client_id=CLIENT_ID" \
  -H "Authorization: bearer YOUR_TOKEN"

4. Create the unit​

curl -X POST "https://www.acmdestiny.net/api/v1/units" \
  -H "Authorization: bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "imei": "350000000000001",
        "serial_no": "SN-0001"
        /* plus the type/model/etc. chosen from the create-form options */
      }'

A successful create returns the new unit in data; problems come back as warnings / warn_fields (see Errors).

5. Allocate it to a vehicle (when ready)​

Units are attached to vehicles through the Unit Swapping operations — e.g. Transfer to New Vehicle (Same Client). This keeps each vehicle's history intact when hardware is swapped or repaired.

tip

Check the exact field names and required values for your deployment on the Add Unit page in the API Reference — the create-form response is always the source of truth for valid options.