Skip to main content

Staff Roles

Manage the roles that can be assigned to staff members (e.g., Guide, Instructor, Manager).

List Roles​

Get all staff roles for your account.

Endpoint​

GET /v1/staff/roles

Example Request​

curl -X GET "https://app.equipdash.com/api/v1/staff/roles" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response​

{
  "data": {
    "roles": [
      {
        "id": 1,
        "name": "Guide",
        "staff_count": 5,
        "created_at": "2026-01-01T00:00:00+00:00"
      },
      {
        "id": 2,
        "name": "Instructor",
        "staff_count": 3,
        "created_at": "2026-01-15T10:00:00+00:00"
      },
      {
        "id": 3,
        "name": "Manager",
        "staff_count": 2,
        "created_at": "2026-01-20T09:00:00+00:00"
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-01T10:00:00+00:00"
  }
}

Create Role​

Create a new staff role.

Endpoint​

POST /v1/staff/roles

Request Body​

FieldTypeRequiredDescription
namestringYesRole name (max 100 chars)

Example Request​

curl -X POST "https://app.equipdash.com/api/v1/staff/roles" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Technician"
  }'

Response​

{
  "data": {
    "id": 4,
    "name": "Technician",
    "staff_count": 0,
    "created_at": "2026-02-01T10:00:00+00:00"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-01T10:00:00+00:00"
  }
}

Update Role​

Update an existing staff role.

Endpoint​

PATCH /v1/staff/roles/{id}

Request Body​

FieldTypeRequiredDescription
namestringYesNew role name

Example Request​

curl -X PATCH "https://app.equipdash.com/api/v1/staff/roles/4" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Technician"
  }'

Response​

{
  "data": {
    "id": 4,
    "name": "Senior Technician",
    "staff_count": 0,
    "created_at": "2026-02-01T10:00:00+00:00"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-01T10:00:00+00:00"
  }
}

Delete Role​

Delete a staff role.

Endpoint​

DELETE /v1/staff/roles/{id}

Example Request​

curl -X DELETE "https://app.equipdash.com/api/v1/staff/roles/4" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response​

Returns 204 No Content on success.

Error Responses​

Role In Use​

{
  "error": {
    "code": "conflict",
    "message": "Cannot delete role. It is assigned to 3 staff member(s)."
  }
}

Cannot Delete Guide Role​

{
  "error": {
    "code": "conflict",
    "message": "The Guide role cannot be deleted."
  }
}

Assigning Roles to Staff​

When creating or updating a staff member, you can assign roles using the role_ids field:

Create Staff with Role​

curl -X POST "https://app.equipdash.com/api/v1/staff" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "role_ids": [1, 2]
  }'

Update Staff Roles​

curl -X PATCH "https://app.equipdash.com/api/v1/staff/123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role_ids": [1, 3]
  }'

Response with Roles​

{
  "data": {
    "id": 123,
    "first_name": "John",
    "last_name": "Doe",
    "roles": [
      {
        "id": 1,
        "name": "Guide"
      },
      {
        "id": 3,
        "name": "Manager"
      }
    ]
  }
}

Assigning Locations to Staff​

Assign work locations to staff members using main_location_id and location_ids:

Create Staff with Locations​

curl -X POST "https://app.equipdash.com/api/v1/staff" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "main_location_id": 1,
    "location_ids": [2, 3]
  }'

Update Staff Locations​

curl -X PATCH "https://app.equipdash.com/api/v1/staff/456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "main_location_id": 2,
    "location_ids": [1, 3]
  }'

Response with Locations​

{
  "data": {
    "id": 456,
    "first_name": "Jane",
    "last_name": "Smith",
    "main_location": {
      "id": 2,
      "name": "Downtown Store"
    },
    "locations": [
      {
        "id": 1,
        "name": "Main Warehouse",
        "is_main": false
      },
      {
        "id": 3,
        "name": "Beach Location",
        "is_main": false
      }
    ]
  }
}

Notes​

  • The "Guide" role is a system role and cannot be deleted
  • A role cannot be deleted while assigned to staff members
  • When updating staff roles/locations, the provided arrays replace existing assignments
  • Use GET /v1/settings/locations to get available location IDs