Skip to navigation
SDK Techniques

Find Users Using the V3 SDK

Resolve a Benchling user from a username, a display name, or an API ID.

This recipe uses the V3 API through the V3 Python SDK. For creating, suspending, and reactivating users, see User Management via the API.

The V3 user endpoints are beta. Set early_access="true" on the client, as in the example below, or send the EARLY-ACCESS: true header on raw HTTP requests. See the V3 Stability Guidelines.

  1. SDK boilerplate

    Import the V3 SDK and instantiate the client. Pass your tenant’s root URL and your API key; the SDK adds /api/v3 itself.

  2. Look a user up with user.list()

    user.list() returns a pager that fetches pages as you iterate it. How you find the user depends on what you already know about them.

    1. By username

      user.list() has no username filter, so this walks the users and compares username on each one. page_size=100 is the maximum and keeps the number of requests down.

    2. By display name

      name_any_of_case_sensitive takes a list of full display names as they appear in Benchling. next(iter(...), None) returns the first match, or None if there isn’t one. Use name_any_of instead for a case-insensitive match.

  3. Look a user up by API ID

    Going the other direction, user.get() takes an API ID and returns the user, so you can read their username off it. This is a direct fetch rather than a filtered list, so there is no pager to iterate.

from benchling_v3_sdk import Benchling
benchling = Benchling(
    base_url="https://yourcompany.benchling.com",
    api_key="<your-api-key>",
    early_access="true",
)
username = "benchlingsupport"
def username_to_id(username):
    for user in benchling.user.list(page_size=100):
        if user.username == username:
            return user.id
    return None
print(username_to_id(username))
name = "Benchling Support"
def name_to_id(name):
    user = next(iter(benchling.user.list(name_any_of_case_sensitive=[name])), None)
    return user.id if user else None
print(name_to_id(name))
api_id = "ent_FooBar"
def id_to_username(api_id):
    user = benchling.user.get(api_id)
    return user.username
print(id_to_username(api_id))

What changed from V2

V2V3
benchling.users.list(handles=[...])No username filter. Iterate benchling.user.list() and compare username.
benchling.users.list(name=...)benchling.user.list(name_any_of=[...]) or name_any_of_case_sensitive=[...], up to 100 names per call.
benchling.users.get_by_id(id)benchling.user.get(id)
handleusername
isSuspended: true / falsestatus: "SUSPENDED" / "ACTIVE"

The other filters on user.list() are id_any_of and the modified_at_* range filters. There is no filter on email or status, so filter on those client-side.