Task 1 - Find or Invite a User
In this task, you find the user you want to assign a product to. If the person isn’t on your team yet, you invite them.
By the end of this task you will be able to:
- Find a team user by email address.
- Invite a person to your team.
- Retrieve a user by ID.
You will use the following operations in this task:
| Operation | HTTP request |
|---|---|
| List Team Users | GET /teams/{team-id}/users |
| Add Team User | POST /teams/{team-id}/users |
| Get Team User | GET /teams/{team-id}/users/{user-id} |
Step 1 - Find a user by email address
List the users of your team and filter by an exact email address. Only users whose email address matches exactly are returned.
In Postman, set lookup_email and run the Find a team user by exact email request. Replace the example email address with the address of the person you want to find. To list all users, leave out the email parameter.
The request
Postman sends this request with the collection’s authorization adding your access token. The following cURL command shows the structure of the request. You don’t need to run it.
curl -X GET \
'https://developer.api.autodesk.com/team-admin/v1/teams/<YOUR_TEAM_ID>/users?email=ada.lovelace@example.com&limit=50' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
Response
Postman shows a response like this:
{
"data": [
{
"id": "US1234567890",
"firstName": "Ada",
"lastName": "Lovelace",
"email": "ada.lovelace@example.com",
"role": "USER",
"isEmailVerified": true
}
],
"pagination": {
"cursor": null,
"hasMore": false
}
}
Each user has these fields:
id: the ID of the user. You use it in later requests.firstName,lastName, andemail: the user’s name and primary email address.role: the user’s role on the team, such asUSER.isEmailVerified: an account-registration indicator.falsemeans an account invitation or registration is pending. Don’t use this field as proof of email ownership or as the status of team membership.
If the person is on your team, note the id of the user and continue to Task 2. In later requests, this ID replaces <YOUR_USER_ID>. In Postman, set the user_id variable to it.
If data is empty, the person isn’t on the team. Continue with Step 2.
Step 2 - Invite a person to the team
Invite a person by email address. You must supply the email field. The firstName and lastName fields are optional. The API uses them only when the email address doesn’t belong to an existing Autodesk account.
Warning: This request invites a real person. Use an email address you control if you only want to try the operation.
In Postman, set invite_email and run the Invite team user - sends invitation request.
The request
Postman sends this request with the collection’s authorization adding your access token. The following cURL command shows the structure of the request. You don’t need to run it.
curl -X POST \
'https://developer.api.autodesk.com/team-admin/v1/teams/<YOUR_TEAM_ID>/users' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{"email":"ada.lovelace@example.com","firstName":"Ada","lastName":"Lovelace"}'
Response
A new user added to the team returns a 201 status code with the user in the response body:
{
"id": "US1234567890",
"firstName": "Ada",
"lastName": "Lovelace",
"email": "ada.lovelace@example.com",
"role": "USER",
"isEmailVerified": true
}
The response also includes a Location header that contains the path of the new user, for example /team-admin/v1/teams/100001/users/US1234567890.
Keep the following in mind:
- The team determines the user’s role. The new user is a
USERor anEXTERNAL_USER. You can’t choose the role. - The invitation might still need to be accepted.
- If the person is already on the team, the API returns a
200status code with the existing user and sends no new invitation. - You can invite users, but you can’t remove them from a team through the API.
Note the id in the response. In Postman, set the user_id variable to it.
Step 3 - Retrieve the user
To check the user, retrieve them by ID.
In Postman, run the Get one team user request.
The request
Postman sends this request with the collection’s authorization adding your access token. The following cURL command shows the structure of the request. You don’t need to run it.
curl -X GET \
'https://developer.api.autodesk.com/team-admin/v1/teams/<YOUR_TEAM_ID>/users/<YOUR_USER_ID>' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
Response
Postman shows a response like this:
{
"id": "US1234567890",
"firstName": "Ada",
"lastName": "Lovelace",
"email": "ada.lovelace@example.com",
"role": "USER",
"isEmailVerified": true
}
An ID that doesn’t belong to a user of the team returns a 404 status code.
See also
- Continue with Task 2 - Choose a Product Pool.