Request

Response

    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:

    OperationHTTP 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
      }
    }
    
    Show More

    Each user has these fields:

    • id: the ID of the user. You use it in later requests.
    • firstName, lastName, and email: the user’s name and primary email address.
    • role: the user’s role on the team, such as USER.
    • isEmailVerified: an account-registration indicator. false means 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
    }
    
    Show More

    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 USER or an EXTERNAL_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 200 status 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
    }
    
    Show More

    An ID that doesn’t belong to a user of the team returns a 404 status code.

    See also