Team controls the access to the sites; only its members are allowed to access them. Use Teams API to manage team membership, and create/get/update/delete a team for a member.

The team object

name type description
id string team identifier
name string team name
members array array of member objects
sites array array of accessible site objects

The member object

name type description
userId string user email address or phone number
role string member role. Possible values are admin or member

Create team

Create a team. The authenticated user (me) will be automatically added to the team as an admin.

Endpoints

POST /teams

Parameters

name type description
name string team name

Request Example

curl -X POST
     -H "Authorization: Bearer <access_token>"
     -H "accept-version: 2.0.0"
     -H "Content-Type: application/json"
     -d '{ "name": "team1" }'
     "https://api2.enertalk.com/teams"

Response

Created team object on success, or error on failure.

Response Example

{
  "id": "1a2b3c4d",
  "name": "team1",
  "members" : [
    {
      "userId": "me@enertalk.com",
      "role": "admin",
    }
  ],
  "sites": []
}

List teams

List all teams where authenticated user is a member.

Endpoints

GET /teams

Request Example

curl -X GET
     -H "Authorization: Bearer <access_token>"
     -H "accept-version: 2.0.0"
     "https://api2.enertalk.com/teams"

Response

List of teams on success, or error on failure.

Response Example

[
  {
    "id": "1a2b3c4d",
    "name": "team1",
    "members" : [
      {
        "userId": "me@enertalk.com",
        "role": "admin",
      }
    ],
    "sites": [
      {
        "id": "a1b2c3d4",
        "name": "team site",
        "latitude": null,
        "longitude": null,
        "timezone": "Asia/Seoul",
        "createdAt": 1485270230604,
        "country": "US",
        "zipcode": null,
        "description": null
      }
    ]
  }
]

Get team

Retrieve a team information. If authenticated user is not a member, forbidden error will be returned.

Endpoints

GET /teams/:teamId

Parameters

name type description
teamId string (required) team identifier

Request Example

curl -X GET
     -H "Authorization: Bearer <access_token>"
     -H "accept-version: 2.0.0"
     "https://api2.enertalk.com/teams/1a2b3c4d"

Response

Retrieved team object on success, or error on failure.

Response Example

{
  "id": "1a2b3c4d",
  "name": "team1",
  "members" : [
    {
      "userId": "me@enertalk.com",
      "role": "admin",
    }
  ],
  "sites": [
    {
      "id": "a1b2c3d4",
      "name": "team site",
      "latitude": null,
      "longitude": null,
      "timezone": "Asia/Seoul",
      "createdAt": 1485270230604,
      "country": "US",
      "zipcode": null,
      "description": null
    }
  ]
}

Update team

Update team information.

Endpoints

PATCH /teams/:teamId

Parameters

name type description
teamId string (required) team identifier
name string (required) team name to be set

Request Example

curl -X PATCH
     -H "Authorization: Bearer <access_token>"
     -H "accept-version: 2.0.0"
     -H "Content-Type: application/json"
     -d '{"name": "team2"}'
     "https://api2.enertalk.com/teams/1a2b3c4d"

Response

Updated team object on success, or error on failure.

Response Example

{
  "id": "1a2b3c4d",
  "name": "team2",
  "members" : [
    {
      "userId": "me@enertalk.com",
      "role": "admin",
    }
  ],
  "sites": [
    {
      "id": "a1b2c3d4",
      "name": "team site",
      "latitude": null,
      "longitude": null,
      "timezone": "Asia/Seoul",
      "createdAt": 1485270230604,
      "country": "US",
      "zipcode": null,
      "description": null
    }
  ]
}

Delete team

Delete a team. Only admin user can delete a team if there are no sites attached to the team.

Endpoints

DELETE /teams/:teamId

Parameters

name type description
teamId string (required) team identifier

Request Example

curl -X DELETE
     -H "Authorization: Bearer <access_token>"
     -H "accept-version: 2.0.0"
     "https://api2.enertalk.com/teams/1a2b3c4d"

Response

Deleted team id on success, error on failure

Response Example

{
  "id": "1a2b3c4d",
}

Add team member

Add a user to a team, or update member role. Note that you are not allowed to update role for last admin of a team.

Endpoints

PUT /teams/:teamId/memberships

Parameters

name type description
teamId string (required) team identifier
userId string (required) email address or phone number of the user to be added
role string role of member to be added. admin or member. default: member

Request Example

curl -X POST
     -H "Authorization: Bearer <access_token>"
     -H "accept-version: 2.0.0"
     -H "Content-Type: application/json"
     -d '{"userId": "you@enertalk.com" }'
     "https://api2.enertalk.com/teams/1a2b3c4d/memberships"

Response

Team object with newly added member on success, or error on failure.

Response Example

{
  "id": "1a2b3c4d",
  "name": "team1",
  "members" : [
    {
      "id": "me@enertalk.com",
      "role": "admin",
    },
    {
      "id": "you@enertalk.com",
      "role": "member",
    }
  ],
  "sites": [
    {
      "id": "a1b2c3d4",
      "name": "team site",
      "latitude": null,
      "longitude": null,
      "timezone": "Asia/Seoul",
      "createdAt": 1485270230604,
      "country": "US",
      "zipcode": null,
      "description": null
    }
  ]
},

Remove member

Remove a member from a team. Either admin can remove a member, or a member can remove oneself. If the only admin in a team tries to remove oneself, forbidden error will be returned.

Endpoints

DELETE /teams/:teamId/memberships

Parameters

name type description
teamId string (required) team identifier
userId string email address or phone number of a member to be removed. Not required to remove oneself.

Request Example

curl -X DELETE
     -H "Authorization: Bearer <access_token>"
     -H "accept-version: 2.0.0"
     -d '{ "userId": "you@encoredtech.com" }'
     "https://api2.enertalk.com/teams/1a2b3c4d/memberships"

Response

Team object with requested member removed on success, or error on failure.

Response Example

{
  "id": "1a2b3c4d",
  "name": "team1",
  "members" : [
    {
      "id": "me@enertalk.com",
      "role": "admin",
    }
  ],
  "sites": [
    {
      "id": "a1b2c3d4",
      "name": "team site",
      "latitude": null,
      "longitude": null,
      "timezone": "Asia/Seoul",
      "createdAt": 1485270230604,
      "country": "US",
      "zipcode": null,
      "description": null
    }
  ]
}