SearchUserProfiles

Searches user profiles using first name, last name, or user resource name filtering. Performs substring matching on user profile first and last names, or exact matching on user resource names within the authenticated group context.

Overview

Method Options

Authorisation specification of the SearchUserProfiles method.

Type	METHOD_TYPE_READ
Access Level	METHOD_ACCESS_LEVEL_AUTHORISED
Roles	ROLE_IAM_ADMIN ROLE_IAM_VIEWER ROLE_IAM_USER_PROFILE_ADMIN ROLE_IAM_USER_PROFILE_VIEWER

Parameters

Request and response parameter message overview:

Input: SearchUserProfilesRequest Message

Field	Type	Required	Description
FirstName	string	False	Optional substring to match against user profile first names. The search is case-insensitive.
LastName	string	False	Optional substring to match against user profile last names. The search is case-insensitive.
Users	string[]	False	Optional list of user resource names to filter by. Format: users/{ULIDv2}. When provided, only profiles associated with the specified users are returned.

Returns: SearchUserProfilesResponse Message

Field	Type	Description
UserProfiles	meshtrade.iam.user_profile.v1.UserProfile[]

Protobuf

syntax = "proto3";

package meshtrade.iam.user_profile.v1;

import "buf/validate/validate.proto";
import "google/protobuf/timestamp.proto";
import "meshtrade/iam/user_profile/v1/user_profile.proto";
import "meshtrade/option/method_options/v1/method_options.proto";

option go_package = "github.com/meshtrade/api/go/iam/user_profile/v1;user_profile_v1";
option java_package = "co.meshtrade.api.iam.user_profile.v1";

/*
   UserProfileService manages user profile information and preferences.

   User profiles contain display preferences, localization settings, and
   personalization data for authenticated users in the IAM system.
   Each profile is linked to a specific user and owned by a group.
*/
service UserProfileService {
  /*
     Updates an existing user profile.

     Allows modification of profile information including display name,
     profile picture, locale preferences, and currency settings.
     Only the fields provided in the request will be updated.

     Returns the updated UserProfile resource.
  */
  rpc UpdateUserProfile(UpdateUserProfileRequest) returns (UserProfile) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_USER_PROFILE_ADMIN
      ]
    };
  }

  /*
     Retrieves a user profile by its resource name.

     Fetches the complete user profile information including all
     preferences and settings for the specified user profile ID.

     Returns the requested UserProfile resource.
  */
  rpc GetUserProfile(GetUserProfileRequest) returns (UserProfile) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_USER_PROFILE_ADMIN,
        ROLE_IAM_USER_PROFILE_VIEWER
      ]
    };
  }

  /*
     Retrieves a user profile by the associated user resource name.

     Looks up and returns the user profile linked to a specific user ID.
     This is useful when you have a user resource and need to find
     their associated profile information.

     Returns the UserProfile resource associated with the specified user.
  */
  rpc GetUserProfileByUser(GetUserProfileByUserRequest) returns (UserProfile) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_USER_PROFILE_ADMIN,
        ROLE_IAM_USER_PROFILE_VIEWER
      ]
    };
  }

  /*
     Lists all user_profiles accessible to the caller.

     Returns a collection of all user_profiles within the caller's
     access scope based on group ownership and role permissions.

     Returns a ListUserProfilesResponse containing all accessible user_profiles.
  */
  rpc ListUserProfiles(ListUserProfilesRequest) returns (ListUserProfilesResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_USER_PROFILE_ADMIN,
        ROLE_IAM_USER_PROFILE_VIEWER
      ]
    };
  }

  /*
     Searches user profiles using first name, last name, or user resource name filtering.

     Performs substring matching on user profile first and last names,
     or exact matching on user resource names within the authenticated group context.
  */
  rpc SearchUserProfiles(SearchUserProfilesRequest) returns (SearchUserProfilesResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_VIEWER,
        ROLE_IAM_USER_PROFILE_ADMIN,
        ROLE_IAM_USER_PROFILE_VIEWER
      ]
    };
  }

  /*
     Retrieves a presigned upload URL for a user profile picture.

     Generates a temporary upload URL that can be used to upload
     a profile picture image. The URL expires after a short duration
     and should be used immediately for uploading the image file.

     Returns upload URL and expiration timestamp.
  */
  rpc GetUserProfilePictureUploadUrl(GetUserProfilePictureUploadUrlRequest) returns (GetUserProfilePictureUploadUrlResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_IAM_ADMIN,
        ROLE_IAM_USER_PROFILE_ADMIN
      ]
    };
  }
}

/*
   Request message for GetUserProfileByUser.

   Retrieves a user profile by specifying the associated user resource name.
*/
message GetUserProfileByUserRequest {
  /*
     The resource name of the user whose profile should be retrieved.
     Format: users/{ULIDv2}.
     This field is required.
  */
  string user = 1 [(buf.validate.field) = {
    required: true
    string: {
      min_len: 1
      pattern: "^users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
    cel: {
      id: "user.required"
      message: "user is required and must be in format users/{ULIDv2}"
      expression: "size(this) > 0"
    }
    cel: {
      id: "user.format"
      message: "name must be in format users/{ULIDv2} where ulidv2 is exactly 26 uppercase alphanumeric characters"
      expression: "this.matches('^users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$')"
    }
  }];
}

/*
   Request message for UpdateUserProfile.

   Updates an existing user profile. Only the fields provided
   in the user_profile will be updated; omitted fields remain unchanged.
*/
message UpdateUserProfileRequest {
  /*
     The user profile with updated values.
     The name field must be set to identify which profile to update.
     Only provided fields will be modified.
  */
  UserProfile user_profile = 1 [(buf.validate.field) = {required: true}];
}

/*
   *
     Request message for GetUserProfile.

     Retrieves a specific user profile by its resource name.
*/
message GetUserProfileRequest {
  /*
     The resource name of the user profile to retrieve.
     Format: iam/user_profiles/{ULIDv2}.
     This field is required.
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {
      min_len: 1
      pattern: "^iam/user_profiles/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
    cel: {
      id: "name.required"
      message: "name is required and must be in format iam/user_profiles/{ULIDv2}"
      expression: "size(this) > 0"
    }
    cel: {
      id: "name.format"
      message: "name must be in format iam/user_profiles/{ULIDv2} where ulidv2 is exactly 26 uppercase alphanumeric characters"
      expression: "this.matches('^iam/user_profiles/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$')"
    }
  }];
}

/*
   Request message for ListUserProfiles.

   Lists all user profiles accessible to the caller based on
   their role permissions and group ownership.
*/
message ListUserProfilesRequest {}

/*
   Response message for ListUserProfiles.

   Contains the collection of user profiles accessible to the caller.
*/
message ListUserProfilesResponse {
  /*
     The list of user profiles.
     Ordered by creation time, with most recent first.
  */
  repeated UserProfile user_profiles = 1;
}

/*
   Request message for GetUserProfilePictureUploadUrl.

   Requests a presigned URL for uploading a profile picture for
   the specified user profile.
*/
message GetUserProfilePictureUploadUrlRequest {
  /*
     The resource name of the user profile to upload a picture for.
     Format: iam/user_profiles/{ULIDv2}.
     This field is required.
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {
      min_len: 1
      pattern: "^iam/user_profiles/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
    cel: {
      id: "name.required"
      message: "name is required and must be in format iam/user_profiles/{ULIDv2}"
      expression: "size(this) > 0"
    }
    cel: {
      id: "name.format"
      message: "name must be in format iam/user_profiles/{ULIDv2} where ulidv2 is exactly 26 uppercase alphanumeric characters"
      expression: "this.matches('^iam/user_profiles/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$')"
    }
  }];
}

/*
   Response message for GetUserProfilePictureUploadUrl.

   Contains the presigned upload URL and its expiration time.
*/
message GetUserProfilePictureUploadUrlResponse {
  /*
     The presigned URL for uploading the profile picture.
     This URL should be used immediately with a PUT request to upload the image.
  */
  string upload_url = 1;

  /*
     The timestamp when the upload URL expires.
     After this time, the URL will no longer be valid for uploading.
  */
  google.protobuf.Timestamp expires_at = 2;
}

/*
   Request message for SearchUserProfiles.

   Searches user profiles by first name or last name substring matching.
*/
message SearchUserProfilesRequest {
  /*
     Optional substring to match against user profile first names.
     The search is case-insensitive.
  */
  string first_name = 1 [(buf.validate.field) = {
    string: {max_len: 255}
  }];

  /*
     Optional substring to match against user profile last names.
     The search is case-insensitive.
  */
  string last_name = 2 [(buf.validate.field) = {
    string: {max_len: 255}
  }];

  /*
     Optional list of user resource names to filter by.
     Format: users/{ULIDv2}.
     When provided, only profiles associated with the specified users are returned.
  */
  repeated string users = 3 [(buf.validate.field) = {
    repeated: {
      max_items: 100
      items: {
        string: {
          pattern: "^users/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
        }
      }
    }
  }];
}

/*
   Response message for SearchUserProfiles.

   Contains the collection of user profiles matching the search criteria.
*/
message SearchUserProfilesResponse {
  repeated UserProfile user_profiles = 1;
}

Code Examples

Select supported SDK in the language of your choice for a full example of how to invoke the this method:

Go

package main

import (
	"context"
	"log"

	user_profilev1 "github.com/meshtrade/api/go/iam/user_profile/v1"
)

func main() {
	ctx := context.Background()

	// Default configuration is used and credentials come from MESH_API_CREDENTIALS
	// environment variable or default discovery methods. Zero config required
	// unless you want custom configuration.
	service, err := user_profilev1.NewUserProfileService()
	if err != nil {
		log.Fatalf("Failed to create service: %v", err)
	}
	defer service.Close()

	// Search user profiles by last name
	request := &user_profilev1.SearchUserProfilesRequest{
		LastName: "Smith",
	}

	// Call the SearchUserProfiles method
	response, err := service.SearchUserProfiles(ctx, request)
	if err != nil {
		log.Fatalf("SearchUserProfiles failed: %v", err)
	}

	for _, profile := range response.UserProfiles {
		log.Printf("Found: %s %s (%s)", profile.FirstName, profile.LastName, profile.Name)
	}
}

Python

from meshtrade.iam.user_profile.v1 import (
    SearchUserProfilesRequest,
    UserProfileService,
)


def main():
    # Default configuration is used and credentials come from MESH_API_CREDENTIALS
    # environment variable or default discovery methods. Zero config required
    # unless you want custom configuration.
    service = UserProfileService()

    with service:
        # Search user profiles by last name
        request = SearchUserProfilesRequest(last_name="Smith")

        # Call the SearchUserProfiles method
        response = service.search_user_profiles(request)

        for profile in response.user_profiles:
            print(f"Found: {profile.first_name} {profile.last_name} ({profile.name})")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.iam.user_profile.v1.UserProfileService;
import co.meshtrade.api.iam.user_profile.v1.Service.SearchUserProfilesRequest;
import co.meshtrade.api.iam.user_profile.v1.Service.SearchUserProfilesResponse;
import co.meshtrade.api.iam.user_profile.v1.UserProfile.UserProfile;

import java.util.Optional;

public class SearchUserProfilesExample {
    public static void main(String[] args) {
        // Default configuration is used and credentials come from MESH_API_CREDENTIALS
        // environment variable or default discovery methods. Zero config required
        // unless you want custom configuration.
        try (UserProfileService service = new UserProfileService()) {
            // Search user profiles by last name
            SearchUserProfilesRequest request = SearchUserProfilesRequest.newBuilder()
                .setLastName("Smith")
                .build();

            // Call the SearchUserProfiles method
            SearchUserProfilesResponse response = service.searchUserProfiles(request, Optional.empty());

            for (UserProfile profile : response.getUserProfilesList()) {
                System.out.println("Found: " + profile.getFirstName() + " " + profile.getLastName() + " (" + profile.getName() + ")");
            }
        } catch (Exception e) {
            System.err.println("SearchUserProfiles failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Advanced Configuration

For advanced client configuration options (custom endpoints, TLS settings, timeouts), see the SDK Configuration Guide.

Other Methods

• Iam User Profile v1 Method List - For Other methods