Managing teams and members

A simple guide to use APIs to manage teams and members of your account

Usually, when managing teams and members, APIs are not involved: one would use the UI in order to perform such tasks. However, in big organisations, and when no enterprise integrations are used, this may be required.

In order to use APIs to manage teams and members you will need an authorization token which is associated to an account administrator. You can do so from dashboard in the tokens section:

Once you have the token, you can simply use it in your calls, here there are few examples using "curl" assuming your token is in the environment variable METERIAN_API_TOKEN.

Managing members

To manage account members you will need to first get your account UUID as well. You can obtain it with this call:

curl -X GET "https://www.meterian.com/api/v1/accounts/me" \
-H "accept: application/json" -H "Authorization: token $METERIAN_API_TOKEN"

{"uuid":"d80d5f9c-a3b2-4ecb-9ce6-9891d4929bda","name":"Account of wombat group",...}

The UUID of your account in this case d80d5f9c-a3b2-4ecb-9ce6-9891d4929bda, let's put into another variable called ACCOUNT_UUID just for simplicity. Let's have a look to some examples of usage.

Adding a member to the account

To add a new member into the account just use the POST verb, passing the required data:

curl -X POST \
"https://www.meterian.com/api/v1/accounts/$ACCOUNT_UUID/members" \
-H "Content-Type: application/json" \
-H "Authorization: token $METERIAN_API_TOKEN" \
-d '{
    "email": "alan@example.com",
    "name": "Alan Example",
    "role": "Viewer"
}'

Listing account members

You can list account members to see that the member was added:

curl -X GET \
"https://www.meterian.com/api/v1/accounts/$ACCOUNT_UUID/members" \
-H "Authorization: token $METERIAN_API_TOKEN"

    {
        "email": "bruno.demo1@meterian.io",
        "name": "bruno.demo1@meterian.io",
        "role": "Administrator",
        "status": "Active",
        "uuid": "52a861fd-252e-45af-bcdc-d2586a0898e8"
    },
    {
        "email": "alan@example.com",
        "name": "Alan Example",
        "role": "Viewer",
        "status": "Active",
        "uuid": "dd2e5fea-0339-40e4-8e8f-987a7dbd565c"
    }
]

Removing account members

To remove a member just use the DELETE verb on the resource, specifying the member email:

curl -X DELETE \
"https://www.meterian.com/api/v1/accounts/$ACCOUNT_UUID/members/alan%40example.com" \
-H "Authorization: token $METERIAN_API_TOKEN"

Managing teams

If you have an enteprise account, or yu have the Teams feature enabled in your account, you can also manage teams. To create a team, you can execute a simple POST call using the REST APis:

curl -X POST "https://www.meterian.com/api/v1/teams" \
-H "Content-Type: application/json" \
-H "Authorization: token $METERIAN_API_TOKEN" \
-d '{ 
  "description": "All colleagues in the Manchester area", 
  "name": "Manchester",
  "active": true
}'

You will receive a 200 return code, and you will be able to see the new team, also via API, just asking for the list:

curl -X GET "https://www.meterian.com/api/v1/teams" \
-H "Content-Type: application/json" \
-H "Authorization: token $METERIAN_API_TOKEN" 

[
  {
    "accountUuid": "...",
    "uuid": "35e145db-418a-42fb-ac45-0f5a583a68fc",
    "name": "Manchester",
    "description": "All colleagues in the Manchester area",
    "active": true,
    "everyone": false
  },
  {
    "accountUuid": "...",
    "uuid": "...",
    "name": "Everyone",
    "description": "Every person in this account",
    "active": true,
    "everyone": true
  }
]

As you can see there's the default team "EVERYONE" and the newly created team. For semplicity, let's put the UUID of the team in the environment variable TEAM_UUID, we will need it in the next exaples.

If you made a mistake, you can delete the team using the UUID returned in the field of the object:

curl -X DELETE "https://www.meterian.com/api/v1/teams/$TEAM_UUID" \
-H "Authorization: token $METERIAN_API_TOKEN" 

Once a team is created, you can then add and remove members from such team

Adding a member to a team (and to the account)

You can use this style of call when you want to add a member that is not present in the account. This call will add the member to the EVERYONE team and to this specific team. It's advantageous as you won't need to do multiple calls. Let's imagine we want to add Alan, a viewer in the account (see the "membership" section of the data) and a collaborator in the team:

curl -X POST \
"https://www.meterian.com/api/v1/teams/$TEAM_UUID/members" \
-H "Content-Type: application/json" \
-H "Authorization: token $METERIAN_API_TOKEN" \
-d '{
  "membership": {
    "email": "alan@example.com",
    "name": "Alan Example",
    "role": "Viewer"
  },
  "role": "Collaborator"
}'

Listing team members

curl -X GET \
"https://www.meterian.com/api/v1/teams/$TEAM_UUID/members" \
-H "Authorization: token $METERIAN_API_TOKEN" 

[
    {
        "accountUuid": "35e145db-418a-42fb-ac45-0f5a583a68fc",
        "email": "alan@example.com",
        "name": "Alan Example",
        "role": "Collaborator",
        "uuid": "a6fc490b-5a08-492e-a4d9-f09b28701fda"
    }
]

Removing a member from a team

You can remove a member from a team as well (while leaving him in the account) using the member UUID and a DELETE call to the REST API:

curl -X DELETE \
"https://www.meterian.com/api/v1/teams/$TEAM_UUID/members/a6fc490b-5a08-492e-a4d9-f09b28701fda" \
-H "Authorization: token $METERIAN_API_TOKEN" 

Adding a member to a team (when the member is already in the account)

To add a member to a team when such member is already in the account is really easy if you now its UUID in the account. If not, you can get it with an API call:

$ curl -X GET \
"https://www.meterian.com/api/v1/accounts/$ACCOUNT_UUID/members" \
-H "Authorization: token $METERIAN_API_TOKEN" 

[
    {
        "accountUuid": "...",
        "email": "bruno.demo1@meterian.io",
        "name": "bruno.demo1@meterian.io",
        "role": "Administrator",
        "status": "Active",
        "uuid": "6962b35b-b739-4f61-9c9b-2b78dcad79d8"
    },
    {
        "accountUuid": "....",
        "email": "alan@example.com",
        "name": "Alan Example",
        "role": "Viewer",
        "status": "Pending",
        "uuid": "a6fc490b-5a08-492e-a4d9-f09b28701fda"
    }
]

Then you can simply add the REST call to add a member to a team, specifying the UUID:

curl -X POST \
"https://www.meterian.com/api/v1/teams/$TEAM_UUID/members" \
-H "Content-Type: application/json" \
-H "Authorization: token $METERIAN_API_TOKEN" \
-d '{
  "uuid": "a6fc490b-5a08-492e-a4d9-f09b28701fda",
  "role": "Collaborator"
}'

A simple tool: importing contacts from a CSV file

A simple Python script is available on GitHub as an easy to use tool to import contacts from a CSV file. It uses the APIs described in this guide, and can be used as it is, or as a staring point for your automation endeavours!

Just create a CSV file whith the required fields (full name, email address, role within the team, team name) and run the tool to import those users in your account.

You can access the script on GitHub.

What next?

Please be aware that all APIs are available via Swagger:

Any further question please drop a line to your support line!

Last updated