V5 User Teams

Last Modified on 01/28/2026 4:51 pm EST |

Page 1: AccountTeams Users Object v5

Note: The AccountTeams Users Object is only accessible to Account Administrator users.

The following API calls are currently available for the AccountTeams Users object:

  • GET LIST
  • ADD USERS
  • UPDATE USERS
  • DELETE USERS

GET LIST - Get a list of all users on a team.

https://api.alchemer.com/v5/accountteams/[TEAMID]/users

Note: Get requests will cache for 60 seconds. If you make repeated API get requests that are identical, the return will be cached and will thus return identical results.

ParametersExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345True
pagepage=2False
resultsperpageresultsperpage=100False

Response Example (.json format):

{
    "result_ok": true,
    "total_count": 2,
    "page": 1,
    "total_pages": 1,
    "results_per_page": 2,
    "data": [
        {
            "user_id": "938116",
            "username": "JF Testuser4",
            "email": "justin.falk+tu4@alchemer.com",
            "team_id": "1",
            "team_name": "Team 1",
            "is_team_manager": false,
            "role_id": "4",
            "role_name": "Editor"
        },
        {
            "user_id": "928117",
            "username": "Chris Minnich",
            "email": "chris.minnich+cid731671@alchemer.com",
            "team_id": "1",
            "team_name": "Team 1",
            "is_team_manager": false,
            "role_id": "4",
            "role_name": "Editor"
        }
    ]
}

ADD USERS - Add users to a team.

https://api.alchemer.com/v5/accountteams/[TEAMID]/users?_method=PUT&users=[JSON_ARRAY]
ParametersValue/ExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345True
usersJSON array of user objectsTrue

User Object Parameters:

ParameterDescriptionRequired
user_idThe user ID of the user to addTrue
role_idThe role ID of the role to assign (2-6 for standard roles)True
is_team_managerWhether the user is a team manager (true/false)False (defaults to false)

Request Example:

https://api.alchemer.com/v5/accountteams/123456/users?_method=PUT&api_token=abcd12345&api_token_secret=abcd12345&users=[{"user_id":"889312","role_id":"4","is_team_manager":true},{"user_id":"909455","role_id":"2"}]

Success Response Example (.json format):

{
    "result_ok": true,
    "code": 200,
    "message": "Added 2 users to team.",
    "data": [
        {
            "user_id": "889312",
            "result_ok": true,
            "code": 200,
            "message": "Added user to team."
        },
        {
            "user_id": "909455",
            "result_ok": true,
            "code": 200,
            "message": "Added user to team."
        }
    ]
}

Error Response Example (.json format):

{
    "result_ok": false,
    "code": 400,
    "message": "Failed to add all users to team. See data for details.",
    "data": [
        {
            "user_id": "889312",
            "result_ok": true,
            "code": 200,
            "message": "Added user to team."
        },
        {
            "user_id": "909455",
            "result_ok": false,
            "code": 400,
            "message": "Failed to add user to team. User id 909455 not found."
        }
    ]
}

UPDATE USERS - Update team properties for users on a team.

https://api.alchemer.com/v5/accountteams/[TEAMID]/users?_method=POST&users=[JSON_ARRAY]
ParametersValue/ExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345True
usersJSON array of user objectsTrue

User Object Parameters:

ParameterDescriptionRequired
user_idThe user ID of the user to updateTrue
role_idThe role ID to assign (2-6 for standard roles)False*
is_team_managerWhether the user is a team manager (true/false)False*

*At least one of role_id or is_team_manager is required.

Request Example:

https://api.alchemer.com/v5/accountteams/123456/users?_method=POST&api_token=abcd12345&api_token_secret=abcd12345&users=[{"user_id":"889312","role_id":"2","is_team_manager":false},{"user_id":"909455","role_id":"4"}]

Success Response Example (.json format):

{
    "result_ok": true,
    "code": 200,
    "message": "Updated 2 users on team.",
    "data": [
        {
            "user_id": "889312",
            "result_ok": true,
            "code": 200,
            "message": "Updated user on team."
        },
        {
            "user_id": "909455",
            "result_ok": true,
            "code": 200,
            "message": "Updated user on team."
        }
    ]
}

Error Response Example (.json format):

{
    "result_ok": false,
    "code": 400,
    "message": "Failed to update all users on team. See data for details.",
    "data": [
        {
            "user_id": "889312",
            "result_ok": true,
            "code": 200,
            "message": "Updated user on team."
        },
        {
            "user_id": "909455",
            "result_ok": false,
            "code": 400,
            "message": "Failed to update user. User is not a member of team id 123456."
        }
    ]
}

DELETE USERS - Remove users from a team.

https://api.alchemer.com/v5/accountteams/[TEAMID]/users?_method=DELETE&user_ids=[JSON_ARRAY]
ParametersValue/ExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345True
user_idsJSON array of user IDsTrue

Request Example:

https://api.alchemer.com/v5/accountteams/123456/users?_method=DELETE&api_token=abcd12345&api_token_secret=abcd12345&user_ids=["889312","909455"]

Alternative: JSON Body

You can also pass the user_ids as a JSON body:

{
    "user_ids": ["889312", "909455"]
}

If both query parameter and JSON body are provided, the query parameter takes precedence.

Success Response Example (.json format):

{
    "result_ok": true,
    "code": 200,
    "message": "Removed 2 users from team.",
    "data": [
        {
            "user_id": "889312",
            "result_ok": true,
            "code": 200,
            "message": "Removed user from team."
        },
        {
            "user_id": "909455",
            "result_ok": true,
            "code": 200,
            "message": "Removed user from team."
        }
    ]
}

Error Response Example (.json format):

{
    "result_ok": false,
    "code": 400,
    "message": "Failed to remove all users from team. See data for details.",
    "data": [
        {
            "user_id": "889312",
            "result_ok": true,
            "code": 200,
            "message": "Removed user from team."
        },
        {
            "user_id": "909455",
            "result_ok": false,
            "code": 400,
            "message": "Failed to remove user from team. User id 909455 not found."
        }
    ]
}

Page 2: AccountUser Teams Object v5

Note: The AccountUser Teams Object is only accessible to Account Administrator users.

The following API calls are currently available for the AccountUser Teams object:

  • GET LIST
  • ADD TEAMS
  • UPDATE TEAMS
  • DELETE TEAMS

GET LIST - Get a list of all teams for a user.

https://api.alchemer.com/v5/accountuser/[USERID]/teams

Note: Get requests will cache for 60 seconds. If you make repeated API get requests that are identical, the return will be cached and will thus return identical results.

ParametersExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345True
pagepage=2False
resultsperpageresultsperpage=100False

Response Example (.json format):

{
    "result_ok": true,
    "total_count": 2,
    "page": 1,
    "total_pages": 1,
    "results_per_page": 2,
    "data": [
        {
            "team_id": "1",
            "team_name": "Team 1",
            "user_id": "938116",
            "username": "JF Testuser4",
            "email": "justin.falk+tu4@alchemer.com",
            "is_team_manager": true,
            "role_id": "4",
            "role_name": "Editor"
        },
        {
            "team_id": "2",
            "team_name": "Team 2",
            "user_id": "938116",
            "username": "JF Testuser4",
            "email": "justin.falk+tu4@alchemer.com",
            "is_team_manager": false,
            "role_id": "2",
            "role_name": "Reporter"
        }
    ]
}

ADD TEAMS - Add a user to teams.

https://api.alchemer.com/v5/accountuser/[USERID]/teams?_method=PUT&teams=[JSON_ARRAY]
ParametersValue/ExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345True
teamsJSON array of team objectsTrue

Team Object Parameters:

ParameterDescriptionRequired
team_idThe team ID of the team to add the user toTrue
role_idThe role ID of the role to assign (2-6 for standard roles)True
is_team_managerWhether the user is a team manager (true/false)False (defaults to false)

Request Example:

https://api.alchemer.com/v5/accountuser/938116/teams?_method=PUT&api_token=abcd12345&api_token_secret=abcd12345&teams=[{"team_id":"1","role_id":"4","is_team_manager":true},{"team_id":"2","role_id":"2"}]

Success Response Example (.json format):

{
    "result_ok": true,
    "code": 200,
    "message": "Added user to 2 teams.",
    "data": [
        {
            "team_id": "1",
            "result_ok": true,
            "code": 200,
            "message": "Added user to team."
        },
        {
            "team_id": "2",
            "result_ok": true,
            "code": 200,
            "message": "Added user to team."
        }
    ]
}

Error Response Example (.json format):

{
    "result_ok": false,
    "code": 400,
    "message": "Failed to add user to all teams. See data for details.",
    "data": [
        {
            "team_id": "1",
            "result_ok": true,
            "code": 200,
            "message": "Added user to team."
        },
        {
            "team_id": "42",
            "result_ok": false,
            "code": 400,
            "message": "Team id 42 not found."
        }
    ]
}

UPDATE TEAMS - Update team properties for a user.

https://api.alchemer.com/v5/accountuser/[USERID]/teams?_method=POST&teams=[JSON_ARRAY]
ParametersValue/ExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345True
teamsJSON array of team objectsTrue

Team Object Parameters:

ParameterDescriptionRequired
team_idThe team ID of the team to updateTrue
role_idThe role ID to assign (2-6 for standard roles)False*
is_team_managerWhether the user is a team manager (true/false)False*

*At least one of role_id or is_team_manager is required.

Request Example:

https://api.alchemer.com/v5/accountuser/938116/teams?_method=POST&api_token=abcd12345&api_token_secret=abcd12345&teams=[{"team_id":"1","role_id":"2","is_team_manager":false},{"team_id":"2","role_id":"4"}]

Success Response Example (.json format):

{
    "result_ok": true,
    "code": 200,
    "message": "Updated user on 2 teams.",
    "data": [
        {
            "team_id": "1",
            "result_ok": true,
            "code": 200,
            "message": "Updated user on team."
        },
        {
            "team_id": "2",
            "result_ok": true,
            "code": 200,
            "message": "Updated user on team."
        }
    ]
}

Error Response Example (.json format):

{
    "result_ok": false,
    "code": 400,
    "message": "Failed to update user on all teams. See data for details.",
    "data": [
        {
            "team_id": "1",
            "result_ok": true,
            "code": 200,
            "message": "Updated user on team."
        },
        {
            "team_id": "3",
            "result_ok": false,
            "code": 400,
            "message": "Failed to update. User is not a member of team id 3."
        }
    ]
}

DELETE TEAMS - Remove a user from teams.

https://api.alchemer.com/v5/accountuser/[USERID]/teams?_method=DELETE&team_ids=[JSON_ARRAY]
ParametersValue/ExampleRequired
Authentication Credentialsapi_token=abcd12345&api_token_secret=abcd12345True
team_idsJSON array of team IDsTrue

Request Example:

https://api.alchemer.com/v5/accountuser/938116/teams?_method=DELETE&api_token=abcd12345&api_token_secret=abcd12345&team_ids=["1","3"]

Alternative: JSON Body

You can also pass the team_ids as a JSON body:

{
    "team_ids": ["1", "3"]
}

If both query parameter and JSON body are provided, the query parameter takes precedence.

Success Response Example (.json format):

{
    "result_ok": true,
    "code": 200,
    "message": "Removed user from 2 teams.",
    "data": [
        {
            "team_id": "1",
            "result_ok": true,
            "code": 200,
            "message": "Removed user from team."
        },
        {
            "team_id": "3",
            "result_ok": true,
            "code": 200,
            "message": "Removed user from team."
        }
    ]
}

Error Response Example (.json format):

{
    "result_ok": false,
    "code": 400,
    "message": "Failed to remove user from all teams. See data for details.",
    "data": [
        {
            "team_id": "1",
            "result_ok": true,
            "code": 200,
            "message": "Removed user from team."
        },
        {
            "team_id": "42",
            "result_ok": false,
            "code": 400,
            "message": "Failed to remove user from team. Team id 42 not found."
        }
    ]
}

Standard Roles Reference

The following standard role IDs are available:

Role IDRole Name
2Reporter
3Builder
4Editor
5Standard
6Admin

Custom roles will have IDs greater than 6.

Was this article helpful?
Thank you for your feedback!
© 2020 Alchemer LLC | All rights reserved.